Skip to main content

Windows WSL Source Build And Flash

Audience: users who build and flash NE301 from source in a Windows + WSL setup (via Docker) after following Development Environment Setup and System Flashing And Initialization. Use this as a reference and adjust based on your hardware situation.

Key steps are shown below:

1. Environment Preparationโ€‹

  1. Install/enable
  2. Clone the repo (inside WSL) 
    git clone https://github.com/camthink-ai/ne301.git
    cd ne301
  3. Fix CRLF scripts Some scripts turn into CRLF on Windows and error with $'\r': command not found. Convert them to LF in WSL: 
    sed -i 's/\r$//' Script/generate-reloc-model.sh
  4. Confirm WSL can run Docker commands: docker version should print client info.

  1. In elevated PowerShell, install usbipd-win (skip if already installed):

    winget install --exact dorssel.usbipd-win

  2. Plug in ST-LINK and list devices:

    usbipd list

    Note the ST-LINK <busid> (for example, maybe 2-3).

  3. Force bind and enable auto-attach to all WSL2 distros:

    usbipd bind --force --busid <busid>
    usbipd attach --wsl --auto-attach --busid <busid>
    ST-LINK shown in lsusbusbipd attach example

    • If prompted, reboot Windows and rerun the commands.

    • If attach fails, try usbipd detach --busid <busid>, usbipd unbind --busid <busid>, wsl --shutdown, replug ST-LINK, then bind/attach again.

    Tip: If STM32CubeProgrammer is connected to the ST-LINK, disconnect it before passing through to WSL.

  4. Back in WSL, verify:

    lsusb

    Seeing 0483:3748 STMicroelectronics ST-LINK/V2 means pass-through succeeded. If ST-LINK disappears after re-enumeration, repeat the PowerShell attach steps.

3. Start The Docker Dev Containerโ€‹

In the repo directory inside WSL (use $(pwd); avoid \ line breaks in PowerShell):

docker run -it --rm --privileged \
  -v "$(pwd)":/workspace \
  -v /dev/bus/usb:/dev/bus/usb \
  camthink/ne301-dev:latest

If you must run it in PowerShell, put it on one line or use the backtick ` for continuation. If the host lacks /dev/bus/usb you cannot pass USB; running inside WSL is still recommended.

After entering the container, confirm the toolchain and ST-LINK:

STM32_Programmer_CLI -l

If ST-LINK is not listed, re-check the usbipd attach status.

4. Build + Flash Flowโ€‹

  1. Recommended one-liner (inside the container): 
    make flash
  2. Build only: 
    make          # FSBL + App + Web + Model
    make app      # same as single module build
  3. Flash components individually: 
    make flash-fsbl
    make flash-app
    make flash-web
    make flash-model
    make flash-wakecore

5. Common Issues & Fixesโ€‹

5.1 Docker reports invalid reference formatโ€‹

PowerShell cannot use \ for line continuation; use a single-line command or backtick `. Running inside WSL is recommended.

5.2 $'\r': command not foundโ€‹

Scripts were converted to CRLF. Run sed -i 's/\r$//' <file> or switch to LF in your editor.

5.3 usbipd attach fails / device disappearsโ€‹

  • Run commands in elevated PowerShell.
  • Replug the device, then usbipd detach/unbind โ†’ wsl --shutdown โ†’ usbipd bind --force โ†’ usbipd attach --wsl --auto-attach.

5.4 Unable to get core ID / No STM32 target foundโ€‹

  • Usually a bad connection or the chip crashed: check SWDIO/SWCLK/GND/NRST wiring and common ground; verify DIP switches and power.
  • Try low frequency + hard reset: 
    STM32_Programmer_CLI -c port=SWD mode=UR reset=HARD_RST freq=1000
    Press and hold Reset while running it if needed.

5.5 External Flash erase fails (optional)โ€‹

  1. Erase manually: 
    STM32_Programmer_CLI -c port=SWD mode=UR reset=HARD_RST freq=1000 \
      -e 0x70000000 0x70300000
  2. Write again: 
    STM32_Programmer_CLI -c port=SWD mode=UR reset=HARD_RST freq=1000 \
      -d build/ne301_App_signed_pkg.bin 0x70100000 -v
  3. If it still fails, check power/cables or try Mass Erase in the GUI with the External Loader.

5.6 STM32_Programmer_CLI -l shows no ST-LINK infoโ€‹

Example:

root@1e35ac8374ea:/workspace# STM32_Programmer_CLI -l
Detected locale "C" with character encoding "ANSI_X3.4-1968", which is not UTF-8.
Qt depends on a UTF-8 locale, and has switched to "C.UTF-8" instead.
If this causes problems, reconfigure your locale. See the locale(1) manual
for more information.
-------------------------------------------------------------------
STM32CubeProgrammer v2.19.0
-------------------------------------------------------------------

===== DFU Interface =====

No STM32 device in DFU mode connected

===== J-Link Interface =====
No J-Link/flasher probe detected.
===== STLink Interface =====
No ST-Link detected!

===== UART Interface =====

Total number of serial ports available: 0

root@1e35ac8374ea:/workspace#

If the container cannot see any ST-LINK/serial devices, USB is not passed through or nothing is connected. Troubleshoot as follows:

  • On the host/WSL, check devices: lsusb should show something like โ€œSTMicroelectronics ST-LINK/V2โ€. Install sudo apt install usbutils in WSL if lsusb is missing.
  • In WSL, use usbipd wsl list to see status. If not attached, run usbipd wsl attach --busid <busid>, then confirm with lsusb.
  • Container run args must include USB pass-through: --privileged -v /dev/bus/usb:/dev/bus/usb. If the current container lacks USB, exit and re-run docker with these flags.
  • Re-enter the container and run lsusb; once ST-LINK appears, STM32_Programmer_CLI -l should list it.
  • Ensure the board is powered, cables are good, and no other program (e.g., VSCode debugger, STM32_Programmer Connect) is occupying the ST-LINK.

6. Tips For Getting The Device MACโ€‹

After flashing, reboot the device (Reset or power cycle) and connect to the WiFi AP named NE301{MAC last 6 letters}. If only one NE301 is nearby, just connect; for multiple devices, confirm the MAC:

  • After it joins the LAN, find the MAC from your router/switch DHCP lease or ARP list. If you know the device IP, in Windows run: 
    ping <device IP>
    arp -a <device IP>
  • Or check the label on the unit directly.
  • Or watch the boot serial log (prints the device MAC).

After connecting a serial console, run ifconfig wifi ap to view the output.

Serial debug info

7. Special Caseโ€‹

If the environment is set up and flashing succeeds but the device WiFi AP still will not start, the WiFi firmware may not be updated. Join our Discord for further help.

8. Wrap-upโ€‹

Using the WSL environment, the above steps let you reproduce the flows in Development Environment Setup and System Flashing And Initialization on Windows + WSL while avoiding common pitfalls. Cross-reference this with the original docsโ€”hope it helps!