### MeshCore Firmware Build Setup

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Steps to set up a MeshCore build environment, including creating a virtual environment, installing PlatformIO, and cloning the MeshCore repository. This process is consistent across Linux, Windows (with WSL), and macOS.

```bash
python3 -m venv meshcore
cd meshcore && source bin/activate
pip install -U platformio
git clone https://github.com/ripplebiz/MeshCore.git
cd MeshCore
```

--------------------------------

### App Start Command Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Initializes communication with the device. This command must be sent first after establishing a BLE connection. The optional application name is UTF-8 encoded.

```hex
01 00 00 00 00 00 00 00 6d 63 63 6c 69
```

--------------------------------

### Simple Room Server Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example of a simple BBS server for sharing Posts.

```bash
cd examples/simple_room_server
```

--------------------------------

### Start Packet Logging

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Starts logging packets to the device's file system.

```cli
log start
```

--------------------------------

### Install MkDocs and Material Theme

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/docs.md

Install the necessary Python packages for building documentation with MkDocs and the Material theme.

```bash
pip install mkdocs
pip install mkdocs-material
```

--------------------------------

### Get Channel Info Command Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Retrieves information about a specific channel. The channel index ranges from 0 to 7.

```hex
1f 01
```

--------------------------------

### Serve Local Documentation

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/docs.md

Start the live-reloading documentation server to preview changes as you make them.

```bash
mkdocs serve
```

--------------------------------

### App Start Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Command to start an application. `code` must be 1. The `app_name` field contains the remainder of the frame.

```protobuf
CMD_APP_START {
  code: byte,     // constant: 1
  app_ver: byte,
  reserved: bytes(6),
  app_name: varchar   // remainder of frame 
}
```

--------------------------------

### LittleFS Example: Boot Count Update

Source: https://github.com/meshcore-dev/meshcore/blob/main/arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/README.md

This example demonstrates how to initialize, mount, read, write, and unmount the LittleFS filesystem. It updates a boot count file, ensuring data integrity even if interrupted.

```c
#include "lfs.h"

// variables used by the filesystem
lfs_t lfs;
lfs_file_t file;

// configuration of the filesystem is provided by this struct
const struct lfs_config cfg = {
    // block device operations
    .read  = user_provided_block_device_read,
    .prog  = user_provided_block_device_prog,
    .erase = user_provided_block_device_erase,
    .sync  = user_provided_block_device_sync,

    // block device configuration
    .read_size = 16,
    .prog_size = 16,
    .block_size = 4096,
    .block_count = 128,
    .lookahead = 128,
};

// entry point
int main(void) {
    // mount the filesystem
    int err = lfs_mount(&lfs, &cfg);

    // reformat if we can't mount the filesystem
    // this should only happen on the first boot
    if (err) {
        lfs_format(&lfs, &cfg);
        lfs_mount(&lfs, &cfg);
    }

    // read current count
    uint32_t boot_count = 0;
    lfs_file_open(&lfs, &file, "boot_count", LFS_O_RDWR | LFS_O_CREAT);
    lfs_file_read(&lfs, &file, &boot_count, sizeof(boot_count));

    // update boot count
    boot_count += 1;
    lfs_file_rewind(&lfs, &file);
    lfs_file_write(&lfs, &file, &boot_count, sizeof(boot_count));

    // remember the storage is not updated until the file is closed successfully
    lfs_file_close(&lfs, &file);

    // release any resources we were using
    lfs_unmount(&lfs);

    // print the boot count
    printf("boot_count: %d\n", boot_count);
}

```

--------------------------------

### Companion Radio Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example for a companion radio, intended for use with external chat applications over BLE, USB, or Wi-Fi.

```bash
cd examples/companion_radio
```

--------------------------------

### Simple Sensor Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example of a remote sensor node that includes telemetry and alerting capabilities.

```bash
cd examples/simple_sensor
```

--------------------------------

### Install picocom for Serial Management

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Install the picocom utility using apt. This tool is used to manage devices connected via USB serial.

```bash
sudo apt install picocom
```

--------------------------------

### KISS Modem Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example for a serial KISS protocol bridge, used for host applications. Refer to the protocol documentation for details.

```bash
cd examples/kiss_modem
```

--------------------------------

### Install esptool for ESP32-S3

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Install the esptool package using pip. The --break-system-packages flag may be required on some systems.

```bash
pip install esptool --break-system-packages
```

--------------------------------

