Developer Instruction

This section explains how to download the Dragino Mesh firmware source on Windows and build application firmware for S31B-MS or SN50V3-MS with the Visual Studio Code (VS Code) PlatformIO interface, and points to the standard firmware and the diagnostic tool. No device connection is required during compilation. After a successful build, the generated firmware is installed over USB serial or PC BLE with FirmwareUpdateUtility. For the step-by-step upload procedure, see How to upload the firmware to Mesh End Node in the FAQ (section 9).

1. How to compile the GitHub source code

Build workflow:

Download source -> Extract source -> Install VS Code and PlatformIO
-> Open the firmware project -> Wait for dependencies -> Select the product
-> Click Build -> Locate firmware.bin

1.1 Requirements

• A Windows 10 or Windows 11 computer.
• A working internet connection. PlatformIO must download the compiler, framework, and third-party libraries during initial setup.
• Visual Studio Code.
• At least approximately 5 GB of free disk space.

Use a short path containing only English characters when practical, for example:

D:\Dragino\MeshNode

Do not open the project directly inside the ZIP archive, and avoid placing the source in a deeply nested directory because long paths can break the dependency install on Windows.

1.2 Download the firmware source

1. Open the public Dragino MeshNode source repository: https://github.com/dragino/MeshNode
2. Select the branch or version specified by Dragino. Use the master branch only when no specific version has been supplied.
3. Click Code.
4. Click Download ZIP.
5. Extract the complete ZIP archive to a local directory.

Figure annotations:

1. Current branch. Select the required release branch or tag before downloading a specific release.
2. The Code download menu.
3. The Download ZIP source archive action.

The source can also be downloaded with Git:

git clone https://github.com/dragino/MeshNode.git

note

Firmware used for production or fleet updates must come from an approved version. Do not deploy the master branch only because it is newer.

1.3 Install VS Code and PlatformIO

Download and install the Windows version of VS Code from the VS Code website. Then install the PlatformIO extension:

1. Start VS Code.
2. Click the Extensions icon in the Activity Bar.
3. Enter PlatformIO IDE in the search field.
4. Select the extension published by PlatformIO, then click Install.
5. Reload or restart VS Code when prompted.

Figure annotations:

1. Enter platformio in the extension search field.
2. Select PlatformIO IDE. Do not select a similarly named third-party extension.
3. Confirm the extension name, publisher, and installation state. A PlatformIO icon appears in the VS Code Activity Bar after installation.

PlatformIO may also install PlatformIO Core the first time it starts. Allow this operation to finish before opening the firmware project.

1.4 Open the firmware project

The downloaded repository contains documentation, tools, and multiple source trees. VS Code must open the firmware directory that directly contains the root platformio.ini, not the repository root. The current firmware project directory is:

MeshNode\firmware\dragino-firmware\firmware-2.7.15.567b8ea

To open it:

1. Select File -> Open Folder in VS Code.
2. Browse to the directory shown above and confirm that the selected folder is named firmware-2.7.15.567b8ea.
3. Click Select Folder.
4. If VS Code asks whether the folder is trusted, confirm the source and trust the folder.

When the project is opened for the first time, PlatformIO reads the configuration and downloads the compiler, framework, and third-party libraries. This can take several minutes. If loading makes no progress for an extended period, close all VS Code windows completely, start VS Code again, reopen the same folder, and allow PlatformIO to continue. If downloads repeatedly fail, check the computer's network, proxy, and firewall settings. Do not start builds before PlatformIO has completed initialization.

The root platformio.ini is the PlatformIO project entry configuration: [platformio] / default_envs select the default build environment, and extra_configs loads the environment definitions from arch, variants, and the other listed locations. These settings do not need to be edited for a normal build.

1.5 Select the product (firmware targets)

The products use different PlatformIO environments, defined in variants\stm32\dragino-stm32-node\platformio.ini:

Product	PlatformIO environment
S31B-MS	dragino-stm32-node-S31B-MS
SN50V3-MS	dragino-stm32-node-SN50V3-MS

Always select the environment that matches the product label. Firmware for the two products is not interchangeable.

After the project loads, PlatformIO shortcuts appear in the lower-left VS Code status bar:

Number	Action	Use in this guide
1	PIO Home	Opens the PlatformIO home and project management page
2	Build	Builds the active environment; this is the primary action used in this guide
3	Upload	Uploads directly through PlatformIO; do not use it for a normal Dragino firmware update
4	Clean	Removes cached build output for the active environment
5	Test	Runs PlatformIO tests; not required for a normal firmware build
6	Serial Monitor	Opens the serial monitor
7	New Terminal	Opens a PlatformIO terminal
8	Active Environment	Shows the active environment and can be used to switch environments

Check item 8 before building: for S31B-MS it must show env:dragino-stm32-node-S31B-MS, and for SN50V3-MS it must show env:dragino-stm32-node-SN50V3-MS. If the active environment is incorrect, click the environment name and select the required environment, or run PlatformIO: Switch Project Environment from the Command Palette.

1.6 Build the APP firmware

1. Confirm that the correct product environment is shown in the lower-left status bar.
2. Click the PlatformIO checkmark icon (item 2) to run Build.
3. A terminal opens at the bottom of VS Code and displays build progress.
4. Wait for the final SUCCESS result. The build is complete only when this result appears.

Figure annotations:

1. firmware.hex is generated and its output path is displayed.
2. Flash and RAM usage are displayed, and .pio\build\<environment>\firmware.bin is generated.
3. The active environment reports SUCCESS.

