Set up a node

Before you transmit

• Radio profile: choose a frequency, bandwidth, spreading factor, coding rate and transmit power permitted where you operate. Every role on the node uses this profile, and your companion radio must match it.
• Credentials: set your own administrator, management and room passwords. Keep owner keys and seeds on your own computer, outside the repository and firmware images.
• Backup: on an existing node, back up role identities, settings, programs and stored data before changing firmware or moving host services.
• Supported hardware: Seeed Wio SX1262 with a XIAO ESP32-S3R8 (8 MiB flash, PSRAM) or XIAO nRF52840, and an antenna fitted before transmitting. Heltec V3/V4 and other board ports need their own wiring, flash-layout, memory and role checks; the XIAO packages must not be flashed to them.

The guides use 912.525 MHz / BW 250 kHz / SF7 / CR5 / TX 2 dBm with three-byte paths as an example. Use it only where it is permitted.

Source-build options

Standalone ESP32 (Aspen)

The ESP32 runs the selected repeater, room, companion and observer roles, the command bot and the shared modem. RF roles keep running if WiFi drops.

New board: browser setup and MeshCore flasher

Start Aspen browser setup

1. Choose your settings

   Download the Aspen release ZIP and select it in the browser setup. Enter your local radio profile, WiFi and the services you want. The page creates credentials locally; they are not uploaded.

2. Save the private files and flash

   Keep the private setup ZIP, including your operator key and passwords. Download the private -merged.bin, then choose it with Custom Firmware at flasher.meshcore.io. The wizard has the port-selection and reset steps.

3. Check the node

   After reset, USB diagnostics report Public setup loaded and the selected roles become ready. With WiFi enabled, log in at http://aspen.local/admin (or the printed IP address) and confirm the frequency and power before sending messages. Then connect and test.

Preview the browser settings

If the setup is missing or invalid, the node reports RF and administration disabled; restore private setup over USB and does not create identities or transmit.

make aspen-config
$EDITOR firmware/platformio.onchip.ini

make -C firmware/esp32 bot-firmware \
  CONFIG="$PWD/firmware/platformio.onchip.ini" \
  BUILD="$PWD/.tmp/onchip-MeshCore" ENV=Xiao_S3_WIO_onchip_beta \
  ONCHIP_BOT_WASM=1

Already have a MeshCore node?

Keep it running while you try Aspen on a new supported board. They communicate over the same native MeshCore protocols when their radio profiles match.

Replacing a different firmware is a migration, not an Aspen update. Its flash layout and saved state may differ. Preserve its identity and useful state using that firmware's backup/export tools before deciding to replace it. The browser's combined Aspen image erases the board and creates new radio identities; it does not import the previous node's keys.

For an initialized private Aspen moving to the generic application, use the retained-state migration procedure, not new-board setup.

Birch: Go host with a WiFi modem

A Linux computer runs the roles; an ESP32 + SX1262 WiFi modem at the antenna provides the radio. For an existing modem, download Birch 0.1.1, extract it and check SHA256SUMS. Use Debian 12 x86_64 with Python 3.11, libcjson1 and libssl3; no Go compiler is needed.

python3 birch-v0.1.1-linux-x86_64-SOURCE12/install-birch.py \
  --prefix "$HOME/.local/opt/birch-0.1.1"

Replace SOURCE12 with the extracted directory suffix. Edit its private config/meshcore-host.json: choose the modem address, enabled roles and room password environment. Run bin/meshcore-host -config CONFIG -check before starting it. The installed configuration follows the modem's profile without retuning it.

Build a WiFi modem and host from source

If you need a modem, use Git, Python 3, PlatformIO and Go, then run from the repository root:

make firmware-config
$EDITOR firmware/platformio.local.ini
make firmware
make firmware-upload UPLOAD_PORT='/dev/serial/by-id/<radio-device>'
make host-config
$EDITOR meshcore-host.json
make host-run

• In the firmware configuration, set WiFi and the modem's hostname.
• In meshcore-host.json, set radio_address, enable the roles you need and choose the shared radio profile. Supply the room password through MESHCORE_ROOM_PASSWORD, or set room_public: true for an open room.
• If the modem is a standalone node that manages its own radio settings, set "phy_authority": "modem" so the host does not retune it.
• Name the upload device explicitly when several radios are attached.

Expected: the modem serves KISS at RADIO_IP:8001 and a read-only dashboard at http://RADIO_IP/. The host reports at http://127.0.0.1:9080/status, and /readyz returns HTTP 200 when the enabled roles and connections are ready. Without mDNS, use the modem's DHCP address.

Go host guide: capacity, services, native worker, backup and rollback