### Install adafruit-nrfutil for nRF Devices

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Install the adafruit-nrfutil package using pip. This tool is required for flashing nRF devices.

```bash
pip install adafruit-nrfutil --break-system-packages
```

--------------------------------

### CMD_APP_START

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

The initial command sent by the app to the radio upon starting. The radio responds with RESP_CODE_SELF_INFO(5).

```APIDOC
## CMD_APP_START

### Description
This command should be the very first request the app sends to the radio. It signals the application's start.

### Command Code
1

### Expected Response
RESP_CODE_SELF_INFO (5)
```

--------------------------------

### App Start

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Initializes communication with the device. This command must be sent first after establishing a BLE connection. It can optionally include an application name.

```APIDOC
## App Start

### Description
Initializes communication with the device. Must be sent first after connection.

### Command Format
```
Byte 0: 0x01
Bytes 1-7: Reserved (currently ignored by firmware)
Bytes 8+: Application name (UTF-8, optional)
```

### Example (hex)
```
01 00 00 00 00 00 00 00 6d 63 63 6c 69
```

### Response
`PACKET_SELF_INFO` (0x05)
```

--------------------------------

### Device Query Command Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Queries device information. This command is used to retrieve details about the connected device.

```hex
16 03
```

--------------------------------

### Simple Repeater Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example of a simple repeater designed to extend network coverage by relaying messages.

```bash
cd examples/simple_repeater
```

--------------------------------

### Contacts Start Response Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Indicates the start of contact data transmission. `code` must be 2. Contains the total `count` of contacts to be sent.

```protobuf
RESP_CODE_CONTACTS_START {
  code: byte,   // constant 2
  count: uint32    // total number of contacts
}
```

--------------------------------

### Install Build Dependencies on Debian/Ubuntu

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Install necessary build dependencies for MeshCore firmware compilation on Debian-based systems like Ubuntu. This includes Python development headers and virtual environment support.

```bash
sudo apt update
sudo apt install libpython3-dev
sudo apt install python3-venv
```

--------------------------------

### Simple Secure Chat Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Example for secure terminal-based text communication between devices. Can be interacted with via Serial Monitor or a Serial USB Terminal.

```bash
cd examples/simple_secure_chat
```

--------------------------------

### Set Channel Command Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Creates or updates a channel on the device. Supports private and public channels with specific naming and secret requirements. Channel names are UTF-8 encoded and null-padded to 32 bytes.

```hex
20 01 53 4d 53 00 00 ... (name padded to 32 bytes)
    [16 bytes of secret]
```

--------------------------------

### Run LittleFS Tests

Source: https://github.com/meshcore-dev/meshcore/blob/main/arch/stm32/Adafruit_LittleFS_stm32/src/littlefs/README.md

Execute the LittleFS test suite on a Linux environment using the emulated block device. Ensure you have the necessary build tools installed.

```bash
make test
```

--------------------------------

### Start picocom Session for USB Serial Device

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Initiate a picocom session to manage a device connected via USB serial. Adjust the baud rate and device path as necessary.

```bash
picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf
```

--------------------------------

### CMD_GET_ADVERT_PATH Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Request to get the advertisement path for a specific contact. Includes the contact's public key.

```protobuf
CMD_GET_ADVERT_PATH {
  code: byte,    // constant: 42
  reserved: byte,    // zero
  pub_key: bytes(32)   // public key of contact being queried
}
```

--------------------------------

### Search for regions by name prefix

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Use 'region get' with a name prefix or '*' to search for regions. It returns the region name, parent name, and flood permission status.

```bash
region get {* | name-prefix}
```

--------------------------------

### Set Transmit Power via Command Line

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Use the 'set tx' command for repeater and room server radios to adjust transmit power. Use 'get tx' to retrieve the current setting. Exercise caution as incorrect settings can damage hardware.

```bash
set tx
get tx
```

--------------------------------

### Get Contacts Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Command to request contact list. `code` must be 4. Optionally includes a `since` parameter to fetch contacts modified after a specific timestamp.

```protobuf
CMD_GET_CONTACTS {
  code: byte,   // constant 4
  (optional) since: uint32,   // the last contact.lastmod value already received
}
```

--------------------------------

### Send Channel Message Command Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Sends a text message to a specified channel. Includes a 32-bit little-endian Unix timestamp and UTF-8 encoded message text.

```hex
03 00 01 d2 02 96 49 48 65 6c 6c 6f
```

--------------------------------

### Build Static Documentation Site

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/docs.md

