docs/2_MOTOR_SHIELD_FIX.md

@@ -1,47 +1,47 @@
 # 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
+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
 ```
 
-- 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)
+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.
 
-- Plug the Wemos D1 mini on top of the motor shield and then connect it to your PC using a micro USB cable
+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
+```
 
-- 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`
+#### Build the firmware:
 
-Note: If you compile it yourself make sure you choose the Wemos D1 mini board as target for the build.
+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.
+![D1 mini](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_firmware_update_bb.jpg)
+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() {
@@ -52,16 +52,16 @@ void loop() {
   // just some dummy code
 }
 ```
-- Erase flash on the chip:
+4. Erase flash on the chip:
 ```
 $ esptool.py --port /dev/ttyUSB0 erase_flash
 ```
-- Flash the dummy sketch:
+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:
+#### 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:
@@ -70,7 +70,7 @@ $ make
 $ make install
 ```
 
-### Connect the motor shield to D1 mini:
+#### 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|
@@ -80,11 +80,13 @@ Use some jumper cables to connect the motor shield and the D1 mini in the follow
 |3V            |  3V|
 |GND           |  GND |
 
-![D1 mini](https://imaginaerraum.de/git/Telos4/RoboRally/raw/branch/master/docs/images/motor_firmware_update_bb.jpg)
+In addition on the motor shield connect 3V to RTS
+Also make sure that the I2C bridge connection on the motor shield is set.
 
-### Flash the new firmware on the STM32:
-- Connect the D1 mini to your PC using a micro USB cable.
-- Check if you can communicate with the STM32:
+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
 ```
@@ -102,7 +104,7 @@ Device ID    : 0x0444 (STM32F03xx4/6)
 - System RAM : 3KiB
 ```
 
-- Unlock the shield for flashing:
+2. Unlock shield:
 ```
 $ stm32flash -k /dev/ttyUSB0
 ```
@@ -126,7 +128,7 @@ Read-UnProtecting flash
 Done.
 ```
 
-- Flash new motor driver:
+3. Flash new motor driver:
 ```
 $ stm32flash -f -v -w motor_shield.bin /dev/ttyUSB0
 ```