Manage a node. Upload a command over LoRa.

Choose the connection you have

• Use the Management public key from your existing setup/contact, not the bot key. Management advertises a repeater-type CLI endpoint but does not forward packets.
• Match the complete PHY: frequency, bandwidth, spreading factor and coding rate. Keep existing identities/settings; do not retune production radios just to try the guide.
• Obtain authorization: the existing Management password, or an already authorized full sender public key. Public channels and radio proximity do not authorize administration.

Open the Management console over RF

In an app that exposes the native repeater administrator console, select the Management contact, log in and send status, then bot status. Use the admin console, not ordinary bot chat. App menu names vary; if yours does not expose this console, use meshcli with a companion radio:

meshcli -s /dev/serial/by-id/YOUR_COMPANION

Or connect to a native companion TCP endpoint with meshcli -t COMPANION_HOST -p COMPANION_PORT. That port is not KISS. In the interactive console, replace the key and password placeholders locally:

add_contact MANAGEMENT_PUBLIC_KEY64 2 mast
reset_path mast
login mast ADMIN_PASSWORD
cmd mast status
wmt8
cmd mast "bot status"
wmt8
cmd mast "source status"
wmt8

For an already authorized full companion key, use login mast "". cmd does not request a delivery ACK. Read the native encrypted CLI reply with wmt8, or sync_msgs for replies already queued. Keep console history containing a password private.

Install one Lua command from a file over LoRa

This file route uses a different sender setup from the console above. You need a separate MeshCore KISS gateway radio reachable over TCP, the source checkout and a Python environment with the admin client dependencies. The gateway transmits the client's encrypted packets; it is not the target Aspen.

Need a gateway? Follow the WiFi modem setup on a different radio. You do not need to start a Go host just to use that modem's KISS port.

Use an existing operator-managed 32-byte Ed25519 sender seed file and a password file, both private regular files with mode 0600. The password file contains only the password, with no final newline. The client owns this sender identity; it need not be your mobile app's identity. Do not extract private keys from an app or radio. Omit the password file only when this client's full public key is already authorized.

python3 - /absolute/private/rf-client.seed <<'PY'
import os, secrets, sys
from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.hazmat.primitives import serialization
seed = secrets.token_bytes(32)
fd = os.open(sys.argv[1], os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
with os.fdopen(fd, "wb") as output:
    output.write(seed)
    output.flush()
    os.fsync(output.fileno())
public = ed25519.Ed25519PrivateKey.from_private_bytes(seed).public_key()
print("Client public key:", public.public_bytes(
    serialization.Encoding.Raw, serialization.PublicFormat.Raw).hex())
PY

Keep the gateway network private. KISS and native companion TCP are unencrypted network services; use a trusted LAN or protected tunnel. --gateway does not connect to app BLE, native companion TCP or Aspen's web admin page. RF login and CLI packets sent by this client are encrypted.

1. Read capabilities and save the current set

   Run from the source repository root. Substitute your own gateway, full Management key and protected file paths in every invocation:

   python3 tools/hardware/admin.py \
     --gateway KISS_GATEWAY_HOST --port 8001 --target MANAGEMENT_PUBLIC_KEY64 \
     --seed-file /absolute/private/rf-client.seed \
     --password-file /absolute/private/node-password \
     command 'source api sources'
   python3 tools/hardware/admin.py \
     --gateway KISS_GATEWAY_HOST --port 8001 --target MANAGEMENT_PUBLIC_KEY64 \
     --seed-file /absolute/private/rf-client.seed \
     --password-file /absolute/private/node-password \
     download saved-source.lua
   chmod 600 saved-source.lua

   Expected: the capability reply includes format=meshcore-sources/1 and commit-base=sha256. The download verifies full readback and writes a new file; chmod makes that backup private. Keep it out of public commits. With the same options, source-list lists names and source-export NAME NEW_FILE exports one installed file.

2. Save and test a greeting

   Download hello.lua or save the following as UTF-8 with LF newlines and a final newline:

   function hello(name)
     return "Hello " .. name
   end
   command("hello", "name:string:32", "Greet a name",
           "hello", "public", "!hello mesh")

   Test the greeting locally before using airtime. Choose a source name not used by an unrelated file. Duplicate command names reject the candidate.

3. Add the named file and wait for activation

   python3 tools/hardware/admin.py \
     --gateway KISS_GATEWAY_HOST --port 8001 --target MANAGEMENT_PUBLIC_KEY64 \
     --seed-file /absolute/private/rf-client.seed \
     --password-file /absolute/private/node-password \
     source-install greeting hello.lua
   python3 tools/hardware/admin.py \
     --gateway KISS_GATEWAY_HOST --port 8001 --target MANAGEMENT_PUBLIC_KEY64 \
     --seed-file /absolute/private/rf-client.seed \
     --password-file /absolute/private/node-password status

   Expected: Durable chunk N/TOTAL, acceptance of verification, then source durably saved and active. The client verifies the selected hash. The file named greeting changes; other files remain. A concurrent source update rejects the conditional commit rather than overwriting that update.

   A disabled bot reports source saved; bot disabled; loads on next enabled boot. Inspect its channel policy before enabling/restarting. If activation is still pending when the client times out, inspect source status and source hash instead of repeating the install.

4. Switch to the bot conversation

   From a separate companion on the same PHY, advertise your companion so the bot learns its contact, then open the bot's ordinary private DM:

   1. You!hello mesh
   2. BotHello mesh
   3. You!help hello

   Generated help describes the argument and example. This uses the bot's key, not Management's. A reply reflected through the node's own Base is not reception by another radio.

Understand the transfer and its replies

The client logs in to Management, admits an upload, sends numbered 48-byte chunks and starts verification. Each durable chunk reply confirms readback and saved progress. Commit acceptance is only the start: read status until activation finishes, then check the hash.

Admin commands you can use over LoRa

After Management login, begin with read-only checks. In meshcli, use cmd mast "COMMAND" and wmt8. In the Python client, use the RF connection options above followed by command 'COMMAND'. Consult help and help TOPIC PAGE on your actual build before changing anything.

Command catalog and service guides · Exact syntax, units and limits · Safe addressed-only channel walkthrough.

Recover without erasing the node

Management does not answer

Check the destination key, native admin login, route and complete PHY. Read queued replies with sync_msgs. Do not confuse native companion TCP with KISS.

A chunk reply is lost

A matching source begin reports saved progress; only repeat the identical numbered chunk. The current source remains selected during upload.

Commit, install or restart is uncertain

Read source status, source hash, status and the affected saved/live settings before retrying. Do not blindly replay a mutation.

A candidate is rejected

Inspect the error; the old source remains selected. Fix the size, hash, command collision or initialization failure locally before a new explicit attempt.

The durable selection cannot run

Inspect bot readiness and source status, then choose source retry, source rollback or source remove. Removal restores bundled handlers and removes the installed set; rollback restores code/help, not data.

Native Management remains available when the bot is disabled or custom source is quarantined. Source repair is not provisioning: do not format, erase flash or replace identities to install a command.

More command tutorials · Node administration overview · Source RF walkthrough.