Generate the static HTML files for the documentation site.

```bash
mkdocs build
```

--------------------------------

### Initialize MeshCore Device Connection

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

This snippet demonstrates the initialization flow for connecting to a MeshCore device. It covers scanning, BLE GATT connection, service and characteristic discovery, enabling notifications, and sending the initial AppStart command.

```python
# 1. Scan for MeshCore device
device = scan_for_device("MeshCore")

# 2. Connect to BLE GATT
gatt = connect_to_device(device)

# 3. Discover services and characteristics
service = discover_service(gatt, "6E400001-B5A3-F393-E0A9-E50E24DCCA9E")
rx_char = discover_characteristic(service, "6E400002-B5A3-F393-E0A9-E50E24DCCA9E")
tx_char = discover_characteristic(service, "6E400003-B5A3-F393-E0A9-E50E24DCCA9E")

# 4. Enable notifications on TX characteristic
enable_notifications(tx_char, on_notification_received)

# 5. Send AppStart command
send_command(rx_char, build_app_start())
wait_for_response(PACKET_SELF_INFO)
```

--------------------------------

### Download ESP Firmware using wget

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Use wget to download the firmware file for ESP-based devices. If the initial download is small, use the alternative command with a user agent and content disposition.

```bash
wget https://flasher.meshcore.io/releases/download/companion-v1.7.1/Heltec_v3_companion_radio_ble-v1.7.1-165fb33.bin
```

```bash
wget --user-agent="Mozilla/5.0" --content-disposition "https://flasher.meshcore.io/releases/download/companion-v1.7.1/Heltec_v3_companion_radio_usb-v1.7.1-165fb33.bin"
```

--------------------------------

### Send Channel Data Datagram Example

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Example of sending a binary datagram to channel 1, flooding the network, with data type DATA_TYPE_DEV and payload A1 B2 C3.

```hex
3E 01 FF FF FF A1 B2 C3
```

--------------------------------

### Get Bridge Type

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Retrieves the current bridge type, which can be 'none', 'rs232', or 'espnow'.

```cli
get bridge.type
```

--------------------------------

### Implement Board-Specific Power Management Logic

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/nrf52_power_management.md

Implement the `initiateShutdown` function in your board's .cpp file to handle board-specific shutdown preparations and system-off entry. This includes configuring LPCOMP for low voltage or boot protection reasons.

```cpp
#ifdef NRF52_POWER_MANAGEMENT
const PowerMgtConfig power_config = {
  .lpcomp_ain_channel = PWRMGT_LPCOMP_AIN,
  .lpcomp_refsel = PWRMGT_LPCOMP_REFSEL,
  .voltage_bootlock = PWRMGT_VOLTAGE_BOOTLOCK
};

void MyBoard::initiateShutdown(uint8_t reason) {
  // Board-specific shutdown preparation (e.g., disable peripherals)
  bool enable_lpcomp = (reason == SHUTDOWN_REASON_LOW_VOLTAGE ||
                        reason == SHUTDOWN_REASON_BOOT_PROTECT);

  if (enable_lpcomp) {
    configureVoltageWake(power_config.lpcomp_ain_channel, power_config.lpcomp_refsel);
  }

  enterSystemOff(reason);
}
#endif

void MyBoard::begin() {
  NRF52Board::begin();  // or NRF52BoardDCDC::begin()
  // ... board setup ...

#ifdef NRF52_POWER_MANAGEMENT
  checkBootVoltage(&power_config);
#endif
}
```

--------------------------------

### Get Channel Info

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Retrieves information about a specific channel on the device. Requires the channel index as a parameter.

```APIDOC
## Get Channel Info

### Description
Retrieve information about a specific channel.

### Command Format
```
Byte 0: 0x1F
Byte 1: Channel Index (0-7)
```

### Example (get channel 1)
```
1F 01
```

### Response
`PACKET_CHANNEL_INFO` (0x12) with channel details
```

--------------------------------

### Configure LORA_FREQ and Build Firmware

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

After cloning the MeshCore repository, open the 'platformio.ini' file to edit the 'LORA_FREQ' setting within the '[arduino_base]' section. Then, run the PlatformIO build command for the RAK_4631_Repeater. The compiled firmware will be located in the '.pio/build/RAK_4631_Repeater' directory.

```bash
pio run -e RAK_4631_Repeater
```

--------------------------------

### PUSH_CODE_TRACE_DATA Frame Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Push code for trace data. Includes the code and indicates the start of trace data.

