diff --git a/README.md b/README.md index 4a35f4f1..5f65bca4 100644 --- a/README.md +++ b/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/ \ No newline at end of file diff --git a/esp32/README.md b/esp32/README.md index 70174b23..3a5670db 100644 --- a/esp32/README.md +++ b/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 diff --git a/images/vscode_devices.png b/images/vscode_devices.png new file mode 100644 index 00000000..d1e2bdb7 Binary files /dev/null and b/images/vscode_devices.png differ diff --git a/images/vscode_env_esp32.jpeg b/images/vscode_env_esp32.jpeg new file mode 100644 index 00000000..49e4c835 Binary files /dev/null and b/images/vscode_env_esp32.jpeg differ diff --git a/images/vscode_env_stm32.jpeg b/images/vscode_env_stm32.jpeg new file mode 100644 index 00000000..2ca07a85 Binary files /dev/null and b/images/vscode_env_stm32.jpeg differ diff --git a/images/vscode_upload_monitor.jpeg b/images/vscode_upload_monitor.jpeg new file mode 100644 index 00000000..59bfd32d Binary files /dev/null and b/images/vscode_upload_monitor.jpeg differ diff --git a/stm32/README.md b/stm32/README.md index 28ff545b..5cec7d5f 100644 --- a/stm32/README.md +++ b/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