GROLAB USERBOT HW01 User manual

www.opengrow.pt
EN
E
S
FR
®
© 2019 Open Grow, LDA. All rights reserved.
USERBOT
(HW01)
IMUB2019V01
INSTALLATION
MANUAL
MANUEL D'INSTALLATION
MANUAL DE INSTALACIÓN
MANUAL DE INSTALAÇÃO
MANUALE DI INSTALLAZIONE

1
1
1
6
6
2
9
4
10
12
3
7
5
8
11
EN
E
S
FR
PT
IT

2
1
2
3
4
5
6
7
8
9
10
11
12
RF communication antenna
RF antenna outlet
RF module
RF interrupt pin
Universal breakout board
Arduino connecon pins
2 x SOT26
3 x SSOT223
2 x TSSOP-8 (=) 1 x TSSOP-16
SOIC16
4 x TO-92
Female pin headers
EN
E
S
FR
PT
IT

3
3
Dimensions 68.6mm x 53.4mm
Exterior Material: FR-4
Color: Green
Connections RP-SMA female
Female Pin Headers (Arduino connection/extension)
Includes Antenna
Inter-Module
Communication
Radio Frequency - 2.4GHz
Warranty 2-years limited hardware warranty
Operating Voltage +3V3 VDC
SMD Sockets 1 x SOIC16
2 x TSSOP 8 (=) 1 xTSSOP 16
3 x SSOT223
2 x SOT26
BreakOut Board
Spacing
2.54mm - 100mil
TH Sockets 4 x TO-92
BreakOut Board DIP/1206/0805/0603
SPECIFICATIONS TABLE
Hardware Version H01
EN
E
S
FR
PT
IT

4
3.a/b
INSTALLATION 1
Base connecons
Screw the communicaon antenna (1) into
the module’s RF antenna outlet (2).
For correct communicaon, turn the commu-
nicaons antenna (1) to posion it vercally
in the direcon of the module.
1
2
At this point, the UserBot shield is ready to be
assembled into the Arduino.
Connecon to Arduino
- Arduino UNO;
- Arduino Duemilanove;
- Arduino Leonardo with headers;
- Genuino Zero.
First, check if your Arduino model is compa-
ble with UserBot shield. Compable models:
EN
E
S
FR
PT
IT

5
5
Before connecng the UserBot shield to the
Arduino, make sure the Arduino is correctly
assembled and ready to be used (follow the
official Arduino instrucons manual). Also,
make sure your Arduino is not connected to
the power supply.
Place the Arduino on a firm surface, far from
flood-prone areas. Make sure the Arduino
female pin headers (A1) are faced up and the
UserBot shield connecon pins (7) are faced
down.
Insert the UserBot connecon pins (7) into the
Arduino female header (A1) from top-down as
shown in the above picture.
A1
7
A2
Avoid the contact between the UserBot shield and the
Arduino USB power entry (A2).
EN
E
S
FR
PT
IT

6
Peripherals connecon
Since UserBot is an extension for Arduino, it
means that any device or sensor that can
interface with Arduino is also compable
with UserBot shield.
In this way, the list of compable devices and
sensors is extremely long, being impossible
to list and explain how to connect all of them.
We will provide two examples: the first one
shows how to connect/sample a buon and a
temperature sensor, while also act on a LED;
the second one explains how to act on a DC
motor.
Before assembling any sensor or device, make sure the
Arduino is not connected to the power supply. Moreover, it is
advisable to carry out the assembly on a firm surface, far
from flood-prone areas. Also, use the proper tools for
handling electronic components.
EN
E
S
FR
PT
IT

7
7
6
6
6
6
BB
U1
R1
R2 D1
S1
5
Example 1
Connecng one buon, one temperature sensor and one LED.
6
R1
S1
U1
D1
Female pin headers
Pull down resistor 10k
Tacle Buon SPST
LM35 temperature sensor
LED
5Universal breakout board
BB External breadboard
R2 LED resistor 240
EN
E
S
FR
PT
IT