```protobuf
PUSH_CODE_TRACE_DATA {
  code: byte,    // constant 0x89

```

--------------------------------

### Set Advert Name Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Sets the advertised name for the device. `code` must be 8. The `name` field contains the remainder of the frame.

```protobuf
CMD_SET_ADVERT_NAME {
  code: byte,   // constant 8
  name: varchar   // remainder of frame
}
```

--------------------------------

### Set the home region

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Use 'region home' with a name prefix or '*' to set the 'home' region.

```bash
region home {* | name-prefix}
```

--------------------------------

### Get ACL Command

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Retrieves and displays the list of authorized nodes currently in the Access Control List (ACL).

```bash
get acl
```

--------------------------------

### Set Guest Password

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Sets or updates the guest password. For repeaters, guest logins can send the 'Get Stats' request.

```cli
set guest.password {guess-password}
```

--------------------------------

### Display Device Version

Source: https://github.com/meshcore-dev/meshcore/wiki/Terminal-Chat-Reference

Shows the current device version and the firmware build date. Useful for diagnostics and support.

```bash
ver
```

--------------------------------

### Get Battery and Storage Command

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Sends a command to query the device's battery voltage and storage usage. The response is PACKET_BATTERY.

```hex
14
```

--------------------------------

### Send Get Stats Commands

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/stats_binary_frames.md

Functions to send the CMD_GET_STATS command for core, radio, or packet statistics. Requires a SerialPort instance.

```typescript
// Send CMD_GET_STATS command
const CMD_GET_STATS = 56;
const STATS_TYPE_CORE = 0;
const STATS_TYPE_RADIO = 1;
const STATS_TYPE_PACKETS = 2;

function sendGetStatsCore(serialInterface: SerialPort): void {
    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_CORE]);
    serialInterface.write(cmd);
}

function sendGetStatsRadio(serialInterface: SerialPort): void {
    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_RADIO]);
    serialInterface.write(cmd);
}

function sendGetStatsPackets(serialInterface: SerialPort): void {
    const cmd = new Uint8Array([CMD_GET_STATS, STATS_TYPE_PACKETS]);
    serialInterface.write(cmd);
}
```

--------------------------------

### Download nRF Firmware using wget

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Use wget to download the ZIP firmware file for nRF devices. This file is used with the adafruit-nrfutil tool.

```bash
wget https://flasher.meshcore.io/releases/download/companion-v1.7.1/RAK_4631_companion_radio_ble-v1.7.1-165fb33.zip
```

--------------------------------

### Set Duty Cycle Limit

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/terminal_chat_cli.md

Sets the transmit duty cycle limit as a percentage (1-100%). Example: set dutycycle 10 for 10%.

```bash
set dutycycle {percent}
```

--------------------------------

### Import Contact Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Imports contact data from a 'business card' format. `code` must be 18. The `card_data` is the byte string received from `RESP_CODE_EXPORT_CONTACT`.

```protobuf
CMD_IMPORT_CONTACT {
  code: byte,   // constant 18
  card_data: bytes   // remainder of frame.
}
```

--------------------------------

### Get GPS location advert configuration

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

The 'gps advert' command displays the current location advert configuration: 'none', 'share', or 'prefs'.

```bash
gps advert
```

--------------------------------

### Define Power Management Configuration in variant.h

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/nrf52_power_management.md

Define essential power management parameters in your board's variant.h file. These include the bootlock voltage threshold and LPCOMP settings for voltage sensing.

```c
#define PWRMGT_VOLTAGE_BOOTLOCK    3300   // Won't boot below this voltage (mV)
#define PWRMGT_LPCOMP_AIN          7      // AIN channel for voltage sensing
#define PWRMGT_LPCOMP_REFSEL       2      // REFSEL (0-6=1/8..7/8, 7=ARef, 8-15=1/16..15/16)
```

--------------------------------

### Get GPS status

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

The 'gps' command provides the current status of the GPS. It replies with 'off' or 'on, {status}, {fix}, {sat count}'.

```bash
gps
```

--------------------------------

### Get Next Queued Message Command

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/companion_protocol.md

Sends a command to request the next available message from the device. Poll periodically to retrieve queued messages.

```hex
0A
```

--------------------------------

### Set Device Time Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Sets the device's current time. `code` must be 6. `epoch_secs` is the current Unix epoch time.

```protobuf
CMD_SET_DEVICE_TIME {
  code: byte,   // constant 6
  epoch_secs: uint32
}
```

