====== VREL #5: Roboarm IoT Laboratory ======
The laboratory is located at Silesian Technical University, Poland, Gliwice Akademicka 16, room 310.

===== Introduction  =====
The lab consists of a mechanical robot arm with two degrees of freedom. Using two actuators user can change the position of the arm, especially, can move the tail section of the arm, at beside ground of the node. For a better impression on the ground, there are bricks on the rail, which can be pushed with the robotic arm left and right. You can observe the arm position via camera and also read its position via embedded IMUs (one per each movable piece of the arm).

===== Prerequisites =====

The user needs to know:
  * PWM control method,
  * working od servo-motors,
  * working of step-motors,
  * basic of inverse kinematics problem,
  * the way proximity sensor works,
  * the way IMU (particularily accelerometer) works.

===== Technical details =====
Robo arm is a set of two arms. The first part of the arm is fixed to the axle of step motors that are fixed to the "wall" of the laboratory. On the end of the first arm, there is a servo motor that drives the second, tail part of the arm. Thus, for full operation of the robot arm, the user has to control for two different devices: step motor and servomotor. To control the position of the brick, on each end of the rail (left and right wall), there is a binary proximity sensor, to recognize the utmost position of bricks. For feedback, the user can check the position of the arm using accelerometer sensors fixed on each arm (IMU).

{{:en:iot-open:remotelab:sut:iotra.jpg?470|}}

{{:en:iot-open:remotelab:sut:arm_geom.jpg?470|}}

{{:en:iot-open:remotelab:sut:arm_equ.jpg?470|}}

===== Sensors =====
There are 4 sensors in the lab:
  * 2 accelerometer sensor on each part of the arm (MPU6050)
  * 2 proximity sensor on bricks' rail

===== Actuators =====
There are two actuators: step motor and servomotor. Control of step-motos is simplified, using the dedicated proxy drive board. The user does not need to understand how the step motor works on the low level (i.e. control separate coils), because thanks for the proxy driver board, there are only two input: DIR and STEP, so the overall control process is simplified. 

{{:en:iot-open:remotelab:sut:iotra_sch.jpg?500|}}

===== Software, libraries and externals =====
LCD display requires a dedicated library. Of course, you can control it on the low-level programming, writing directly to the I2C registers, but we do suggest using a library first. As there are many universal libraries, and many of them are incompatible with this display, we strongly recommend using [[https://github.com/tonykambo/LiquidCrystal_I2C|''LiquidCrystal_I2C by Tony Kambourakis'']].
The LCD I2C control library can be imported to the source code via:
<code c>
#include <LiquidCrystal_I2C.h>
</code>
Then configure your LCD controller:
<code c>
LiquidCrystal_I2C lcd(0x3F,20,4);  // set the LCD address to 0x3F 
                                   // for a 20 chars and 4 line display
</code>


To read data from the MPU6050 IMMUs, you may use ''I2Cdevlib-MPU6050'' library. You must include related I2C library as well:
<code c>
#include "I2Cdev.h"
#include "MPU6050.h"
...
//IMU
MPU6050 accelgyro(0x68);  //hand gyro (servo)
MPU6050 accelgyro2(0x69); // arm gyro (motor)
</code>
Note: I2C addresses for the MPUs:
  * 0x68 - for the IMU on the "hand" (segment **b** on the image above)
  * 0x69 - for the IMU located on the arm (segment **a** on the image above)

To control servomotor, standard Arduino's Servo library is suitable:
<code c>
#define SERVO_PIN D8
...
#include "Servo.h"
...
</code>

Finally, to control the step motor, we suggest using ''StepperDriver'' library:
<code c>
#include "BasicStepperDriver.h"
...
//Motor and Stepper Driver
#define MICROSTEPS 1
#define MOTOR_STEPS 200
#define RPM 120
#define DIR D5
#define STEP D6
#define SLEEP D7
BasicStepperDriver stepper(MOTOR_STEPS, DIR, STEP, SLEEP);
...
</code>

=== Platformio.ini ===
<code c>
; PlatformIO Project Configuration File
;
;   Build options: build flags, source filter
;   Upload options: custom upload port, speed and extra flags
;   Library options: dependencies, extra library storages
;   Advanced options: extra scripting
;
; Please visit documentation for the other options and examples
; http://docs.platformio.org/page/projectconf.html

[env:d1_mini]
platform = espressif8266
board = d1_mini
framework = arduino
lib_deps = Wire, EmonLib, Adafruit NeoPixel, Encoder,DHT sensor library, 
Adafruit Unified Sensor, LCD, PubSubClient, 
KS0108_PCF8574, CoAP simple library, I2Cdevlib-MPU6050, StepperDriver
</code>

===== Communication =====
You can connect your ESP8266 microcontroller via its integrated WiFi interface to the separated IoT network. Then you can communicate with other, already connected devices and even provide some information to the cloud. In details, there is a dedicated MQTT broker waiting for you. You can also set up your own soft Access Point and connect another node directly to yours.

The communication among the devices can be done using MQTT messages, exchanging data among other nodes (M2M) and you can even push them to the Internet. 

Using your Node, you can access it and publish/subscribe to the messages once you connect your ESP to the existing wireless network (this network does not provide access to the global internet and is separated but please note there are other developers and IoT nodes connected to this access point:
  * SSID: internal.IOT
  * Passkey: IoTlab32768
  * Setup your microcontroller for DHCP, to automatically obtain an IP address, your ESP will obtain the address from the 192.168.90.X pool.
  * MQTT server is available under the fixed address: 192.168.90.5, and the credentials to publish/subscribe are: 
    * User: vrel
    * Password: vrel2018

===== Limits =====

At the same time, only one user can be programming the node, although analysing the signal by others (unlimited number) the user makes sense. Model is provided to continuously work, without service breaks.

<note important>Robotic arm is a pretty powerful device and you can eventually break it if operated out of reasonable constraints (speed, momentum)</note>

===== Support =====
In case the LCD display hangs and you are sure that your code should work but it does not, it may be the case the I2C bus is stuck and hang the I2C to LCD controller converter.\\
In this case, please use the following code to reset the I2C bus (you can embed it to your source code or run separately, then run your original code, again):
<code c>
#include <Arduino.h>
#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x3F,20,4);  

void setup()
{
  pinMode(4,OUTPUT);
  pinMode(5, OUTPUT);
  digitalWrite(4,LOW);
  digitalWrite(5,LOW);
  delay(2000);
  pinMode(5, INPUT);       // reset pin
  pinMode(4, INPUT);
  delay(2050);
  lcd.init(D2,D1);
  lcd.backlight();
  lcd.home();
  lcd.print("Hello world...");
}
void loop()
{
  
}
</code>
Finally, you should see Hello World message on the LCD and I2C bus should be recovered now.