Add instructions for flsahing MCUs

README.md

@@ -32,7 +32,7 @@ The following is the list of the software used for developing the firmware. The
 
 | Software | Version | Optional |
 | --- | --- | --- |
-| [platformio](https://platformio.org/) | `6.1.7` | No |
+| [platformio](pio) | `6.1.7` | No |
 | [stm32pio](https://github.com/ussserrr/stm32pio) | `2.1.0` | Yes, for code generation |
 | [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) | `6.10.0` | Yes, for code generation |
 | [STM32CubeIDE](https://www.st.com/en/development-tools/stm32cubeide.html) | `1.13.2` | Yes, for flashing with openocd on Windows |
@@ -41,6 +41,53 @@ The following is the list of the software used for developing the firmware. The
 | [protobuf](https://protobuf.dev/) | `25.2` | No |
 | Make | `4.4.1` | No |
 
+## Flashing firmware to microcontrollers
+
+The Wio-E5 (stm32 based) and the esp32 have different methods of flashing but both use the [PlatformIO](pio) system. The VSCode extension is the most intuitive to use with setup instructions available [here](https://platformio.org/install/ide?install=vscode) and quick start guide available [here](https://docs.platformio.org/en/latest/integration/ide/vscode.html#quick-start). There is also a CLI interface that is similar to the `Make` build system with installation instructions varying depending on you OS. The [quick start guide](https://docs.platformio.org/en/latest/core/quickstart.html#process-project) is a good reference for common commands.
+
+In VSCode PlatformIO extension requires a folder with a `platformio.ini` file for the project configuration. We recommend opening the root folder `ents-node-firmware` in VSCode than adding the `esp32` and `stm32` folders with *File/Add Folder to Workspace...*, then saving the workspace to the root project folder. The `.code-workspace` file should be automatically excluded from git. After all environments in both `esp32` and `stm32` should be available.
+
+The Wio-E5 relies on a ST-Link JTAG interface with detailed instructions available at [stm/README.md](stm32/README.md). The esp32 uses a built in a bootloader that can be accessed over UART, detailed instructions are available at [eps32/README.md](esp32/README.md).
+
+In both `stm32/platformio.ini` and `esp32/platformio.ini` the `upload_port`, `monitor_port`, and `test_port` will need to be changed to match the USB port. ***DO NOT*** change the `debug_port` as it will cause issues when launching the debugger. To get a list of connected devices in VSCode, click the following *PlatformIO Tab -> Project Tasks -> General -> Devices*. There is also an equivalent CLI command.
+
+**VSCode**
+
+![VSCode Devices](images/vscode_devices.png)
+
+**CLI**
+
+```bash
+pio device list
+```
+
+The following is the expected output with the Wio-E5 and ST-Link connected via USB. The esp32 port definition will depend on the USB to TTL used to interface with the exposed UART pins. In my case `/dev/ttyUSB0` with description *CP2102N USB to UART Bridge Controller* is the serial connection with the Wio-E5 module and `/dev/ttyACM0` is the ST-Link.
+
+```
+/dev/ttyUSB0
+------------
+Hardware ID: USB VID:PID=10C4:EA60 SER=fe18dcf14e87ed119ee029d7a603910e LOCATION=1-2
+Description: CP2102N USB to UART Bridge Controller
+
+/dev/ttyACM0
+------------
+Hardware ID: USB VID:PID=0483:3754 SER=004B00233033510635393935 LOCATION=1-4:1.1
+Description: STLINK-V3 - ST-Link VCP Ctrl
+```
+
+The USB ports can be copied into `platformio.ini` as follows:
+
+```ini
+debug_port = localhost:3333
+upload_port = /dev/ttyACM0
+
+monitor_port = /dev/ttyUSB0
+monitor_speed = 115200
+
+test_port = /dev/ttyUSB0
+test_speed = 115200
+```
+
 ## Generation documentation
 
 This project use [Doxygen](https://www.doxygen.nl/) for its code documentation. HTML documentation is automatically generated through Github Actions and is updated whenever there is a change to the `main` branch. To generate documentation locally in the `docs/` folder, run the following from the root directory:
@@ -83,3 +130,5 @@ Code in this repository is licensed under the MIT License unless specified in th
 
 - [Steve Taylor](mailto:sgtaylor@ucsc.edu)
 - [Varun Sreedharan](mailto:vasreedh@ucsc.edu)
+
+[pio]: https://platformio.org/

esp32/README.md

@@ -4,7 +4,27 @@ The ESP32 firmware acts as a WiFi interface the STM32 module. It gets binary dat
 
 ## Flashing
 
-TODO
+> Before running the following ensure you have updated the ports in `platformio.ini` described in the root [README.md](../README.md).
+
+The esp32 is programmed through a bootloader through UART. A USB to TTL convert is required to program the microcontroller with your computer and can be found cheaply online. Ensure it supports 3.3V logic levels.
+
+### VSCode
+
+Check the correct environment is selected. Should be `env:esp32 (esp32)`
+
+![VSCode env](../images/vscode_env_esp32.jpeg)
+
+Goto *PlatformIO Tab -> Project Tasks -> Upload and Monitor*
+
+![VSCode Upload and Monitor](../images/vscode_upload_monitor.jpeg)
+
+### CLI
+
+The following can be used to flash the firmware on the esp32
+
+```bash
+pio run -e esp32 -t upload -t monitor
+```
 
 ## Testing
 

stm32/README.md

@@ -1,5 +1,35 @@
 # STM32 Firmware
 
+## Flashing the firmware
+
+> Before running the following ensure you have updated the ports in `platformio.ini` described in the root [README.md](../README.md).
+
+Connect the ST-Link to `D2` at the top of the board. Connect Wio-E5 to your computer using a USB-C cable.
+
+### VSCode
+
+Check the correct environment is selected. Should be `env:stm32 (stm32)`
+
+![VSCode env](../images/vscode_env_stm32.jpeg)
+
+Goto *PlatformIO Tab -> Project Tasks -> Upload and Monitor*
+
+![VSCode Upload and Monitor](../images/vscode_upload_monitor.jpeg)
+
+### CLI
+
+To build and upload the firmware and open a serial monitor run the following command. You should see LoRaWAN EUIs printed and the device attempting to connect to a network.
+
+```bash
+pio run -e stm32 -t upload -t monitor
+```
+
+There are other firmware (mainly examples) that can be flashed to the board. For example the environment *example_adc* prints measurements and can be flashed with the following
+
+```bash
+pio run -e example_adc -t upload -t monitor
+```
+
 ## Structure of `platformio.ini`
 
 Since this project is monolithic and requires all components to be built together, the structure of @ref platformio.ini does not follow standard platformio practices. The default environment (`stm32`) builds the project with `main.c`. For the `example_battery` environment `main.c` needs to be excluded as follows