--------------------------------

### Get current home region

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

The 'region home' command without arguments replies with the current 'home' region. This functionality is reserved for future use.

```bash
region home
```

--------------------------------

### Current Time Response Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Provides the current device time. `code` must be 9. `epoch_secs` is the current Unix epoch time.

```protobuf
RESP_CODE_CURR_TIME {
  code: byte,   // constant 9
  epoch_secs: uint32
}
```

--------------------------------

### Query Power Management Status via CLI

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/nrf52_power_management.md

Use these CLI commands to check the power management capabilities and status of the device. These commands are useful for verifying if power management is enabled and understanding the current power state.

```bash
get pwrmgt.support
```

```bash
get pwrmgt.source
```

```bash
get pwrmgt.bootreason
```

```bash
get pwrmgt.bootmv
```

--------------------------------

### Get current power saving mode

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

The 'powersaving' command without arguments returns the current power saving mode ('on' or 'off'). Available from v1.12.0.

```bash
powersaving
```

--------------------------------

### CMD_REBOOT

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Initiates a reboot of the companion device. The command is sent with the text 'reboot'. This command does not expect a response.

```APIDOC
## CMD_REBOOT

### Description
This command instructs the companion device to reboot itself. The command payload should be the string 'reboot'.

### Command Code
19

### Parameters
#### Request Body
- **command** (string) - Required - Must be the string 'reboot'.

### Expected Response
None
```

--------------------------------

### Declare initiateShutdown Override in board .h file

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/nrf52_power_management.md

Declare the `initiateShutdown` function as an override in your board's .h file if NRF52_POWER_MANAGEMENT is defined. This is necessary for the compiler to recognize the overridden method.

```cpp
#ifdef NRF52_POWER_MANAGEMENT
  void initiateShutdown(uint8_t reason) override;
#endif
```

--------------------------------

### CMD_SEND_LOGIN Frame Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Command to send login credentials. Includes the public key of the target repeater or room server and the password.

```protobuf
CMD_SEND_LOGIN {
  code: byte,    // constant 26
  pub_key: bytes(32),     // id of repeater or room server
  password: varchar     // remainder of frame (max 15 bytes)
}
```

--------------------------------

### CMD_DEVICE_QEURY

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Initiates a device query after establishing a connection. The radio responds with RESP_CODE_DEVICE_INFO(13).

```APIDOC
## CMD_DEVICE_QEURY

### Description
This command should be the first one sent by the app after establishing a connection. It is used to query device information.

### Command Code
22

### Expected Response
RESP_CODE_DEVICE_INFO (13)
```

--------------------------------

### Send Get Stats Commands (Python)

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/stats_binary_frames.md

Python functions to send commands for retrieving core, radio, and packet statistics. These functions expect a serial interface object with a `write` method.

```python
# Send CMD_GET_STATS command
def send_get_stats_core(serial_interface):
    """Send command to get core stats"""
    cmd = bytes([56, 0])  # CMD_GET_STATS (56) + STATS_TYPE_CORE (0)
    serial_interface.write(cmd)

def send_get_stats_radio(serial_interface):
    """Send command to get radio stats"""
    cmd = bytes([56, 1])  # CMD_GET_STATS (56) + STATS_TYPE_RADIO (1)
    serial_interface.write(cmd)

def send_get_stats_packets(serial_interface):
    """Send command to get packet stats"""
    cmd = bytes([56, 2])  # CMD_GET_STATS (56) + STATS_TYPE_PACKETS (2)
    serial_interface.write(cmd)
```

--------------------------------

### Flash ESP-based MeshCore Radio (Non-Merged Bin)

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Flash a non-merged firmware binary onto an ESP32-S3 device. Ensure the correct firmware file and device path are used.

```bash
esptool.py -p /dev/ttyUSB0 --chip esp32-s3 write_flash 0x10000 <non-merged_firmware>.bin
```

--------------------------------

### Configuration Settings

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Commands to configure various parameters of the device, including network, RF, and operational settings.

```APIDOC
## set af {air-time-factor}

### Description
Sets the air-time-factor for the device.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **air-time-factor** (number) - Required - The value for the air-time-factor.

### Request Example
```
set af 5
```

### Response
(Indicates setting success)
```

```APIDOC
## set tx {tx-power-dbm}

### Description
Sets the LoRa transmit power in dBm. A reboot is required to apply this setting.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **tx-power-dbm** (number) - Required - The transmit power in dBm.

### Request Example
```
set tx 14
```

### Response
(Indicates setting success, note about reboot required)
```

