Manage a node. Upload a command over LoRa.

Choose the connection you have

• Use the Management public key from your existing setup/contact. Management advertises a repeater-type CLI endpoint for administration; forwarding remains with the repeater role.
• Match the complete PHY: frequency, bandwidth, spreading factor and coding rate. Keep production radios on their existing profile and use a separate test radio for another PHY.
• Obtain authorization: use the existing Management password or an already authorized full sender public key. Public channels and radio proximity carry no administrative authority.

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. App menu names vary; if yours lacks 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. Raw KISS uses a separate endpoint. 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 sends without requesting 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

Use 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 to the target Aspen.

Need a gateway? The WiFi modem setup prepares a separate radio with the KISS endpoint this route needs.

Use an 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 can use a dedicated identity or an existing operator-managed identity. Keep app and radio private keys in their original stores. Omit the password file 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. Give --gateway the raw KISS TCP endpoint, usually port 8001. 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/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/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 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/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/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 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 and preserves 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. Send chat commands to the bot's contact. Use a separate companion radio when checking replies over RF.

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. Verify whether your client expects native companion TCP or raw 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 any retry.

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 and help while preserving stored data.

Management remains available when the bot is disabled or custom source is quarantined. Use it to repair the selected program without formatting flash or replacing identities.

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