docs/2_ROBOT_SETUP.md

@@ -0,0 +1,209 @@
+# 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
+
+1 Install esptool
+-----------------
+The chip on the Wemos D1 mini is a Esp8266. In order to flash programs on this chip we will use esptool by Espressif.
+You can install it using pip:
+```
+$ pip install esptool
+```
+
+2 Update Motor shield firmware
+----------------------------
+The Wemos motor shield comes with a buggy firmware which has problems with the I2C communication ([see here]([buggy firmware](https://hackaday.io/project/18439-motor-shield-reprogramming))). 
+Luckily, some guys figured out how to update the firmware of the STM32 on the motor shield with a custom one that fixes these issues.
+
+These are the necessary steps:
+#### Install arm compiler:
+```
+$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
+$ sudo apt-get update
+$ sudo apt-get install gcc-arm-embedded
+```
+
+#### Build the firmware:
+
+Get the firmware from: [https://github.com/pbugalski/wemos_motor_shield](https://github.com/pbugalski/wemos_motor_shield)
+```
+$ make
+```
+-> motor_shield.bin
+
+#### Upload empty firmware to Wemos D1 mini
+We will program the STM32 on the motor shield using the serial USB connection from the Wemos D1 mini. The D1 mini should
+just pass through the serial communication to the STM32. For this we need to upload a dummy firmware to the D1 mini.
+
+1. Make sure the RTS and 3V port of the Wemos motor shield are connected by a wire (you should already have done this in the assembly instructions).
+Also make sure that the I2C bridge connection on the motor shield is set.
+
+2. Plug the Wemos D1 mini on top of the motor shield and then connect it to your PC using a micro USB cable
+
+3. Compile the sketch below into a .bin file using the Arduino IDE -> `dummy_sketch.ino.d1_mini.bin` or use the one from `bin/dummy_sketch.ino.d1_min.bin`
+
+Note: If you you compile it yourself make sure you choose the Wemos D1 mini board as target for the build.
+
+```
+void setup() {
+  // just some dummy code
+}
+
+void loop() {
+  // just some dummy code
+}
+```
+4. Erase flash on the chip:
+```
+$ esptool.py --port /dev/ttyUSB0 erase_flash
+```
+5. Flash the dummy sketch:
+```
+$ esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 dummy_sketch.ino.d1_mini.bin/dummy_sketch.ino.d1_mini.bin.ino.d1_mini.bin
+``` 
+
+#### Install stm32flash utility:
+To upload a new firmware to the STM32 that is running on the motor shield we need the STM32 flash utility.
+You can download from: [https://sourceforge.net/projects/stm32flash/files/](https://sourceforge.net/projects/stm32flash/files/)
+You should then build and install it using the usual:
+```
+$ make
+$ make install
+```
+
+#### Connect the motor shield to D1 mini:
+Use some jumper cables to connect the motor shield and the D1 mini in the following way.
+
+|Wemos D1 mini | Motor shield|
+|--------------|---------------|
+|TX            |  D1|
+|RX            |  D2|
+|3V            |  3V|
+|GND           |  GND |
+
+In addition on the motor shield connect 3V to RTS
+Also make sure that the I2C bridge connection on the motor shield is set.
+
+Then, connect the D1 mini to your PC using a micro USB cable.
+
+#### Flash the new firmware on the STM32:
+1. Check if you can communicate with the STM32:
+```
+$ stm32flash /dev/ttyUSB0
+```
+
+Output should be:
+```
+Interface serial_posix: 57600 8E1
+Version      : 0x31
+Option 1     : 0x00
+Option 2     : 0x00
+Device ID    : 0x0444 (STM32F03xx4/6)
+- RAM        : 4KiB  (2048b reserved by bootloader)
+- Flash      : 32KiB (size first sector: 4x1024)
+- Option RAM : 16b
+- System RAM : 3KiB
+```
+
+2. Unlock shield:
+```
+$ stm32flash -k /dev/ttyUSB0
+```
+
+Output should be:
+```
+stm32flash 0.5
+
+http://stm32flash.sourceforge.net/
+
+Interface serial_posix: 57600 8E1
+Version      : 0x31
+Option 1     : 0x00
+Option 2     : 0x00
+Device ID    : 0x0444 (STM32F03xx4/6)
+- RAM        : 4KiB  (2048b reserved by bootloader)
+- Flash      : 32KiB (size first sector: 4x1024)
+- Option RAM : 16b
+- System RAM : 3KiB
+Read-UnProtecting flash
+Done.
+```
+
+3. Flash new motor driver:
+```
+$ stm32flash -f -v -w motor_shield.bin /dev/ttyUSB0
+```
+
+Output should be:
+```
+stm32flash 0.5
+
+http://stm32flash.sourceforge.net/
+
+Using Parser : Raw BINARY
+Interface serial_posix: 57600 8E1
+Version      : 0x31
+Option 1     : 0x00
+Option 2     : 0x00
+Device ID    : 0x0444 (STM32F03xx4/6)
+- RAM        : 4KiB  (2048b reserved by bootloader)
+- Flash      : 32KiB (size first sector: 4x1024)
+- Option RAM : 16b
+- System RAM : 3KiB
+Write to memory
+Erasing memory
+Wrote and verified address 0x08000be8 (100.00%) Done.
+```
+
+#### Cleaning up
+Finally, you can remove the wire between RTS and 3V. 
+At this point, please make sure that the I2C bridge on the Wemos Motor shield is connected. This is necessary for I2C to work correctly.
+
+
+Flash Micropython to the Wemos D1 mini
+--------------------------------------
+The next step is to flash the micropython firmware to 
+```
+$ 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
+```
+Setting up webrepl:
+ Connect using picocom:
+```
+  $ picocom /dev/ttyUSB0 -b115200
+```
+3. Connect via picocom and enable Webrepl
+```
+>>> import webrepl_setup
+```
+  -> enable, set password and reboot
+
+  Connect to local wifi:
+```
+  >>> 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
+```
+  Use access point to connect:
+```
+  >>> import network
+  >>> ap_if = network.WLAN(network.AP_IF)
+  >>> ap_if.active(True)
+  >>> ap_if.ifconfig() # this prints the IP
+```
+  Default password for the access point: `micropythoN`
+
+Connect via [online WebREPL](http://micropython.org/webrepl):
+ - Enter IP from above and click connect. Login with password.
+ - Upload boot.py via Webrepl to automatically connect to wifi and start webrepl after reboot
+ - You can also upload a file called main.py or just work in the webrepl terminal.
+
+
+4. Connect via webpage and upload boot.py, main.py, etc.
+Modify boot.py before uploading!
+
+5. Connect to the robot and test the connection
+
+The next step is to setup the position detection using ROS. For this see the ROS_SETUP.txt