```APIDOC
## set repeat {on|off}

### Description
Enables or disables the repeater role for this node.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **state** (string) - Required - 'on' to enable, 'off' to disable.

### Request Example
```
set repeat on
```

### Response
(Indicates setting success)
```

```APIDOC
## set allow.read.only {on|off}

### Description
(Room server only) If set to 'on', allows login with a blank password but restricts posting to the room (read-only access).

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **state** (string) - Required - 'on' to enable read-only mode, 'off' to disable.

### Request Example
```
set allow.read.only on
```

### Response
(Indicates setting success)
```

```APIDOC
## set flood.max {max-hops}

### Description
Sets the maximum number of hops for inbound flood packets. Packets exceeding this limit will not be forwarded.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **max-hops** (integer) - Required - The maximum number of hops allowed.

### Request Example
```
set flood.max 5
```

### Response
(Indicates setting success)
```

```APIDOC
## set int.thresh {db}

### Description
Sets the Interference Threshold in dB. Default is 14. Setting to 0 disables channel interference detection.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **db** (integer) - Required - The interference threshold in dB.

### Request Example
```
set int.thresh 10
```

### Response
(Indicates setting success)
```

```APIDOC
## set agc.reset.interval {seconds}

### Description
Sets the interval in seconds for resetting the Auto Gain Controller (AGC). Setting to 0 disables the AGC reset.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **seconds** (integer) - Required - The interval in seconds.

### Request Example
```
set agc.reset.interval 300
```

### Response
(Indicates setting success)
```

```APIDOC
## set multi.acks {0|1}

### Description
Enables or disables the 'double ACKs' feature.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **state** (integer) - Required - 0 to disable, 1 to enable.

### Request Example
```
set multi.acks 1
```

### Response
(Indicates setting success)
```

```APIDOC
## set advert.interval {minutes}

### Description
Sets the timer interval in minutes for sending a local (zero-hop) advertisement packet. Setting to 0 disables local advertisements.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **minutes** (integer) - Required - The interval in minutes.

### Request Example
```
set advert.interval 5
```

### Response
(Indicates setting success)
```

```APIDOC
## set flood.advert.interval {hours}

### Description
Sets the timer interval in hours for sending a flood advertisement packet. Setting to 0 disables flood advertisements.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **hours** (integer) - Required - The interval in hours.

### Request Example
```
set flood.advert.interval 24
```

### Response
(Indicates setting success)
```

```APIDOC
## set guest.password {guest-password}

### Description
Sets or updates the guest password. For repeaters, guest logins can send the 'Get Stats' request.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **guest-password** (string) - Required - The new guest password.

### Request Example
```
set guest.password guest123
```

### Response
(Indicates setting success)
```

```APIDOC
## set name {name}

### Description
Sets the advertisement name for the device.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The desired advertisement name.

### Request Example
```
set name MyRepeater
```

### Response
(Indicates setting success)
```

```APIDOC
## set owner.info {info}

### Description
(Since ver 1.12.+) Sets owner information. Pipe characters ('|') are translated to newline characters when displayed.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **info** (string) - Required - The owner information string.

### Request Example
```
set owner.info John Doe|123 Main St
```

### Response
(Indicates setting success)
```

```APIDOC
## set lat {latitude}

### Description
Sets the advertisement map latitude in decimal degrees.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **latitude** (number) - Required - The latitude value.

### Request Example
```
set lat 34.0522
```

### Response
(Indicates setting success)
```

```APIDOC
## set lon {longitude}

### Description
Sets the advertisement map longitude in decimal degrees.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **longitude** (number) - Required - The longitude value.

### Request Example
```
set lon -118.2437
```

### Response
(Indicates setting success)
```

```APIDOC
## set radio {freq},{bw},{sf},{cr}

### Description
Sets completely new radio parameters and saves them to preferences. Requires a 'reboot' command to apply.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **freq** (number) - Required - The radio frequency.
- **bw** (number) - Required - The bandwidth.
- **sf** (integer) - Required - The spreading factor.
- **cr** (string) - Required - The coding rate (e.g., '4/5').

### Request Example
```
set radio 915000000,125000,7,4/5
```

### Response
(Indicates setting success, note about reboot required)
```

