RoboRally/docs/2_MOTOR_SHIELD_FIX.md

# Motor shield fix

### Get 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
```
-> This creates a file called 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.

- 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
```

- Make sure the RTS and 3V port of the Wemos motor shield are connected by a wire. Also make sure that the I2C bridge connection on the motor shield is set.
![Motor shield jumper](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_shield_jumper.jpeg)

- Plug the Wemos D1 mini on top of the motor shield and then connect it to your PC using a micro USB cable

- 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 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
}
```
- Erase flash on the chip:
```
$ esptool.py --port /dev/ttyUSB0 erase_flash
```
- 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 |

![Firmware fix connections sketch](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_firmware_update_bb.jpg)
![Firmware fix connections image](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_shield_fix_4.JPG)

### Flash the new firmware on the STM32:
- Connect the D1 mini to your PC using a micro USB cable.
![Micro USB connection](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_shield_fix_1.JPG)
- 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
```

- Unlock the shield for flashing:
```
$ 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.
```

- 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.

### Next steps
Continue with the instructions in the file [3_ROBOT_SETUP.md](https://imaginaerraum.de/git/Telos4/RoboRally/src/branch/master/docs/3_ROBOT_SETUP.md) to complete the setup of the robot.