2015

Arduino Total Control Manual

Juan Luis Gonzalez

EMIM
1/1/2015

Index
1. What is Arduino Total control?
2. Arduino Total Control Main features
3. Communicating with the app
a. Sending data from app to Arduino overview
b. Sending data from Arduino to App overview
i. Displaying data on top of the app
c. Communication tags
i. Text tags
ii. Button tags
iii. Image tags
iv. Seek Bars
d. Communication via Bluetooth (click here for common issues)
i. Using Connection manager to connect multiple devices
ii. Using auto connect to connect one single device
iii. Arduino circuitry
iv. Arduino Sketch
e. Communication via WiFi (click here for common issues)
i. Setting up WiFi connection
1. Setting IP or address
2. Setting TCP Port
ii. Using auto connect
iii. Arduino circuitry
iv. Arduino sketch
4. Setting up a layout
a. Editing Pictures
i. Setting picture visibility
ii. Setting pictures as push buttons
iii. Setting commands
iv. Setting images displayed
1. Setting Default State (State 0)
2. Setting Pressed State (State 1)
3. Setting Extra State (State 2)
b. Editing Text
i. Setting text visibility
ii. Setting text content
iii. Enabling text as sensor source
c. Editing Button
i. Setting button visibility
ii. Setting commands
d. Setting Emphasis Color
e. Setting Layout orientation
f. Enabling layout scroll
g. Switching layouts
5. FAQ

What is Arduino Total Control

Arduino Total Control (ATC) is an app which enables your smartphone to control your makings and surroundings via
Bluetooth and WiFi. Build up to 4 different layouts, control up to 24 x 2 circuits on 7 different devices at the same time,
take pictures of what you want to control or choose a picture from your gallery and have fun controlling and switching
your circuits.
Arduino was chosen as firmware platform since it based on easy to use hardware and software, thus encouraging the
growing of the makers community.
Arduino Total Control can be fully customized. You can manage the layout as you like the most! Using its Matrix like
layout, just hide and show elements to form different layouts, from a remote control for your home lighting automation,
through a smartphone controlled robotic arm to a smart RC Car.

Images: visual dynamic indicators and / or push buttons (with editable commands)
Text Tags, Can be used as descriptors, as sensor sources, or to display data from Arduino
Toggle Buttons (with editable commands)

ATC is a window between your smartphone or tablet and your physical surroundings using Bluetooth or WiFi. In other
words, ATC will let you share information between your mobile device (like accelerometer, button strokes, touches
events, etc.) and your microcontroller based system (systems states, physical sensors data, internal program values,
etc.).

Arduino Total Control Main Features

1. Connect and control multiple devices at a time on four different layouts
Connect via WiFi or
Share data from 7 different devices; build your own Bluetooth personal network.
Different layouts for multiple projects.
2. Dynamic visual indicators
Images have three states which can be set via Camera or Gallery and controlled from Arduino commands or App
events.
Descriptor texts can be modified from Arduino commands
Toggle button state can be set from Arduino commands, providing real feedback.
3. Fully Customizable
From colors to layout arrangement, ATC can be set up for controlling or monitoring any kind of system, it is and
Human Machine Interface for smartphones and tablets.

Communicating with the app

For either Bluetooth or WiFi communication, sharing data between the app and the Arduino board is as easy as using a
serial terminal.
The way of sending data is exactly the same when the app runs on Bluetooth or WiFi.

