From 5fb292012a537e8c5226d5be10bad2641f55bca2 Mon Sep 17 00:00:00 2001 From: Sebastiano Date: Fri, 22 May 2026 14:56:33 +0200 Subject: [PATCH] add WSL support details and flashing instructions to README --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5bea00b..d19e6f6 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ This is a tutorial for Lingua Franca applications running on RIOT OS with the [A | **Linux** (Ubuntu/Debian) | Fully supported (recommended) | | **NixOS / Nix** | Fully supported | | **macOS** | Supported with caveats | +| **Windows / WSL** | Supported with flashing caveats | > **Note:** For detailed RIOT OS setup instructions, see the official [RIOT Getting Started Guide](https://doc.riot-os.org/getting-started.html). @@ -104,6 +105,30 @@ brew install --cask gcc-arm-embedded > **Important:** On macOS, `make` is installed as `gmake`. Use `gmake` instead of `make` in all commands below. +#### 1.3.4. Windows Subsystem for Linux (WSL) + +WSL can use the same Linux package setup as Ubuntu/Debian. In addition, install the Python packages required by the RIOT terminal and the Adafruit flashing tool: + +```bash +pip install psutil adafruit-nrfutil +``` + +WSL does not automatically expose USB serial devices from Windows. Before using a board from WSL, share and attach the device from Windows PowerShell with `usbipd-win`. Follow the [Microsoft WSL USB guide](https://learn.microsoft.com/en-us/windows/wsl/connect-usb) for the full setup. + +Typical PowerShell commands are: + +```powershell +usbipd list +usbipd bind --busid +usbipd attach --wsl --busid +``` + +After attaching the board, verify the serial device from WSL and use the detected device path as the `PORT` value: + +```bash +ls /dev/ttyACM* +``` + ### 1.4. Verify Your Setup Check that the required tools are available: @@ -245,6 +270,7 @@ Add the following lines to your Makefile to enable I2C support in RIOT: # so i2c and printf support for floats is compiled into the riot kernel USEMODULE += periph_i2c USEMODULE += printf_float +USEMODULE += ztimer_sec ``` ### 4.2. Implementing the Sensor @@ -260,7 +286,27 @@ To test your sensor implementation, compile and run `Sensor.lf` (which includes make LF_MAIN=Sensor BOARD=adafruit-feather-nrf52840-sense all flash term ``` -### 4.3. Using Sensor Values +If you are using WSL, use the explicit flashing and terminal commands in the next section. + +### 4.3. WSL Flashing & Troubleshooting + +When using Windows Subsystem for Linux (WSL) with the Adafruit Feather nRF52840 Sense, the normal RIOT build flow can be used for compilation, but flashing may require the Adafruit bootloader workflow. + +Before flashing from WSL, make sure the board's USB serial device has been shared from Windows PowerShell and attached to WSL as described in the setup section. Then put the board into bootloader mode manually. The board should enumerate as a serial device such as `/dev/ttyACM0`. + +Then use this command to flash the firmware using the Adafruit nRF Util tool: + +```bash +make LF_MAIN=Sensor BOARD=adafruit-feather-nrf52840-sense PROGRAMMER=adafruit-nrfutil PORT=/dev/ttyACM0 flash +``` + +After flashing, open the serial monitor with: + +```bash +make LF_MAIN=Sensor BOARD=adafruit-feather-nrf52840-sense PORT=/dev/ttyACM0 term +``` + +### 4.4. Using Sensor Values Make the LED blink faster or slower based on the device's orientation. When flat on a table (angle ≈ 0), use a 1-second LED toggle period. @@ -371,5 +417,3 @@ Open the the `src/FederatedBlinking.lf` file now we want to combine everything l here we want to let the local Blink faster if neighbors microcontroller is turned. Then make sure all the necessary modules are added inside your `Makefile`. Additionally, make sure you flash the correct version onto the correct board (otherwise the addresses won't match). - -