Skip to content

Companion CLI

Companions accept local CLI commands through the Companion protocol. Remote commands require the configured admin permission. Available commands depend on the board and firmware profile; use help for the commands in your build.

Common commands

Purpose Commands
Firmware version ver
Node name get name, set name <name>
Radio profile get radio, set radio <MHz>,<kHz>,<SF>,<CR>
Frequency get freq, set freq <MHz>
Transmit power get tx, set tx <dBm>
Radio apply status get radio.apply
Timezone, hours get tz.offset, set tz.offset <hours>
Airtime limit get dutycycle, set dutycycle <percent>
Receive gain get radio.rxgain, set radio.rxgain <on/off>
Device power saving get powersaving, set powersaving <on/off>
GPS status, power and clock sync (GPS builds) gps, gps on, gps off, gps sync
Receive power saving get radio.rxps, get radio.rxps.config
FEM receive gain get radio.fem.rxgain, set radio.fem.rxgain <on/off>
FEM transmit gain get radio.fem.txgain, set radio.fem.txgain <on/off>
BLE PIN set pin <0-999999>
Restart reboot
Power off, where supported poweroff or shutdown

Supported frequencies, bandwidths and power limits depend on the radio and board. RF changes may wait for active traffic; get radio.apply reports the apply state. Transmit power is the radio-chip setting, which can differ from antenna output on amplified boards.

See CLI commands for setting ranges and access restrictions, and radio profiles for radio2, temporary profiles and schedules.

Power saving

On ESP32 Bluetooth Companions, set powersaving on requests a 15-30 ms connection interval during app sync and 60-75 ms after two seconds of quiet. Three closely spaced incoming app frames return the link to fast timing. Mesh traffic sent to the phone does not count as app activity. With set powersaving off, the link stays on the fast profile. The phone chooses the actual connection interval.

ESP32 Companions with hardware USB Serial/JTAG and a tickless power-management build can use automatic light sleep during short idle periods on battery. A USB host or its reconnect grace period holds the device awake.

Wi-Fi

Wi-Fi builds expose get wifi.status, get wifi.ip, and get/set wifi.enabled. Configure credentials with set wifi.ssid <SSID> and set wifi.pwd <password>. Credential access follows the normal local/admin restrictions. Reboot after saving Wi-Fi settings to apply them.

Heltec V4 Wi-Fi builds also advertise _meshcore._tcp through mDNS once their TCP listener is enabled and Wi-Fi connects. The hostname follows the existing meshcore-<node-name> DHCP naming policy; TXT fields identify the node, firmware and Companion protocol. Discovery follows node renames and stops when the listener or Wi-Fi is disabled. Other ESP32 Wi-Fi recipes can opt in with ENABLE_ESP_MDNS at build time.

Display and notifications

This fork uses the saved display.* controls described in display controls:

get display.mode
get display.timeout
get display.usb.mode
get display.usb.timeout
get display.inbox

Timeouts default to 900 seconds on e-paper and 15 seconds on other screens. Battery and USB settings are independent. Display settings live in a separate checked preferences file and preserve the existing node-preferences layout. The upstream ui.* settings are not aliases in this fork.

For sound, vibration and custom notification rules, see notifications.