For Bluetooth: Serial.println(.

For WiFi: server.println(

The same applies when data is received from the app, for more details please refer to the following sections of this
manual.

For Bluetooth: Serial.available()

For WiFi: server.available()

Sending data from app to Arduino overview

There are three cases when the app will send data to Arduino:
1. Character [ is sent every 2.5 seconds in order to let the microcontroller know we are still connected
2. Any character or string send by buttons or push buttons
3. Character < means that the following data will be a special command. The current special commands are
accelerometer data and seek bar information:
a. <AccelX
b. <AccelY
c. <AccelZ
d. <Skb07
e. More special commands will be included in the future.

Sending data from Arduino to App overview

Arduino can control pictures, buttons and text via special commands called Tags:

<ImgsXX:Y. You can change picture state by sending the appropriate command tag.
<TextXX:Any string. Text content can be changed via Arduino. Use this feature to display information (e.g.
sensor data).
<ButnXX:Z. Arduino can control buttons states (ON, OFF) via these command tags.

Where:
XX is the object/relay number from 00...0923.
Y is the state of the image XX, it can be 0, 1, or 2 for Default, Pressed and Extra state respectively
Z is the state of the button XX. On: 1, Off: 0.
Any string is the information that will be displayed as Text XX content.

Displaying data on top of the app

To display data in top of the app (next to the green connected text) just print any string followed by a new line character.
Any of the following will do the trick.

println(Any string);
print(Any string \n);

Figure 1 Displaying ATC Online text on top of the app

Communication tags
Communication tags are special strings sent to the app which activate special features of the app. In other words,
communication tags let you control your layout behavior via Arduino.

Text tags
Use text tags to modify text content on app:

<TextXX:Any String

Where:

XX, from 00 to 23 is the text number

Any String is the string to be displayed
Example: Serial.println ("<Text01:A1: 253"); will display "A1: 253" at Text 1.

Figure 2 Result of sending photo resistor data: Serial.println(<Text01:Lum: 560);

Button tags
Use Button tags to button state on app:

<ButnXX:Z

Where:

XX, from 00 to 23 is the text number

Z 0 or 1 is the button state
Example: server.println ("<Butn05:1 "); will turn the app button 5 on.

Image tags
Use Button tags to button state on app:

<ImgsXX:Y

XX, from 00 to 23 is the text number

Y 0, 1, or 2 for Default, Pressed and Extra state respectively
Example: Serial.println ("<Imgs02:1 "); will change image 2 to the pressed state.

Figure 3 Example of Image Tag use: Serial.println(<Imgs00:0); (left) and Serial.println (<Imgs00:1); (right)

Seek Bars
Seek bars emulate analog controls or dimmers. Seek bars send data to Arduino in tag format:

Figure Example of two seek bars at different values

<SkbX:SYYYYY
X, from 0 to 7, is the seek-bar number.
YYYYY from 00000 to 00255 is the seek bar value.
S Is the value sign (+ or -)
Communication via Bluetooth
Arduino Total Control supports any Bluetooth Serial Port Profile enabled device. Most Bluetooth modules will only need
a serial TTL port for communicating with Arduino. This mean you will need a TX and a RX pin, which are available from
any Arduino.

Figure 4 A commonly used Bluetooth module.

Before using Bluetooth, please open App menu and check BT Enable box to allow Bluetooth communication.

Figure 5 Enabling Bluetooth Communication via ATC App

Arduino circuitry
In most cases, the basic communication circuit is well represented by the following

Connect Bluetooth board Vcc to 5V or 3.3V

Connect Bluetooth board GND to Arduino GND
Connect Bluetooth Rx to Arduino Tx
Connect Bluetooth Tx to Arduino Rx.

Figure 6 Basic Arduino Bluetooth circuitry. Check your BT module back for correct wiring

Arduino Sketch
The most recent, proven and functional Arduino sketch can be found in the app. Open app menu then touch Arduino
Code then select Beginner Code. You can also check our Facebook pages for some early releases and examples:
https://www.facebook.com/ArduinoTotalControlApp
There are some warnings to take into account when downloading the Sketch into your Arduino board!!!

Disconnect Bluetooth modules TX when downloading, then reconnect.

Set the correct baud rate for your board. Most boards default is 9600 bits/second which is the default in the
Beginner sketch. Change it looking for the #define BAUD_RATE and setting your correct number.
Connect your Bluetooth on the correct serial port. ATC for Bluetooth uses Serial by default. If using mega or
other Arduino having more than one serial port, you can change the serial port used changing every Serial to
Serial1,2, or 3.
Dont use Pin 0 and 1 as inputs/Outputs since they will be used as serial port TX and RX.
Select your correct board and COM port for programming.

Once you have programmed your Arduino and paired your Bluetooth module with your Android powered device, you
can connect either via connection manager or auto-connect.

Using Connection manager to connect multiple devices

If you want to connect more than one device at a time, open app Menu, then click on Connection Manager. From now
on, for each image, button or seek bar you press the dialog shown in figure 7 will appear. All paired devices which
support Serial Port Profile will be listed.

Figure 7 Connection manager dialog

Select all devices you want to send the button or Picture data to. You can select more than one or all devices.
Once you have set every element, button or picture connection management, connect to the actual devices using the
connect button next to app title. The next dialog will appear.

Figure 8 Bluetooth Connect dialog

Note: Accelerometer data (if enabled) will be sent to all connected Bluetooth devices

Using auto connect to connect one single device

When only one device is required, uses Auto connect to connect all objects to this device.

Figure 9 Auto connect enabled

Note: Unchecking Auto Connect will reset the auto connect MAC address.

Communication via WiFi

Arduino Total Control supports connection via WiFi using an Arduino as a TCP/IP Server. In order to connect, you will
need either an Ethernet shield connected to a WiFi router or a WiFi shield or module. The only software requirement is
to set a TCP/IP server with a suitable IP and PORT.
Before using Bluetooth, please open App menu and check BT Enable box to allow Bluetooth communication.

Figure 10 Enabling WiFi Communication via ATC App

Arduino circuitry
In its simplest form, WiFi control can be achieved using an Ethernet shield attached to any Arduino and to a WiFi
Wireless router (like the one in our homes).

Figure 11 Basic Ethernet shield connection

Arduino sketch
The most recent, proven and functional Arduino sketch can be found in the app. Open app menu then touch Arduino
Code then select Beginner Eth Code. You can also check our Facebook pages for some early releases and examples:
https://www.facebook.com/ArduinoTotalControlApp
There are some warnings to take into account when downloading the Sketch into your Arduino board!!!

For UNO pins 10, 11, 12 and 13 are dedicated.

For MEGA pins 10, 50, 51 and 52 are dedicated
In other words do not use these PINS for INPUT or OUTPUT!!!
Select the correct board and COM port for programming.

Setting up WiFi connection

In order to connect to your Arduino via WiFi, the first you need to do is to set a proper IP address for your board. Most
Wireless Routers will use a local IP like 198.162.1.1. Then you can select from 198.162.1.2 to 198.162.1.253. For more
details on IP addresses please refer to http://en.wikipedia.org/wiki/IP_address.
To connect to an IP address, click on connect button next to App Title, select WiFi
TCP/Communication and the following dialog will appear.
Setting IP address
Type exactly the same address you have set on the Arduino Sketch on the Set Ip Address
field.
Figure Setting up a WiFi connection

Setting TCP Port

TCP/IP communication uses ports to send and receive data. Please type the port numbers exactly the same you did on
the Arduino Sketch.

Using auto connect for WiFi

When WiFi communication is active and enabled, auto connect will behave in the next way.

When app starts, ATC will try to connect to desired IP and port.
If connection fails, ATC will retry each 2.5 seconds until the app is closed.

Setting up a layout
In order to get the most of the app, to build a proper layout is recommended.
This section includes all you need to know to build a nice looking and useful
layout.
To start building a layout check menu -> Edit properties as displayed in figure 12,
this will put in the app in layout configuration
mode.

Editing Pictures
Once you have checked edit properties, touch
any picture and a dialog like shown at figure 13
will appear.
Figure 12 App Menu showing
Edit Properties checkbox

Setting picture visibility

Figure 13 Picture properties dialog

There are tree visibility states:

Visible. If selected, the current object will be visible

Invisible. If selected, the current picture will be invisible, but the space it uses will remain
Gone. If selected, the current picture will be invisible, and its layout footprint will be absorbed by rest of the
pictures in the same row.

Figure 14 illustrates the difference between invisible and gone pictures.

Setting images displayed

Each picture has tree states: Default state, which is displayed most of the time;
Pressed state, when a picture is enabled as a button, this state is displayed on
touch; Extra state, displayed only via a command from Arduino. After enabling edit
properties, long press on a picture and the dialog shown in figure 15 will appear,
use this dialog to change each of the image states.
Figure 15 Image Chooser Dialog
Setting Default State (State 0)
Check default state box, then select the source from gallery or from camera.
Setting Pressed State (State 1)
Check pressed state box, then select the source from gallery or from camera.
Setting Extra State (State 2)
Check extra state box, then select the source from gallery or from camera.
You can set the same image displayed for more than one state as displayed on
figure 16.

Figure 16 Selecting more than

one state for an image
displayed

Setting pictures as push buttons

To set a picture to be used as a push button, open the properties dialog by touching
any picture, then check Action on pic touch box.
Figure 17 Setting a picture as
a push button

When Action on pic touch property is enabled, action on long touch box will appear.
Use this property to enable images as long touch events. In other words, image will
send data and enter to pressed state after one second of being pressed approx.

Setting commands
When enabled as buttons, pictures will send commands or data to Arduino when
they are pressed and when they are released. Open the edit properties dialog
and set the data send on touch and on untouch as shown on the figure 18.
Commands can be a single character or multiple characters or strings.

Figure 18 Setting commands

send by picture

Editing Text
After enabling edit properties from app menu, touch any text and the following dialog
will appear.

Setting text visibility

There are tree visibility states:

Figure 19 Text properties dialog

Visible. If selected, the current object will be visible

Invisible. If selected, text will be invisible, but the space it uses will remain
Gone. If selected, the current text will be invisible, and its layout footprint will
be absorbed by the rest of the texts in the same row.

Figure 19 illustrates the difference between invisible and gone texts.

Setting text content

Text content can be any string as shown in figure 20. Please note that a very long text will affect layout proportions.

Figure 20 Setting text content

Enabling text as sensor source

In the properties window check the Use as sensor source box. Once checked the
available source will appear. The sensor data available is Accelerometer data, Axis X,
Axis Y and Axis Z.
When text is set as sensor source, text content will be replaced by sensor data, and
sensor data will be sent to Arduino via special command tags.
Figure 21 Setting Text as
sensor source

Editing Buttons
Once you have checked edit properties, touch any toggle button and a dialog will
appear.

Setting button visibility

There are tree visibility states:

Figure 22 Button properties

dialog

Visible. If selected, the current object will be visible

Invisible. If selected, the current text will be invisible, but the space it uses
will remain
Gone. If selected, the current text will be invisible, and its layout footprint
will be absorbed by rest of the texts in the same row.

Figure 23 illustrates the difference between visible, invisible and gone buttons.

Setting commands
Buttons will send commands or data to Arduino when they are checked (YES, ON, etc.)
and when they are unchecked (NO, OFF, etc.). Open the edit properties dialog and set the
data send on checked and on unchecked as shown on the figure 24.
Commands can be a single character or multiple characters or strings.
Figure 24 Setting
commands send by
button

Setting Emphasis Color

Emphasis color makes reference to button colors, and image color shading when they are enabled as push buttons. To
change emphasis color, open the app menu and select Emphasis Color. The dialog shown at figure 25 will appear.
Touch the circle in the middle to set a selected color.

Figure 25 Emphasis color selector dialog

Setting Layout orientation

For a better user experience, app layout is fixed. To change layout orientation, open the app menu and select from
portrait or landscape this will set up the layout orientation for the current layout. You will notice the app is arranged in
different ways for landscape and portrait modes.

Figure 26 Selecting a layout orientation

Enabling layout scroll

If there is no need to scroll, disabling layout scroll is recommended. If your implementation needs scrolling, just open
the app menu and check scroll enable.

Figure 27 enabling layout scroll

Switching layouts
To change from one layout to another, open app menu and select layout, the dialog shown in figure will appear. This
dialog shows the current selected layout. Once a layout is selected, the app will regenerate the layout with its particular
configurations.

Figure 28 Select layout dialog

Frequently Asked Questions

These are some tips and questions not covered in the manual regarding mostly to programming in Arduino.

How to use Seek Bars?

The latest Arduino beginner and advanced sketches include the following function:

This function is called when a < is received, which indicates a special command has been sent.
DecodeSpecialCommand method will extract the important information from special commands such as accelerometer
and seek bar data. These values are stored in the integer array:

In other words, every time special command data is sent, DecodeSpecialCommand is called and variables updated. Then
all you have to do is to add some code after DecodeSpecialCommand is called to do something with this information
like the following:

For this example, Seek bar 0 will act as a dimmer for LED 13 (which is available on every Arduino board). Please note that
if you are using Ethernet, pin 13 is not available, so use another PWM enabled pin.

How to add physical buttons

Physical buttons are switches or push buttons connected to Arduino input pins. It is an alternative to control circuits or
relays. The easiest way to implement physical buttons is to enable internal pull up resistors which will pull the voltage
up to 5 volts when the switch is open (when switch is closed, input voltage drops to 0 volts).

Figure Basic button wiring

All provided sketches include an example of how to add physical buttons. Since physical buttons are not as simple to
implement as one may think (because they have to be synced with actual relay states) you have to follow the next steps
in order to program a physical button:
1. Declare a global boolean variable which will tell us the button latch status.

2. Declare a suitable pin as input and enable pull up resistor via digitalWrite() at setup().

3. Add the following code for each physical button you want to use at the end of loop().

Please note that this code will toggle relay or circuit 0 when button at PIN A5 is pressed. In other words, if
relay 0 is on then it will be turned off when button is pressed. If relay 0 is off it will be turned on
when button is pressed.

But I want to add more physical buttons!!!

Lets say you want a physical button for more than one relay, one cool way you may want to try is to use arrays. One
array for input pins and one array for latch states (be careful of available I/O management). Then just follow the
following three steps:
1. Declare a global boolean array which will tell us each button latch status. Dont forget to declare an int array for
button input pins.

2. Set each input as digital input + pull up resistor at setup().

3. Add a for cycle which will check and set states for each ButtonPins (MAX_INPUTS = 3) at the end of loop().

How to use more than 8 relays

The first thing you have to consider is the available I/O, for UNO it will be difficult to get 24 outputs, for example.
However, you can use this tutorial as an example of how to get more than 8 commands from the app. To set the Arduino
to handle more than 8 relays please follow the next steps (It will be easier to achieve this using the Advanced codes for
either Ethernet or Bluetooth https://www.dropbox.com/sh/sgycfab71mch2r0/AAARbcJODcxRY29ag3qOFTVPa?dl=0 ):
1. Change the number of MAX_RELAYS to the desired quantity:

2. Add more pins to the RelayPins array (Note that they have to match MAX_RELAYS):

3. Add more IDs to RelayAppId array (Note that they have to match MAX_RELAYS):

4. Add more Commands according to MAX_RELAYS:

This is most of you have to do to use more outputs mapped to the app.
Note: if using beginner codes, you have to add more commands in the #define form
If using beginner codes, you have to add more case CMD_XX: to the switch located at loop.
Arduino is not remembering all relay states on reset
There is one more thing you may want to add to your code in order to make it completely functional for more than 8
relays. Eight relay codes use EEPROM_READ and EEPROM_WRITE which read and store byte values to EEPROM memory
on the Arduino. Since using more than 8 relays will require storing data in more than 8 bits, you have to follow the next
steps:
1. Add the RELAY_SATUS_SIZE constant and change RelayStatus to long:

2. On setup, change the RelayStatus = EEPROM.read(REL_ADD); for the next:

This will read the whole RelayStatus byte by byte.

3. Finally, change the simple EEPROM.write(STATUS_EEADR, RelayStatus); for the following at set relay state
function:

END OF MANUAL
Manual Version: 2.1

Please feel free to make any suggestion or correction