15 KiB
Companion CLI
Since version 1.18 meshcore companion radio firmware has a CLI interface, which can be accessed locally (through companion radio protocol) or remotely via the network.
Navigation
Operational
Reboot the node
Usage:
reboot
Note: No reply is sent.
Power-off the node
Usage:
poweroff, orshutdown
Note: No reply is sent.
Configuration
System
View or change this node's name
Usage:
get nameset name <name>
Parameters:
name: Node name
Set by build flag: ADVERT_NAME
Default: Varies by board
Note: Advertised names can use up to 23 bytes when location is included and 31 bytes otherwise. Emoji and Unicode characters may take more than one byte. Names that exceed the available advert space are truncated at a valid UTF-8 code point boundary.
View this node's firmware version
Usage: ver
Configure this node's timezone
Usage:
set tz.offset <offset>get tz.offset
Parameters:
offset: float value of the offset in hours
Radio
Radio parameters are common to all roles and handled by CommonRadioPrefs.
View or change this node's radio parameters
Usage:
get radioset radio <freq>,<bw>,<sf>,<cr>
Parameters:
freq: Frequency in MHzbw: Bandwidth in kHzsf: Spreading factor (5-12)cr: Coding rate (5-8)
Set by build flag: LORA_FREQ, LORA_BW, LORA_SF, LORA_CR
Default: 869.618,62.5,8,5
Note: Requires reboot to apply
View or change this node's transmit power
Usage:
get txset tx <dbm>
Parameters:
dbm: Power level in dBm (1-22)
Set by build flag: LORA_TX_POWER
Default: Varies by board
Notes: This setting only controls the power level of the LoRa chip. Some nodes have an additional power amplifier stage which increases the total output. Refer to the node's manual for the correct setting to use. Setting a value too high may violate the laws in your country.
View or change this node's frequency
Usage:
get freqset freq <frequency>
Parameters:
frequency: Frequency in MHz
Default: 869.618
Note: Requires reboot to apply
Serial Only: set freq <frequency>
GPS
View GPS state
Usage:
gps
Note: Reports the requested state, receiver activity, last-fix status (last fix gives number of sats and how long ago was the fix), and mode. In periodic mode, waiting means the receiver is off between acquisitions; the last fix remains available. off(hw) means a hardware GPS switch is off.
Change GPS state
Usage:
gps <state>
Parameters:
state:on|off
View or change the GPS acquisition period
Usage:
gps periodgps period <value>
Parameters:
value:0for continuous tracking, or a period. The value can be postfixed withs,m,hordto specify the unit (seconds by default).
Note: A periodic acquisition stops after receiving a valid fix, then resumes after the configured period.
View the last GPS fix
Usage:
gps fix
Output:
> Fix (n sat): <lat>, <lon>: the GPS currently has a fix.> Last fix <age> ago (n sat)[, acq <time>]: <lat>, <lon>: position of the last valid fix;acqis shown only while the receiver is running and shows how for how long the gps has been trying to get a fix.> No fix[, acq <time>]: no valid fix since the node started.
Note: Ages and durations are given in s, m or h.
Sync this node's clock with GPS time
Usage:
gps sync
On demand GPS fix
Usage:
gps oncegps once -s
Parameters:
-s: also sync this node's clock with GPS time (asgps sync)
Note: Starts an acquisition now. If the GPS is off, it is switched and kept on until a valid fix and then turned off.
Reply: OK - turning on and acquiring (GPS was off), OK - waking gps (periodic mode, receiver off between acquisitions) or OK - gps already on. Error, gps hw switch off if a hardware GPS switch is off, Error, gps once not supported.
View GPS time to first fix statistics
Usage:
gps fix_stats
Output: > ttf:<last>/<max> ok:<n> miss:<n>: last and maximum time between a start of the GPS and its first valid fix, then the last count of consecutive starts with a fix (ok) or without one (miss).
View GPS diagnostics
Usage:
gps diag
View or change this node's rx boosted gain mode (SX12xx and LR1110)
Usage:
get radio.rxgainset radio.rxgain <state>
Parameters:
state:on|off
Default: on
View or change the LoRa FEM receive-path gain state on supported boards
Usage:
get radio.fem.rxgainset radio.fem.rxgain <state>
Parameters:
state:on|off
Notes:
- This controls the external LoRa FEM receive-path LNA where the board supports it.
- This is separate from
radio.rxgain, which controls the radio chip receive gain mode.
View or change the LoRa FEM transmit-path gain state on supported boards
Usage:
get radio.fem.txgainset radio.fem.txgain <state>
Parameters:
state:on|off
Notes:
- This controls a software-selectable external LoRa FEM transmit gain where the board supports it.
- On Station G3, remove the PA PL1 jumper to allow software control.
onselects PA PL1 high/short andoffselects PA PL1 low/open. The PA PL2 hardware jumper determines whether this switches between power levels 1/3 or 2/4. - Select an operating level and SX1262 transmit power that comply with local RF limits and the Station G3 power-supply requirements.
- The setting is saved immediately, but on Station G3 the level is applied to the hardware at the start of the next transmit, so that the PA supply rail is never re-targeted while the PA is being driven.
getreports the configured state, which may lead the hardware until the node next transmits.
View or change the duty cycle limit
Usage:
get dutycycleset dutycycle <value>
Parameters:
value: Duty cycle percentage (1-100)
Default: 50% (equivalent to airtime factor 1.0)
Examples:
set dutycycle 100— no duty cycle limitset dutycycle 50— 50% duty cycle (default)set dutycycle 10— 10% duty cycleset dutycycle 1— 1% duty cycle (strictest EU requirement)
Note: Added in firmware v1.15.0
View or change the airtime factor (duty cycle limit)
Deprecated as of firmware v1.15.0. Use
get/set dutycycleinstead.
Usage:
get afset af <value>
Parameters:
value: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example:af = 1→ ~50% dutyaf = 2→ ~33% dutyaf = 3→ ~25% dutyaf = 9→ ~10% duty You are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation).
Default: 1.0
View or change the local interference threshold
Usage:
get int.threshset int.thresh <value>
Parameters:
value: Interference threshold value
Default: 0.0
Enable or disable hardware Channel Activity Detection (CAD)
Usage:
get cadset cad <on|off>
Description: When enabled, the radio performs a hardware Channel Activity Detection scan before transmitting and defers if the channel is busy. Runs independently of int.thresh — either, both, or none may be active.
Parameters:
on|off: Enable or disable hardware CAD
Default: off
View or change the AGC Reset Interval
Usage:
get agc.reset.intervalset agc.reset.interval <value>
Parameters:
value: Interval in seconds, 0-1020, rounded down to a multiple of 4 (17 becomes 16). 0 to disable.
Default: 0.0
Enable or disable Multi-Acks support
Usage:
get multi.acksset multi.acks <state>
Parameters:
state:0(disable) or1(enable)
Default: 0
View or change this node's advert path hash size
Usage:
get path.hash.modeset path.hash.mode <value>
Parameters:
value: Path hash size (0-2)0: 1 Byte hash size (256 unique ids)[64 max flood]1: 2 Byte hash size (65,536 unique ids)[32 max flood]2: 3 Byte hash size (16,777,216 unique ids)[21 max flood]3: DO NOT USE (Reserved)
Default: 0
Note: the 'path.hash.mode' sets the low-level ID/hash encoding size used when the repeater adverts. This setting has no impact on what packet ID/hash size this repeater forwards, all sizes should be forwarded on firmware >= 1.14. This feature was added in firmware 1.14
View or change the retransmit delay factor for flood traffic
Usage:
get txdelayset txdelay <value>
Parameters:
value: Transmit delay factor (0-2)
Default: 0.5
Note: When multiple nearby repeaters all hear the same flood packet, each waits a random amount of time before retransmitting to avoid simultaneous collisions. This factor scales the size of that random window. Higher values reduce collision risk at the cost of added latency. 0 disables the window entirely.
View or change the retransmit delay factor for direct traffic
Usage:
get direct.txdelayset direct.txdelay <value>
Parameters:
value: Direct transmit delay factor (0-2)
Default: 0.3 (Repeater) - 0.2 (Room Server, Sensor)
Note: Same collision-avoidance random window as txdelay, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.
[Experimental] View or change the processing delay for received traffic
Usage:
get rxdelayset rxdelay <value>
Parameters:
value: Receive delay base (0-20)
Default: 0.0
Note: When enabled, repeaters that received a flood packet with a weak signal are held in a delay queue before processing, while those that received it with a strong signal process it immediately. This gives strong-signal paths forwarding priority. By the time weak-signal nodes process their copy, the packet may have already propagated and will be suppressed as a duplicate, reducing redundant retransmissions.
BLE
Change BLE PIN
Usage:
set pin <pin>
Parameters:
pin: New BLE PIN
Set by build flag: BLE_PIN_CODE
Wifi
Get status
Usage:
get wifi.statusget wifi.ip
Toggle
Usage:
set wifi.enabled <value>get wifi.enabled
Parameters:
value:0(disable) or1(enable)
Set SSID
Usage:
set wifi.ssid <value>get wifi.ssid
Parameters:
value: ssid as a string
Set password
Usage:
set wifi.pwd <value>get wifi.pwd
Parameters:
value: password string
UI
Show clock
Usage:
set ui.show_clock <state>get ui.show_clock
Parameters:
state:0(disable) or1(enable)
Default: 0 (or UI_SHOW_CLOCK build flag)
GPS key action
Usage:
set ui.gps_action <action>get ui.gps_action
Parameters:
action:toggle(or0) to switch the GPS on and off,once(ortrigger,1) to acquire a fix on demand, asgps once
Default: toggle, or once on boards with a GPS switch
Note: Only used by the ui-new screens for now.
Node discovery screen shows nodes names
Usage:
set ui.nd_name <state>get ui.nd_name
Parameters:
state:1(show name) or0(show pubkey_prefix)
Default: 1
Note: When showing name, there is not always enough space to draw both incoming and outgoing snr values.
Auto-off screen
Usage:
set ui.auto_off_delay <delay>get ui.auto_off_delay
Parameters:
delay: in seconds (0means always on)
Default: 15 (or set by AUTO_OFF_MILLIS build flag (in ms))
Note:
On e-ink displays, when turned off, the screen is not necessarily blanked, see ui.auto_off_blank and ui.backlight_delay.
When screen is not blanked, it is not refreshed any more. To let the user aware of that, a sleep icon is shown.
Display backlight timeout
Usage:
set ui.backlight_delay <delay>get ui.backlight_delay
Parameters:
delay: in seconds0means no timeout-2means always off-1means always on
Note:
When set to 0, backlight can only be triggered using backlight btn.
When to turn backlight on
Usage:
set ui.backlight_on_keys <state>get ui.backlight_on_keysset ui.backlight_on_msgs <state>get ui.backlight_on_msgs
Parameters:
state:0(disable) or1(enable)
Default:
ui.backlight_on_msgs = 0ui.backlight_on_keys = 0if there is a backlight button on the board, else1
Note:
By default backlight is triggered by backlight button if present (as long as the button is pressed backlight is on, and is turned off after a delay).
These toggles permits to toggle backlight when keys are pressed or when a message arrives (it acts as a notification signal).
If backlight_delay is set to 0 then this setting has no effect, backlight won't be turned on.
Control if eink screen should be blanked
Usage:
set ui.auto_off_blank <state>get ui.auto_off_blank
Parameters:
state:0(disable) or1(enable)
Default: 0 (or set by UI_SCREENOFF_BLANK build flag)
Note: If disabled, when screen is shut the displays stays on screen and is not updated (an sleep icons covers battery to show the screen is sleeping).
When screen is blanked, the controller is also put into hibernation, which should preserve the screen a little and some battery ...
Maximum number of partial refreshes
Usage:
set ui.max_partial <value>get ui.max_partial
Parmeters:
value: max partial refreshes before doing a full refresh
Default: 0 (no partial refresh or set by EINK_MAX_PARTIAL_REFRESH build flag)
Note:
Forcing full refresh helps revives the screen when some tearing appears (under certain environmental conditions). If you see some tearing appearing, you can force full refresh on your screen manually by double clicking the backlight button. If tearing reappears often, use this setting to force full refresh every value partial refreshes.