8
The diagram on the previous page shows the
connecon of some different peripherals to
the UserBot shield through its female pin
headers (6).
The tacle buon SPST (S1) is sampled on
Arduino analog pin A0; the LM35 temperature
sensor (U1) is sampled on Arduino analog pin
A1; the LED (D1) is controlled through the
Arduino digital pin 3. To control the ‘speed/in-
tensity’ of a device, it is required to use a PWM
Arduino digital pin (e.g. 3 and 5).
Use the +5V, +3V3 and the GND pins on Ardui-
no to power your sensors and/or devices.
Please refer to the official Arduino documenta-
on regarding power constraints on these
pins.
The UserBot shield includes an onboard bread-
board (5) that you are free to use. However, for
the diagram, we used an external breadboard
(BB) for a beer understanding.
It is crucial to pay aenon to the polarity of the different
components. A wrong connecon can damage your
components and Arduino/UserBot.
EN
E
S
FR
PT
IT

9
9
Example 2
Connecng a DC motor (peristalc pump, water pump...).
66
66
BB
Q1
P1
M1
5
6
M1
BB
P1
Q1
Female pin headers
DC motor
External breadboard
12VDC power entry
N-type MOSFET (e.g. IRLZ14)
5Universal breakout board
EN
E
S
FR
PT
IT

10
The diagram on the previous page shows an
N-type MOSFET (Q1) being used to control
the supply voltage to a DC motor (M1).
The DC motor (M1) is powered by an external
12VDC (P1) and has PWM control via the
Arduino digital pin 5. To control the "speed
or intensity" of a device, it is required to use
a PWM Arduino digital pin (e.g. 3 and 5).
The 12VDC power entry (P1) and the MOSFET
(Q1) also need to be connected to the Ardui-
no GND pin.
Use the UserBot female pin headers (6) to
connect the 12VDC power entry (P1) and the
MOSFET (Q1) to the respecve Arduino pins.
The UserBot shield includes an onboard
breadboard (5) that you are free to use.
However, for the diagram, we used an exter-
nal breadboard (BB) for a beer understan-
ding.
It is crucial to pay aenon to the polarity of the different
components. A wrong connecon can damage your
components and Arduino/UserBot.
EN
E
S
FR
PT
IT

11
11
1
Prepare the source code
Aer assembling all the sensors and devices,
it is me to prepare the source code to
handle them.
Open Grow provides the base firmware code
in an open-source format. It is available to
download on the GitHub at the following
page:
github.com/OpenWeGrow/UserBot
In this way, the first task is to download the
base code. Since there are several ways to do
it (e.g. using apps to handle repositories or
directly download from the GitHub web
page), we will not detail any specific method
in this manual. However, if you need assistan-
ce, please contact our technical support:
www.opengrow.pt [e-mail]
NOTE: The examples provided by this manual are based on
the code available on August 14, 2019.
EN
E
S
FR
PT
IT

12
Since the essence of the UserBot shield is to
integrate the Arduino with the GroLab
system, then to prepare the code we will use
the Arduino IDE. If at any moment, you find
any issues or obstacles with Arduino IDE,
please refer to the Arduino official guides.
Aer downloading the base code, copy/mo-
ve the contents of the folders ‘libraries’ and
‘examples’, to the respecve folders (same
names) inside the Arduino installaon folder
on your PC.
Ensure you have the correct Arduino board
selected in the Arduino IDE. For that, open
the Arduino IDE and navigate to Tools →
Board and choose the correct Arduino board
based on your physical Arduino.
Next step is to open the code with the Ardui-
no IDE, for that navigate to File → Examples
→ OpenGrow → UserBot and click to open it.
EN
E
S
FR
PT
IT

13
13
1
3
Before proceeding to change the code, we
will list the file structure and explain it a lile:
→ libraries
→ OpenGrow
• ComsTask.cpp
• ComsTask.h
• CRC16.cpp
• CRC16.h
• EEPROM_Uls.cpp
• EEPROM_Uls.h
• GroBot_Variables.h
• nRF24L01.h
• RF24.cpp
• RF24.h
• RF24_config.h
• OpenBus.cpp
• OpenBus.h
• SerialTask.cpp
• SerialTask.h
Communicaon state machine.
CRC calculator from Tim W. Shilling.
NVM handling funcons.
UserBot inputs/outputs definions.
NRF24L01 driver from J. Coliz <maniacbu-
[email protected]> with tweaks by Open
Grow.
Communicaon commands handler.
State machine to handle UART commands.
→ examples
→ OpenGrow
→ UserBot
• SensorsTask.cpp
• SensorsTask.h
• UserBot.ino
A dedicated state machine for sensors
sampling and output control.
Arduino (.ino) file and base to run the
program. This is the main UserBot
configuraon file. All of your inputs and
outputs should be configured in this file.
→ examples
→ OpenGrow
→ UserBot-DCMotor
(Same file structure as examples → OpenGrow → UserBot.)
EN
E
S
FR
PT
IT