The first build normally takes longer because PlatformIO must download and compile all dependencies; later incremental builds are faster. As a sanity check, firmware.bin should be under the APP-slot size (STM32WLE5JC has 256 KB total flash; the APP slot starts at 0x08007800, leaving ~226 KB for the APP).

After switching products, or when cached output may be invalid, run a clean build: confirm the active environment, click the trash icon to run Clean, wait for cleaning to finish, then click Build again. For normal small source changes, click Build directly; a clean is not required before every build.

If the first build fails because third-party libraries have not finished loading, close VS Code completely, reopen the project, wait for dependency loading to finish, and build again. Restarting VS Code will not fix source syntax errors, linker capacity errors, or missing symbols; those must be corrected based on the terminal output.

1.7 Generated firmware files

After a successful build, output files are stored under the firmware project's .pio\build directory, in the subdirectory named after the environment:

.pio\build\dragino-stm32-node-S31B-MS\firmware.bin
.pio\build\dragino-stm32-node-SN50V3-MS\firmware.bin

Each product directory normally contains:

File	Purpose
firmware.bin	Application image used for a normal Bootloader update
firmware.hex	Intel HEX image with address information for specified production or service procedures
firmware.elf	Debugging and symbol analysis file; not used for a normal firmware update
firmware.map	Linker map used for development analysis

For a normal APP update, use firmware.bin. .pio contains generated build output: Clean may remove the temporary output for the active environment, and running Build generates it again.

1.8 Use the build result

For a normal device update, select the firmware.bin produced by the environment that matches the device, then use the Bootloader Update function in FirmwareUpdateUtility. The FirmwareUpdateUtility package includes its own detailed manual for device connection, Bootloader synchronization, firmware selection, writing, and verification. The upload steps are summarized in the FAQ (section 9).

Do not use PlatformIO Upload in VS Code as the normal device update method. The standard workflow is to run Build in VS Code and then install the generated application image with FirmwareUpdateUtility.

Warning

STM32 Programming, Bootloader programming, and custom Flash addresses are production or service operations. Do not change addresses or use those advanced functions without explicit instructions from Dragino.

1.9 Build troubleshooting

Issue	Solution
The PlatformIO icon is not visible	Confirm that PlatformIO IDE is installed and enabled, then reload VS Code
Initial loading takes a long time or fails	Close VS Code completely, reopen the same firmware project, and allow PlatformIO to continue loading third-party libraries
Dependencies still cannot be downloaded after restarting	Check network, proxy, and firewall settings and confirm that PlatformIO download resources are reachable
PlatformIO does not recognize the project	Open the firmware-2.7.15.567b8ea folder that directly contains the root platformio.ini
The active environment does not match the product	Click the environment name in the status bar or use PlatformIO: Switch Project Environment
The wrong product was built	Switch to the correct product environment, then run Clean and Build
Red text appears in the terminal	Read the final error. The build is complete only when the final result is SUCCESS
firmware.bin cannot be found	Confirm SUCCESS, then open the .pio\build subdirectory whose name matches the active environment
A path or filename length error occurs	Move the complete repository to a shorter path containing only English characters, then reopen the project
Product functions are incorrect after an update	Confirm that the build environment and device label match, then rebuild and install the correct product firmware

1.10 Checklists

Before clicking Build, confirm that:

• The firmware project directory is open, not the repository root.
• The root directory contains platformio.ini.
• PlatformIO has completed the initial dependency load.
• The active environment in the status bar matches the device model.
• The source branch or version is the one specified by Dragino.

Before using the build result, confirm that:

• The build reports SUCCESS.
• firmware.bin comes from the correct product environment directory.
• The target device model matches the firmware model.
• The subsequent update follows the manual supplied with FirmwareUpdateUtility.

1.11 References (build)

• Dragino MeshNode source code
• PlatformIO IDE for VS Code
• ST AN2606: STM32 system-memory boot mode
• ST AN3155: USART protocol used by the STM32 ROM bootloader

2. How to Upload the firmware

The normal update workflow with a firmware you built (or a standard firmware supplied by Dragino):

1. Put the node into upgrade mode (Bootloader): press the button 8 times consecutively; the green LED flashes.
2. Use the PC-side FirmwareUpdateUtility tool or the mobile app to connect through USB serial or BLE.
3. Select the corresponding APP firmware (firmware.bin).
4. Start the upgrade and wait for writing and verification to complete.
5. After the upgrade, allow the device to return to normal operation and check its status and data on the Mesh gateway.

If an upgrade fails, the device remains in upgrade mode and the upgrade can be run again. If the device cannot enter upgrade mode, contact Dragino technical support. A detailed procedure to manually upgrade firmware, wiring, and troubleshooting are in the FAQ (section 9).

Standard firmware: coming soon

Dragino will also provide standard, ready-to-flash APP firmware so customers can update a Mesh End Node directly without building from source. The download location and the per-model firmware list will be added here once available.

3. Diagnostic tool: MeshDebug

MeshDebug is the Dragino diagnostic/configuration tool for developers. It can inspect and send packets, decode business data, and validate factory identity and enrollment workflows.

Run it from the repository:

cd apps\meshdebug
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
.\.venv\Scripts\python main.py

note

MeshDebug is the current diagnostic tool. The customer-facing gateway management tools MeshGateway (CLI) and MeshDeck (web dashboard) are still under development.