```APIDOC
## set rxdelay {base}

### Description
(Experimental) Sets a base value for applying a slight delay to received packets, based on signal strength/score. Setting to 0 disables this feature. Must be greater than 1 for effect.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **base** (number) - Required - The base delay value.

### Request Example
```
set rxdelay 2
```

### Response
(Indicates setting success)
```

```APIDOC
## set txdelay {factor}

### Description
Sets a factor multiplied with time-on-air for a flood-mode packet and with a randomized slot system, to delay its forwarding and decrease the likelihood of collisions.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **factor** (number) - Required - The delay factor.

### Request Example
```
set txdelay 1.5
```

### Response
(Indicates setting success)
```

```APIDOC
## set direct.txdelay {factor}

### Description
Similar to `txdelay`, but applies a random delay to the forwarding of direct-mode packets.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **factor** (number) - Required - The delay factor.

### Request Example
```
set direct.txdelay 0.8
```

### Response
(Indicates setting success)
```

```APIDOC
## set bridge.enabled {on|off}

### Description
Enables or disables the bridge functionality.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **state** (string) - Required - 'on' to enable, 'off' to disable.

### Request Example
```
set bridge.enabled on
```

### Response
(Indicates setting success)
```

```APIDOC
## set bridge.delay {0-10000}

### Description
Sets the delay in milliseconds before retransmitting packets via the bridge.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **delay** (integer) - Required - The delay value (0-10000).

### Request Example
```
set bridge.delay 500
```

### Response
(Indicates setting success)
```

```APIDOC
## set bridge.source {rx|tx}

### Description
Chooses whether the bridge will retransmit received ('rx') or transmitted ('tx') packets.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **source** (string) - Required - 'rx' or 'tx'.

### Request Example
```
set bridge.source rx
```

### Response
(Indicates setting success)
```

```APIDOC
## set bridge.baud {speed}

### Description
Sets the serial link baud rate for RS232 bridges.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **speed** (integer) - Required - The baud rate (e.g., 9600, 115200).

### Request Example
```
set bridge.baud 115200
```

### Response
(Indicates setting success)
```

```APIDOC
## set bridge.secret {shared-secret}

### Description
Sets the bridge secret for ESPNOW bridges.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **shared-secret** (string) - Required - The shared secret key.

### Request Example
```
set bridge.secret myespnowsecret
```

### Response
(Indicates setting success)
```

```APIDOC
## set adc.multiplier {factor}

### Description
Sets a custom factor to adjust the reported battery voltage. Only supported on select boards.

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **factor** (number) - Required - The multiplier factor.

### Request Example
```
set adc.multiplier 1.1
```

### Response
(Indicates setting success)
```

```APIDOC
## setperm {pubkey-hex} {permissions}

### Description
Modifies the Access Control List (ACL). Removes an entry if 'permissions' is zero. Adds a new entry if 'pubkey-hex' is full length and not in ACL. Updates an entry by matching 'pubkey-hex' prefix. Permission bits vary by firmware role; the low 2 bits are: 0 (Guest), 1 (Read only), 2 (Read write), 3 (Admin).

### Method
CLI Command

### Endpoint
N/A

### Parameters
- **pubkey-hex** (string) - Required - The public key in hexadecimal format (or prefix).
- **permissions** (integer) - Required - The permission bits to set (0 to remove).

### Request Example
```
setperm abcdef123456 2
```

### Response
(Indicates ACL modification success)
```

--------------------------------

### C/C++ Structure for Radio Stats Response

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/stats_binary_frames.md

Defines the packed binary structure for receiving radio statistics. Use this when the stats_type is STATS_TYPE_RADIO (1). Note that last_snr requires division by 4.0 to get the value in dB.

```c
struct StatsRadio {
    uint8_t  response_code;
    uint8_t  stats_type;
    int16_t  noise_floor;
    int8_t   last_rssi;
    int8_t   last_snr;
    uint32_t tx_air_secs;
    uint32_t rx_air_secs;
} __attribute__((packed));
```

--------------------------------

### Share Contact Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Initiates sharing a contact. `code` must be 16. Requires the `public_key` of the contact to be shared.

```protobuf
CMD_SHARE_CONTACT {
  code: byte,   // constant 16
  public_key: bytes(32)
}
```

--------------------------------

### Enable Power Management in platformio.ini

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/nrf52_power_management.md

Add this preprocessor definition to your platformio.ini file to enable the power management features for your nRF52 board.

```ini
-D NRF52_POWER_MANAGEMENT
```

--------------------------------

### CMD_SET_TUNING_PARAMS

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Sets various 'tuning' parameters on the device. Responds with RESP_CODE_OK(0).

