Operate a node

Check your node

1. Open the dashboard

   For Aspen, open http://NODE_IP/ and sign in at /admin for changes. For Willow, open your configured dashboard address. Check ready roles, the shared radio profile and connected clients.

2. Connect the app

   Use the companion address and port 5000. Send an advert, then a private !ping to the bot. Expect Pong. App connection steps

3. Check the service you need

   Use !help for bot commands, the room's login/history controls for conversations, and radio counters for queue and airtime. If a connection fails, inspect that service's client count and last error.

Change node settings · Backups and restarts · Update while keeping state · Add a command

Shared radio and airtime

The shared modem owns tuning, channel access and the transmit queue. It hands every received packet to each role and schedules their outgoing packets against shared capacity and airtime limits. The selected image sets how many roles and KISS connections it accepts.

Local reflections: when one role transmits, the other roles on the same node receive a copy labelled as a local reflection. RF receptions carry measured RSSI and SNR. Use a recipient ACK or reply to check whether another radio received your transmission.

Adaptive bot admission (opt-in) reduces bot work as local RF load and queues grow, sharing the allowance fairly among callers. Enable it through owner administration and restart; bot adaptive reports the saved setting and live load. On a host, use adaptive on the owner socket.

A second repeater on the same mesh can duplicate forwarding and use extra airtime. Place repeaters deliberately.

RF load and capacity measurements: received replies, room delivery, queues, airtime and memory during mixed traffic.

Roles and identities

Each role is a separate MeshCore node with its own key. A standalone ESP32 runs one of each built-in role; a Go host can run additional instances. Pine pairs its repeater with the Lua bot.

Names and role settings change without rebuilding. Changing an identity needs owner authority, and private data stays tied to the full key that created it. The MeshCore Android app connects over WiFi TCP, exchanges direct and room messages, and administers repeater and room roles you are authorized for.

What survives a restart

Stored data stays with the full identities it belongs to, through name and program changes. Rolling back a program changes the code and leaves stored data and timer claims as they are.

Each reminder can be sent at most once. Restoring a backup does not re-arm reminders that were already sent or whose send was uncertain. A pending reminder needs trusted time and a fresh route, and expires after a 60-second delivery window.

Use an encrypted node backup before maintenance. Keep the operator seed needed to inspect it in private storage.

Administer a node

Over LoRa: open Management, install a command and use admin controls

Aspen controls cover role selection, names, radio settings, grants, program installation, rollback and scoped backups. Program transfers over RF can resume through ordinary MeshCore repeaters. Willow's local controls cover its supported role and bot settings, not shared modem tuning; consult its service guide before a change.

• Check before rebooting. Compare saved and applied settings first. A radio change affects every role on that modem.
• After a timeout, read status before repeating an install or restore; the first request may have completed.
• Before maintenance, keep program and scoped data backups. For an unreadable filesystem, use the platform's recovery procedure to preserve recoverable state.

RF management and owner CLI · ESP32 browser administration · Go host status and owner socket · Willow service and owner controls

Watch the traffic

The observer publishes RF receptions to your MQTT broker as observer-v1 messages with upstream-compatible packet fields and hashes. Packets and status use meshcore/IATA/UPPERCASE_OBSERVER_KEY/{packets,status}; role metadata uses separate lowercase-key topics.

• The packet feed contains RF receptions only. Local transmissions and reflections are kept separate.
• Aspen publishes with QoS 0 and a bounded queue. Go and Willow host observers use QoS 1; broker acknowledgement confirms publication, not subscriber processing. Host retries can redeliver a packet. Willow checkpoints its pending and queued observations after 30 seconds of dirty state and flushes on a controlled stop; crash recovery resumes from the last completed checkpoint, so recent events can be lost or replayed.
• Connect over MQTT on a trusted LAN, or WSS with CA and hostname checks. Send packets only to a broker you trust with your traffic.
• Configure Aspen’s observer destination and credentials using its observer guide.
• Willow accepts your broker's hostname, IPv4 or bracketed IPv6 address in observer.url. TCP, TLS, WS and WSS use the existing publisher; TLS verifies the certificate and hostname. Keep credentials in their separate private settings and run the offline state check before restarting.

The KISS monitor decodes serial or TCP traffic, and the node dashboard shows roles, connections, queues, airtime and memory. For history, import the Grafana dashboard and select your Prometheus data source; the ESP32 telemetry publisher feeds resource panels and a companion bot can poll traffic and repeater status.

Aspen observer setup · Willow observer setup · Grafana dashboard import · Dashboard JSON

Operating Pine

On XIAO nRF52840 + Wio SX1262, Pine runs the shared Lua engine beside a native repeater, with separate repeater and bot identities. It supports custom commands, personal notes, stored data, events, timers and mesh operations.

• Limits: two Lua job slots (at most one for custom or event work, so built-in commands keep capacity), 4,096-byte programs and a 48 KiB Lua memory quota. Check bot limits before installing a program.
• Trusted time: after each restart, an authenticated administrator sends bot time UNIX_SECONDS, and refreshes it at least hourly. Reminders and other deadlines wait in storage until time is set.
• Radio counters: bot radio shows queued, confirmed and failed or uncertain transmissions and RF time.
• BLE (optional): a MeshCore companion app can pair over BLE as Pine-Bot, using a locally set six-digit PIN. Pairings clear on restart; forget the old pairing on the phone and pair again. Repeater administration uses its separate authenticated console.

Pine production Lua · Pine notes and BLE

For a RAK4631 node, use the native repeater and notes-bot profile. The RAK13800 Ethernet option accepts MeshCore companion connections on port 5000.

ESP32 memory and flash

Full Aspen needs PSRAM and room for two application slots. The XIAO ESP32-S3R8 uses 8 MB flash; other board layouts are described in the board guide.

• Lua has a 96 KiB memory cap per program state.
• Wasm reserves a 1 MiB PSRAM interpreter pool on first use, kept until restart, plus 64 KiB of program memory per instance.
• The radio, WiFi, TLS and task stacks also need internal RAM.

Measured build sizes and memory budget

Continue

• Set up a nodeProfiles, installation and safe updates.
• Extend the botCommands, Lua, Wasm and HTTPS services.
• Source guidesDetailed references with the source.