Appearance
Environment variables
Complete reference of the MeshSat Bridge environment variables.
Environment values are first-boot defaults. Once the bridge has started, the dashboard writes its own configuration to the database and that takes precedence, so changing a variable later only affects a setting the dashboard has never touched.
See the Configuration guide for the settings most people need.
Core
| Variable | Default | Description |
|---|---|---|
MESHSAT_MODE | cubeos | Set to direct for standalone USB access |
MESHSAT_PORT | 6050 | HTTP port for dashboard and API |
MESHSAT_DB_PATH | /cubeos/data/meshsat.db | SQLite database path. The standalone compose file sets this to /data/meshsat.db |
MESHSAT_RETENTION_DAYS | 30 | Days of message and telemetry history to keep |
MESHSAT_WEB_DIR | "" | Override the embedded SPA path. Development only |
Serial ports
auto scans USB by VID:PID table and protocol probe. Pin a port explicitly when two devices share a VID:PID, which happens with some ZigBee and Meshtastic boards.
| Variable | Default | Description |
|---|---|---|
MESHSAT_MESHTASTIC_PORT | auto | Meshtastic radio |
MESHSAT_IRIDIUM_PORT | auto | Iridium 9603N (SBD) |
MESHSAT_IMT_PORT | auto | RockBLOCK 9704 (IMT/JSPR) |
MESHSAT_CELLULAR_PORT | auto | Cellular modem |
MESHSAT_ZIGBEE_PORT | auto | ZigBee coordinator |
Iridium 9603N GPIO
Only the SBD modem uses GPIO. The 9704 is USB and needs none of these.
| Variable | Default | Description |
|---|---|---|
MESHSAT_GPIO_CHIP | gpiochip4 | libgpiod chardev. Pi 5 is 4, Pi 4 is 0 |
MESHSAT_IRIDIUM_SLEEP_PIN | 0 | Sleep and wake GPIO, BCM numbering, 0 disables |
MESHSAT_IRIDIUM_NETAV_PIN | 0 | Network Available input, high means satellite visible |
MESHSAT_IRIDIUM_RI_PIN | 0 | Ring indicator input, active low |
IRIDIUM_SBDIX_TIMEOUT | 90 | SBDIX timeout in seconds. Note the missing MESHSAT_ prefix |
Routing and rate limiting
| Variable | Default | Description |
|---|---|---|
MESHSAT_PAID_RATE_LIMIT | 60 | Minimum seconds between paid satellite sends |
MESHSAT_MAX_HOPS | 8 | Maximum interfaces a message may traverse |
MESHSAT_MESH_WATCHDOG_MIN | 0 | Minutes of channel silence before the Meshtastic serial port is reopened. 0 disables it, and the device-health mesh probe covers a stalled radio. A radio that still answers local requests is never reopened |
MESHSAT_MESH_MTU | 100 | Largest text in bytes the delivery intents send on the mesh, range 1 to 237 |
SMS bundle counter
For prepaid SIMs. The counter tracks +CMGS results against the bundle and warns before it runs out.
| Variable | Default | Description |
|---|---|---|
MESHSAT_SMS_BUNDLE_SIZE | 0 | Bundle size in segments, 0 disables the counter. First-boot default only. Record a top-up with PUT /api/cellular/bundle {"size":250} |
MESHSAT_SMS_BUNDLE_WARN_AT | 50 | Segments left that turn the SMS chip amber, log a warning and send the reminder once per bundle |
MESHSAT_SMS_ALERT_NUMBER | "" | E.164 number that receives the top-up reminder. Also settable as alert_number on the bundle API |
Out of band management
Authenticated single-message commands that ride any bearer, so a bridge that has lost its network can still be reached over SMS or APRS.
| Variable | Default | Description |
|---|---|---|
MESHSAT_OOB_ENABLED | false | Accept authenticated OOB commands. First-boot default, managed in the dashboard afterwards |
MESHSAT_OOB_REPLY_BUDGET | 12 | OOB replies per peer per hour |
MESHSAT_OOB_HOST_SOCKET | /run/meshsat-oob/agent.sock | Host agent socket, installed by scripts/install-oob-agent.sh |
MESHSAT_OOB_REQUEST_TTL_MIN | 15 | Minutes a command this bridge sends stays valid. A peer that receives it later, for example a satellite message held until the kit had sky, refuses it |
MESHSAT_OOB_EXPIRY_SKEW_S | 120 | Clock difference allowed when judging whether a received command has expired. Not judged at all while the kit's clock is not established |
Hub uplink fallback
When the MQTT link to a Hub goes down, the bridge can keep reporting over a satellite or SMS bearer, sending compact position, health and SOS frames instead of the full telemetry stream.
| Variable | Default | Description |
|---|---|---|
MESHSAT_HUB_SAT_FALLBACK | true | Enable the fallback uplink |
MESHSAT_HUB_SMS_NUMBER | "" | Hub inbound number for the SMS leg, empty disables it |
MESHSAT_HUB_FALLBACK_AFTER_MIN | 5 | Minutes of broker loss before the first frame |
MESHSAT_HUB_FALLBACK_POSITION_MIN | 15 | Minutes between position frames while down |
MESHSAT_HUB_FALLBACK_HEALTH_MIN | 60 | Minutes between health frames while down |
MESHSAT_HUB_FALLBACK_BEARER | auto | auto, satellite or sms. auto prefers satellite only when that gateway is connected and recently active |
MESHSAT_IMT_MT_POLL_MIN | 10 | Minutes a RockBLOCK 9704 may go without a satellite session before the bridge sends a short health report over it, so messages waiting at Iridium come down. 0 turns it off |
Hub relay
| Variable | Default | Description |
|---|---|---|
MESHSAT_HUB_RELAY_ENABLED | true | Serve this bridge's API to the tenant's phones through the Hub WebSocket relay. The bridge is the TLS server of every tunnel, so the Hub carries ciphertext only |
MESHSAT_HUB_API_URL | "" | Hub HTTPS API base. Empty derives it from the MQTT URL |
Compression sidecars
Both sidecars are optional. Without them SMAZ2 still works, since it is built in.
| Variable | Default | Description |
|---|---|---|
MESHSAT_LLAMAZIP_ADDR | "" | llama-zip gRPC sidecar address |
MESHSAT_LLAMAZIP_TIMEOUT | 30 | RPC timeout in seconds |
MESHSAT_MSVQSC_ADDR | "" | MSVQ-SC gRPC sidecar address |
MESHSAT_MSVQSC_TIMEOUT | 30 | RPC timeout in seconds |
MESHSAT_MSVQSC_CODEBOOK | "" | Codebook path, enables pure Go decode |
Reticulum interfaces
| Variable | Default | Description |
|---|---|---|
MESHSAT_TCP_LISTEN | "" | TCP listen address for RNS interop, for example :4242 |
MESHSAT_TCP_CONNECT | "" | Outbound TCP peer address for RNS interop |
MESHSAT_ANNOUNCE_INTERVAL | 300 | Announce broadcast interval in seconds |
MESHSAT_TIMESYNC_DISCOVERY_MIN | 10 | Minutes between time sync requests on an interface where no other bridge has answered. Where one has, the request goes every 30 s |
MESHSAT_MQTT_RETICULUM_BROKER | "" | MQTT broker for Reticulum packets |
MESHSAT_MQTT_RETICULUM_PREFIX | reticulum/meshsat | MQTT topic prefix |
MESHSAT_RNS_IFAC_NETNAME, MESHSAT_RNS_IFAC_NETKEY | "" | Interface access code (network name and passphrase) on the TCP interface, as in rnsd |
MESHSAT_RNS_PATH_TTL_HOURS | 168 | Path table lifetime, one week like upstream |
MESHSAT_LXMF_ENABLED | true | Run the LXMF endpoint |
MESHSAT_LXMF_DISPLAY_NAME | MeshSat <hostname> | Name announced with the LXMF destination |
MESHSAT_LXMF_STAMP_COST | 0 | Stamp cost demanded of senders (0 = none) |
MESHSAT_LXMF_MAX_OUTBOUND_STAMP_COST | 16 | Highest stamp cost the bridge will compute for a peer |
MESHSAT_LXMF_ANNOUNCE_INTERVAL | 1800 | LXMF announce interval in seconds |
MESHSAT_RNODE_PORT | "" | Seeds an RNode interface once: auto, usb_serial:<sn>, a device path, tcp://host, ble://name. Settings > Routing owns it afterwards |
MESHSAT_RNODE_PRESET | eu-868 | us-915, eu-868, au-915, ism-433; MESHSAT_RNODE_FREQUENCY, _BANDWIDTH, _SF, _CR, _TXPOWER, _AIRTIME_SHORT, _AIRTIME_LONG override single fields |
MESHSAT_RNODE_FLOW_CONTROL, MESHSAT_RNODE_ID_CALLSIGN, MESHSAT_RNODE_ID_INTERVAL | false, "", 600 | READY flow control and the station identification beacon |
MESHSAT_UDP_LISTEN, MESHSAT_UDP_FORWARD, MESHSAT_UDP_DEVICE | "" | Seeds a UDP interface once; a device derives both addresses from its broadcast address |
MESHSAT_AUTO_IFACE_DEVICES, MESHSAT_AUTO_IFACE_GROUP | "", reticulum | Seeds an AutoInterface once on the named devices (never wlan0) |
MESHSAT_KISS_PORT, MESHSAT_KISS_BAUD, MESHSAT_KISS_FLOW_CONTROL | "", 115200, false | Seeds a KISS TNC interface once; tcp://host:8100 for a Mercury modem |
MESHSAT_IMT_RNS_FRAMING | false | CrossTalk's RNSI header on packets over Iridium IMT; the Routing settings override it live |
MESHSAT_HF_RX_ENABLED, MESHSAT_HF_FREQ_HZ | false, 28124000 | Seeds the 10 m HF gateway once; receive borrows the RTL-SDR |
MESHSAT_HF_RTLTCP_PORT, MESHSAT_HF_RTL_GAIN_DB | 6057, 20 | The HF gateway's own rtl_tcp |
MESHSAT_HF_TX_CALLSIGN, MESHSAT_HF_TX_AUDIO_DEVICE, MESHSAT_HF_TX_CAT_PORT | "" | HF transmit: locked without a callsign; ALSA device and CAT serial port of the radio |
APRS and AX.25
| Variable | Default | Description |
|---|---|---|
MESHSAT_AX25_KISS_ADDR | "" | KISS TNC address. The bundled Direwolf binds localhost:8001 |
MESHSAT_AX25_CALLSIGN | "" | AX.25 source callsign, for example MESHSAT-1 |
MESHSAT_AX25_BITRATE | 1200 | The KISS modem's bit rate. Time sync requests on AX.25 are spaced to stay within 2% of it |
MESHSAT_AIOC_CAPTURE | 94% | Capture gain applied at every Direwolf start. Mixer scale, 94 % is -5.8 dB and 90 % is -9.6 dB. Lower it if Direwolf reports the audio input level as too high |
MESHSAT_APRS_RX_WATCHDOG_MIN | 5 | Minutes without a decoded frame, after the channel was heard within two hours, before the recovery ladder runs. A deaf receiver scores 0 for failover. 0 disables |
Key exchange
| Variable | Default | Description |
|---|---|---|
MESHSAT_KEY_PASSPHRASE | "" | Master key passphrase. Empty means device-derived |
MESHSAT_BUNDLE_VERSION | v2 | Key bundle format. v2 carries a signing public key, v1 is legacy |
See Security and key exchange for what the bundle format means in practice.