```APIDOC
## CMD_SET_TUNING_PARAMS

### Description
This command allows the app to configure various 'tuning' parameters on the radio device.

### Command Code
21

### Parameters
#### Request Body
- **parameters** (object) - Required - An object containing the tuning parameters to set.

### Expected Response
RESP_CODE_OK (0)
```

--------------------------------

### Run Unit Tests

Source: https://github.com/meshcore-dev/meshcore/blob/main/README.md

Execute unit tests for the MeshCore project using the PlatformIO test runner. This command runs tests on the native environment and provides verbose output.

```bash
pio test --environment native --verbose
```

--------------------------------

### Set GPS location advert configuration

Source: https://github.com/meshcore-dev/meshcore/wiki/Repeater-&-Room-Server-CLI-Reference

Use 'gps advert {none|share|prefs}' to configure how the node's location is included in adverts.

```bash
gps advert {none|share|prefs}
```

--------------------------------

### Device Query Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Used to query device information. The `code` must be 22 and `app_target_ver` specifies the understood serial protocol version.

```protobuf
CMD_DEVICE_QEURY {
  code: byte,     // constant: 22
  app_target_ver: byte   // version of serial protocol the app understands
}
```

--------------------------------

### Set Advert LatLon Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Sets the advertised latitude and longitude. `code` must be 14. Values are multiplied by 1E6. `adv_alt` is reserved for future use.

```protobuf
CMD_SET_ADVERT_LATLON {
  code: byte,    // constant 14
  adv_lat: int32,    // latitude * 1E6
  adv_lon: int32,    // longitude * 1E6
  adv_alt: int32   // OPTIONAL (for future support)
}
```

--------------------------------

### Device Info Response Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Response containing device information. Includes firmware version, radio capabilities, BLE PIN, and identification strings. `code` must be 13.

```protobuf
RESP_CODE_DEVICE_INFO {
  code: byte,     // constant: 13
  firmware_ver: byte,
  max_contacts_div_2: byte,     // ver 3+
  max_channels: byte,           // ver 3+
  ble_pin: uint32,              // ver 3+. (BLE pin code)
  firmware_build_date: chars(12),    // ASCII-null terminated, eg. "19 Feb 2025"
  manufacturer_model: chars(40),     // ASCII-null terminated
  semantic_version: chars(20)        // ASCII-null terminated
}
```

--------------------------------

### Send Self Advert Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Initiates sending a self-advertisement. `code` must be 7. An optional `type` parameter can specify 'flood' (1) or 'zero-hop' (0, default).

```protobuf
CMD_SEND_SELF_ADVERT {
  code: byte,   // constant 7
  (optional) type: byte,   // 1 = flood, 0 = zero-hop (default)
}
```

--------------------------------

### Add/Update Contact Command Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Adds or updates a contact. `code` must be 9. Includes public key, type, flags, path, name, and last advertisement time. Optional latitude and longitude can be provided.

```protobuf
CMD_ADD_UPDATE_CONTACT {
  code: byte,   // constant 9
  public_key: bytes(32),
  type: byte,   // one of ADV_TYPE_*
  flags: byte,
  out_path_len: signed-byte,
  out_path: bytes(64),
  adv_name: chars(32),    // null terminated
  last_advert: uint32
  (optional) adv_lat: int32,    // advertised latitude * 1E6
  (optional) adv_lon: int32,    // advertised longitude * 1E6
}
```

--------------------------------

### Flash ESP-based MeshCore Radio (Merged Bin)

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Flash a merged firmware binary onto an ESP32-S3 device. This overwrites the bootloader and Bluetooth database but retains configurations.

```bash
esptool.py -p /dev/ttyUSB0 --chip esp32-s3 write_flash 0x00000 <merged_firmware>.bin
```

--------------------------------

### CMD_SET_DEVICE_PIN Structure

Source: https://github.com/meshcore-dev/meshcore/wiki/Companion-Radio-Protocol

Used to set a device's PIN. Requires a constant code and a 32-bit PIN.

```protobuf
CMD_SET_DEVICE_PIN {
  code: byte,    // constant 37
  ble_pin: uint32
}
```

--------------------------------

### Configure Zero-Hop Advert Interval

Source: https://github.com/meshcore-dev/meshcore/blob/main/docs/faq.md

Sets the interval in minutes for how often a MeshCore client advertises itself locally.

```bash
set advert.interval {minutes}
```