14
1
In summary, for the majority of the cases (if
not all), the user only needs to change or
duplicate the following files:
→ examples
→ OpenGrow
→ UserBot
• SensorsTask.cpp
• SensorsTask.h
• UserBot.ino
Now everything is set, so it is me to start
changing the code to match the user needs.
Changing the code
Since the required code changes are depen-
dent on the assembled electronics by the
user and the possible combinaon of sensors
and devices is endless, it is not possible to
provide the exact soluon.
However, we will show the code required to
achieve the two example diagrams previously
presented.
EN
E
S
FR
PT
IT

15
15
5
Example 1
Connecng one buon, one temperature sensor, and one LED.
To interface the buon, the temperature
sensor and the LED, open the UserBot.ino
(examples → OpenGrow → UserBot) and naviga-
te to the setup funcon. This funcon
contains the configuraon for all the inputs
and outputs. You should adjust the code to
match the electronics you assembled on the
board. For the example diagram, the code
should be the following:
INPUTS CONFIGURATION
EN
E
S
FR
PT
IT

16
1
NOTE: UserBot shield supports up to 10 inputs and 10
outputs.
OUTPUTS CONFIGURATION
The different types of inputs and outputs are
declared in the GroBot_Variables.h (libraries
→ OpenGrow) below the comments ‘Possible
Input Types’ and ‘Possible Output Types’.
The changes in this first file are complete and
it is me to open the SensorsTask.cpp (exam-
ples → OpenGrow → UserBot).
EN
E
S
FR
PT
IT

17
17
1
7
Aer opening the SensorsTask.cpp, navigate to
the SensorsTask funcon and search for the
comment that says ‘* IO Config *’. Below the
comment, you will find an example pin configu-
raon that you should adjust to match your
components. For the example diagram the
code should be the following:
Now, navigate to the GoSensorsTask funcon
and look at the switch. Inside the case
GET_IOS, you should add the code to sample
your inputs and update its respecve values in
the inputs array. For example:
if (digitalRead(inputs[INPUT_INDEX0].arduinoPin))
inputs[INPUT_INDEX0].value = 255;
else
inputs[INPUT_INDEX0].value = 0;
Or if it's an output, inside the case
ACT_ON_IOS, you should add the code to act
on the outputs. For example:
if (outputs[OUTPUT_INDEX0].value > 0)
digitalWrite(outputs[OUTPUT_INDEX0].arduinoPin, HIGH);
else
digitalWrite(outputs[OUTPUT_INDEX0].arduinoPin, LOW);
EN
E
S
FR
PT
IT

18
1
You can add more cases based on your needs.
For the example schemacs, the code inside the
switch should be the following:
Note that we added some more code related to
the output to support the variable ‘speed’ (e.g
to control the LED’s intensity) and other funco-
nalies already implemented in the GroLab
System (such as the security cooldown me for
sensive devices).
NOTE: The inputs and outputs arrays, stores the sample
values from sensors, as well as the state of the outputs. Those
arrays are crucial to exchange info with the GroLab system.
EN
E
S
FR
PT
IT

19
9
If you need to change the cases from the
switch it is also required to change the enum
that contains those cases. The enum is decla-
red in the SensorsTask.h (
examples →
OpenGrow → UserBot).
At this point, the code is prepared to handle
the physical peripherals from the diagram
shown in example 1. Now it is me to compi-
le and upload the code to your Arduino.
If you need assistance to compile and upload
the code, please refer to the official Arduino
guides or contact the Arduino support center.
Aer uploading the code to your Arduino,
there is sll one step required to make it fully
operaonal and ready to communicate with
GroLab system: the factory sengs need to
be set (serial number and communicaon
channel). Please refer to the instrucons on
pages 25 and 26.
EN
E
S
FR
PT
IT