RoboRally/docs/3_ROBOT_SETUP.md

# Robot setup

This file explains how to setup the software for the robots. It assumes that you already assembled your robot according to the instructions in [1_ASSEMBLY.md](https://imaginaerraum.de/git/Telos4/RoboRally/src/branch/master/docs/1_ASSEMBLY.md) and that you updated the firmware of the motor shield as described in [2_MOTOR_SHIELD_FIX.md](https://imaginaerraum.de/git/Telos4/RoboRally/src/branch/master/docs/2_MOTOR_SHIELD_FIX.md).

Before we start, stack the D1 mini ontop of the battery shield and connect it to your computer using a micro USB cable: 
![Electronics assembly done](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_battery_stack_13.jpeg)
![Micro USB connection](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/usb_connection.jpeg)

### Flash Micropython to the Wemos D1 mini
The first step is to flash the micropython firmware to the D1 mini. 
You can download the latest micropython firmware for the ESP8266 from [here](http://micropython.org/download#esp8266). I used version _esp8266-20190125-v1.10.bin_ but you can also use a more recent version.
The firmware can be flashed on the D1 mini using the following commands:
```
$ esptool.py --port /dev/ttyUSB0 erase_flash
$ esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20190125-v1.10.bin
```

### Communicating with the D1 mini
After flashing the firmware we can access the python prompt on the microcontroller using a serial communication program such as picocom.

On Ubuntu you can install this with
```
  $ sudo apt-get install picocom
```
 Connect using picocom:
```
  $ picocom /dev/ttyUSB0 -b115200
```
First we enable WebREPL on the microcontroller which allows us to easily upload files and debug the robots via WiFi.
*(I will use `>>>` in order to indicate commands which should be issued in the Micropython prompt)*
```
>>> import webrepl_setup
```
  -> choose enable, set a password and choose reboot

  Now we set up an access point on the D1 mini:
```
  >>> import network
  >>> ap_if = network.WLAN(network.AP_IF)
  >>> ap_if.active(True)
  >>> ap_if.ifconfig() # this prints the IP
```
  The default password for this access point is: `micropythoN`
  
  Alternatively, you can also connect to an existing wifi network using:
```
  >>> import network
  >>> sta_if = network.WLAN(network.STA_IF)
  >>> sta_if.active(True)
  >>> sta_if.connect("<SSID>", "<PW>")
  >>> sta_if.ifconfig() # this prints the IP
```

Join the same WiFi network with your PC (either the access point or the local network) and connect to the D1 mini via the [online WebREPL](http://micropython.org/webrepl):
Enter IP from above and click connect. Login with the password you set for the WebREPL.

![WebREPL connection](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/webrepl0.jpg)

![WebREPL login](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/webrepl1.jpg)

![WebREPL prompt](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/webrepl2.jpg)

### Making settings permanent
In order to avoid having to set up the WebREPL and the WiFi everytime we reboot the robot we can upload a file called boot.py which runs each time the robot restarts:

- Find the file `boot.py` in the `micropython_firmware/` subfolder and edit the lines indicated with `# TODO`. In particular, set the wifi network, password and IP addresses. You should choose a unique IP address for each robot
```
# TODO: edit these lines
network_name = 'Your WiFi network'	# existing wifi network to connect to (leave empty if unused)
password = 'Your password'	# password for the network
desired_ip = '192.168.1.101'	# the robot will be reachable by this IP in the network
subnet = '255.255.255.0'
gateway = '192.168.1.1'
dns = '192.168.1.1'
# TODO end edit
```
 - Upload boot.py via WebREPL
 
 ![WebREPL file upload](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/webrepl3.jpg)
 - Now the robot will automatically connect to WiFi network you set and start a WebREPL server after reboot. 
 
 *Note: If the WiFi network cannot be found the microcontroller will instead open an access point.*
 
### Upload robot firmware
Next, upload the motor controller script to the microcontroller. At the moment the firmware consists of the following three files located in `micropython_firmware/`:

- `main.py` Main script handling network communication and control
- `d1motor.py` Interface for the Wemos D1 mini motor shield
- `l293dmotor.py`Interface for alternative motor driver using L293D (no longer used)

You can upload these files the same way you did before with the WebREPL. After uploading all the files reboot the microcontroller by pressing the reset button or by pressing `Ctrl+D` in the WebREPL prompt.

### Test the robot
Now it's time to test if everything is working fine. 

- Disconnect the USB cable from the microcontroller and connect the battery to the battery connector:
![Battery connection](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/battery_connection.jpeg)

- Next, connect the two motors of the robot to the motor shield according to the following sketch:
![Connect motors to motor shield](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/robot_bb.jpg)
![Motor and battery connection overview](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/battery_connection_overview.jpeg)

- Test if you can reach the robot using
```
$ ping 192.168.1.101
```
*Note: Make sure you use the correct IP address for your robot.*

- If everything worked, connect to the robot via WebREPL as before. Don't worry if the prompt does not appear to be working. The robot is running a program waiting for incoming connections for remote control.
We can connect to the robot via a socket on port `1234`. There is a simple demo program which illustrates how to control the robot remotely via keyboard. The program uses `pygame` for input handling so make sure to install it using
```
$ sudo pip install pygame
```
The program is located in the `remote_control/`. Run it using
```
$ python keyboard_controller.py 192.168.1.101
```
When running the program you should see an output in the WebREPL that a connection was established.
You can use the arrow keys for sending commands to the microcontroller which it then passes on to the motors.

Now you're all set up for controlling your robot remotely via wifi. 
You can control the robot by sending commands to the robot as a string containing `'(u1, u2)\n'`, where `u1` and `u2` are floats in the range `[-1.0, 1.0]`, e.g. `'(0.3, -0.6)\n'`.
Have a look at the `keyboard_controller.py` script to see how this works in python.

### Isolating the electronics
Since the mounting plates of the robot are made of metal it is a good idea to put some isolation around the electronics. You can use some isolation tape to cover the exposed pins:

![Isolation tape](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/isolation_tape_2.JPG)
You can also add some velcro tape to the electronics, the battery and the robot to easily attach and remove the microcontroller from the robot.

![Velcro tape electronics and battery](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/velcro_tape_2.jpeg)
![Velcro tape robot](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/velcro_tape_3.jpeg)

### Charging the battery
In order to charge the battery of the robot just plug a micro USB cable into the USB port of the battery shield.

![Battery charging](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/charging.jpeg)

### Next steps
The next step is to setup the position detection using ROS. For this see the [4_ROS_SETUP.md](https://imaginaerraum.de/git/Telos4/RoboRally/src/branch/master/docs/4_ROS_SETUP.md)