Willow: Hew host with a WiFi modem

Use the WiFi modem from the Birch setup above. Willow runs relay, room, bot and observer services on a Linux x86-64 host. Its native Base companion, HTTP dashboard and local MQTT broker run separately. Choose each service from its own guide and check its supported commands and limits.

Willow is experimental. Extract the Willow 0.0.2 source ZIP, check its SHA256SUMS, and use Hew 0.6.0-rc7 with the dependencies in the Willow README. Build at the final installation path, keep the source and native-worker inputs there, and check your selected services before handing over existing identities:

cd experiments/hew-roles
make compiler-version
make native-worker build/hew-host-release
python3 -B willow.py check --state /path/to/private/willow
python3 -B willow.py run --release --state /path/to/private/willow

Before these commands, follow the offline migration guide to create the private state directory from a stopped Birch or Willow installation. check verifies state and worker inputs without opening the modem. run starts the selected roles; inspect their connection and readiness with python3 -B willow.py health --state /path/to/private/willow.

Willow requirements and capabilities · Build, health and service setup · Offline migration and rollback

Native Base companion · Native local MQTT broker

Standalone nRF52840 (Pine)

Pine runs a native repeater (Pine-Relay) and a separately addressed Lua bot (Pine-Bot) on a XIAO nRF52840. It has no WiFi, HTTPS or Wasm. You administer it from a MeshCore app connected to another companion radio.

The Pine download updates a node that is already initialized; it cannot set up a blank board. Build the image from source with:

make -C firmware/nrf52840 build ENV=nrfmast_fleet_lua \
  LUA_ARCHIVE=/path/to/lua-5.5.1.tar.gz

Install the application firmware.uf2 or DFU firmware.zip, not a full-device image. Updates keep identities, credentials and stored Lua programs and data.

Expected: after you advertise your companion, Pine-Relay's administrator console answers bot status, bot limits and source status, and Pine-Bot answers a private !ping with Pong.

Pine production Lua: provisioning, limits and recovery · Operating Pine

ESP32 role with a remote modem

An indoor ESP32 runs one repeater, room or companion and keeps its identity and settings. A separate ESP32 + SX1262 WiFi modem at the radio site owns tuning, channel access and the transmit queue. Configure the modem first, then give the role matching radio settings and its WiFi connection.

make remote-radio-config
$EDITOR firmware/platformio.phyless.ini
make remote-radio-firmware PHYLESS_ENV=Phyless_Xiao_S3_repeater
make remote-radio-upload PHYLESS_ENV=Phyless_Xiao_S3_repeater \
  UPLOAD_PORT='/dev/serial/by-id/<indoor-esp32>'

Choose Phyless_Xiao_S3_room for a room or Phyless_Xiao_S3_client for a companion. To run several roles indoors, use a Go host instead.

Remote-modem role guide

Connect and test

1. Connect the MeshCore app

   Install the MeshCore app by Liam Cottle on your phone or computer. In the app choose Connect → WiFi, enter Aspen's IP address and port 5000, and enable Auto Reconnect. Choose Skip Setup on a configured node so the app does not replace its shared radio settings. Port 8001 is KISS, not the app endpoint.

2. Advertise, then message the bot

   Send your companion's advert, then open MeshCore command bot (or the bot name shown on the dashboard). Send a private !ping and expect Pong. If the contact is missing, send role advert bot zerohop in Aspen's authenticated /admin console.

   The Aspen 0.1.11 download also answers local commands from its own Base. Use a separate companion radio on the same complete radio profile to communicate with the bot across RF.

3. Explore the commands

   !help lists the commands you may use; !help NAME shows usage and an example. See the built-in commands.

Companion app connection settings · Connect an external bot

Update without losing state

An application-only update keeps role identities, saved settings and stored programs and data. Contacts and routes that the bot learned in memory need a fresh advert after the restart.

Aspen: keep its setup and update one application slot

Download the release and retain an encrypted node backup. For a managed Aspen, use the signed WiFi application update with the operator.seed from your private setup ZIP. Check the selected running hash and healthy roles afterward.

For USB recovery, use the slot-aware USB command. It reads the current OTA selection before choosing where to write the application.

ESP32 updates use BIN files, not UF2, unless the installed bootloader supports UF2. After a timeout, read the node's status before repeating an install or restore. Never erase identity storage to clear a radio-profile mismatch.

ESP32 persistence and recovery · Host state and credentials · Pine BLE update recovery

Continue

• Operate a nodeShared airtime, identities, administration and monitoring.
• Extend the botCommands, Lua, Wasm and HTTPS services.
• DownloadsAspen, Birch, Pine and Willow GitHub releases with checksums.