Get your node running

Choose the hardware you have

Match the exact board and LoRa chip. XIAO release images belong on the XIAO; the Heltec and LilyGO guides select their own pins, memory and flash layout.

Use an original T-Beam or Heltec V3 with Willow

The shared modem handles RF and serves KISS on port 8001; Willow runs the roles and keeps their identities on the computer. The original T-Beam has 4 MB flash, and Heltec V3 has no PSRAM, so choose the modem profile for these boards.

Follow the T-Beam v1.2 SX1262/SX1276 guide or Heltec V3 modem guide to set WiFi and your PHY in a private configuration, build the firmware and install it on the selected USB device. Then give Willow the modem's address. Keep the modem and host on a trusted LAN.

Use a RAK node over Ethernet

The RAK4631 profile runs a repeater and separately addressed notes bot. Add a RAK13800 Ethernet module for MeshCore companion connections on TCP port 5000, and a RAK19018 PoE module to power it through the network cable. Keep companion access on a trusted LAN.

Follow the RAK build and setup guide to select the radio or Ethernet profile, initialize a new board and update its application while keeping its identities and settings.

Choose your radio profile

Fit the antenna before transmitting. Set the frequency, bandwidth, spreading factor, coding rate and permitted transmit power for your network, and match the other radios. Every role sharing the modem uses that profile.

The guides' 912.525 MHz / BW 250 kHz / SF7 / CR5 / TX 2 dBm profile is an example. Select settings permitted where you operate.

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 leaves RF and administration disabled and reports restore private setup over USB. Restore the private setup before creating identities or transmitting.

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.

Before replacing another firmware, export its identity and useful data using its own backup tools. Its flash layout may differ from Aspen's. The browser's combined Aspen image erases the board and generates new identities; your previous keys will be lost from that board.

To move an initialized private Aspen to the generic application while keeping its identities, settings and data, use the migration procedure.

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.4, 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.4-linux-x86_64-SOURCE12/install-birch.py \
  --prefix "$HOME/.local/opt/birch-0.1.4"

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: roles on a Linux host

Connect a configured shared modem to your trusted LAN. Willow runs relay, room, bot and observer roles on Linux x86-64; the Base companion, dashboard and MQTT broker let you connect apps and monitor the node.

Choose your installation: use the Linux bundle below, or run Willow with Docker Compose using ghcr.io/slepp/meshcore-willow:0.0.12. The container guide saves private state across container replacements and lets you add the dashboard, Base companion and broker as separate services.

1. Install Willow

   Use Linux x86-64 with Debian 12 or a compatible system (glibc 2.36 and OpenSSL 3). Download Willow 0.0.12 for Linux x86-64 and its SHA256SUMS from the release page. Install the runtime packages, extract the archive and install it:

   sudo apt-get install python3 python3-cryptography python3-nacl \
     libssl3 libcjson1 libsodium23 libstdc++6 zlib1g ca-certificates
   tar -xzf willow-v0.0.12-linux-x86_64.tar.gz
   cd willow-v0.0.12-linux-x86_64
   python3 install-willow.py --prefix "$HOME/.local/lib/willow/0.0.12"
   cd "$HOME/.local/lib/willow/0.0.12/hosts/willow"

   The bundle includes the host, Base companion, dashboard, MQTT broker and Lua/Wasm worker. See the installation guide for runtime requirements.

2. Choose your modem and radio profile

   Set the modem's actual IPv4 address. Set the frequency, bandwidth, SF, CR and transmit power below to match your local network and modem. Frequency and bandwidth use Hz, and CR5 means 4/5. The remaining values are airtime factor, CAD mode and CAD threshold. Willow reads the modem's configuration and checks this profile without retuning it.

   MODEM_IPV4='192.168.1.50' # Replace with your modem's DHCP address
   PROFILE_HEX=$(python3 -c 'import struct; print(struct.pack(
       "<IIBBBfBh", 912525000, 250000, 7, 5, 2, 1.0, 1, 0
   ).hex())')
   ./build/hew-host-release init "$HOME/.local/state/willow" \
     --address "$MODEM_IPV4" --port 8001 --profile "$PROFILE_HEX"

   Initialization creates new private identities and settings. For an existing node, use the migration instructions below instead. The initialization guide describes the state files and credentials.

3. Check and start

   Check the saved configuration, then start the host:

   python3 -B tools/willow.py check --state "$HOME/.local/state/willow"
   python3 -B tools/willow.py run --release --state "$HOME/.local/state/willow"

   Expect ONLINE and BOT_READY native-extension. In another terminal, use python3 -B tools/willow.py health --state "$HOME/.local/state/willow" from the same installation directory to see connections and ready roles. Add the Base companion to connect the MeshCore app.

Moving an existing node? Stop its previous host before handover and use the migration guide to retain identities in a new state directory. Running the same identity on two hosts causes conflicting transmissions.

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 an initialized node with existing identities, credential records and Lua storage. For initial provisioning, follow the Pine setup guide.

For a USB update, download the matching *-legacy-dfu.zip, pine-v0.1.4-update.json and its .sig from the release page, then follow the signed application-update guide. 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.

Choose the repeater, room or companion profile in the remote-radio guide. To run several roles indoors, use Willow on a host.

Remote-modem role guide

Connect and send your first message

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 to keep its shared radio settings. Port 5000 serves the app; port 8001 serves KISS clients.

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.

   Aspen can answer local commands from its own Base. To message it across RF, connect your app to a separate companion radio on the same complete radio profile.

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, programs and data. Check ready roles, the shared PHY and app connectivity after restarting.

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.