web/packages/protobufs/meshtastic/admin.proto

syntax = "proto3";

package meshtastic;

/* trunk-ignore(buf-lint/COMPILE) */
import "meshtastic/channel.proto";
import "meshtastic/config.proto";
import "meshtastic/connection_status.proto";
import "meshtastic/device_ui.proto";
import "meshtastic/mesh.proto";
import "meshtastic/module_config.proto";

option csharp_namespace = "Meshtastic.Protobufs";
option go_package = "github.com/meshtastic/go/generated";
option java_outer_classname = "AdminProtos";
option java_package = "org.meshtastic.proto";
option swift_prefix = "";

/*
 * This message is handled by the Admin module and is responsible for all settings/channel read/write operations.
 * This message is used to do settings operations to both remote AND local nodes.
 * (Prior to 1.2 these operations were done via special ToRadio operations)
 */
message AdminMessage {
  /*
   * The node generates this key and sends it with any get_x_response packets.
   * The client MUST include the same key with any set_x commands. Key expires after 300 seconds.
   * Prevents replay attacks for admin messages.
   */
  bytes session_passkey = 101;

  /*
   * TODO: REPLACE
   */
  enum ConfigType {
    /*
     * TODO: REPLACE
     */
    DEVICE_CONFIG = 0;

    /*
     * TODO: REPLACE
     */
    POSITION_CONFIG = 1;

    /*
     * TODO: REPLACE
     */
    POWER_CONFIG = 2;

    /*
     * TODO: REPLACE
     */
    NETWORK_CONFIG = 3;

    /*
     * TODO: REPLACE
     */
    DISPLAY_CONFIG = 4;

    /*
     * TODO: REPLACE
     */
    LORA_CONFIG = 5;

    /*
     * TODO: REPLACE
     */
    BLUETOOTH_CONFIG = 6;

    /*
     * TODO: REPLACE
     */
    SECURITY_CONFIG = 7;

    /*
     * Session key config
     */
    SESSIONKEY_CONFIG = 8;

    /*
     * device-ui config
     */
    DEVICEUI_CONFIG = 9;
  }

  /*
   * TODO: REPLACE
   */
  enum ModuleConfigType {
    /*
     * TODO: REPLACE
     */
    MQTT_CONFIG = 0;

    /*
     * TODO: REPLACE
     */
    SERIAL_CONFIG = 1;

    /*
     * TODO: REPLACE
     */
    EXTNOTIF_CONFIG = 2;

    /*
     * TODO: REPLACE
     */
    STOREFORWARD_CONFIG = 3;

    /*
     * TODO: REPLACE
     */
    RANGETEST_CONFIG = 4;

    /*
     * TODO: REPLACE
     */
    TELEMETRY_CONFIG = 5;

    /*
     * TODO: REPLACE
     */
    CANNEDMSG_CONFIG = 6;

    /*
     * TODO: REPLACE
     */
    AUDIO_CONFIG = 7;

    /*
     * TODO: REPLACE
     */
    REMOTEHARDWARE_CONFIG = 8;

    /*
     * TODO: REPLACE
     */
    NEIGHBORINFO_CONFIG = 9;

    /*
     * TODO: REPLACE
     */
    AMBIENTLIGHTING_CONFIG = 10;

    /*
     * TODO: REPLACE
     */
    DETECTIONSENSOR_CONFIG = 11;

    /*
     * TODO: REPLACE
     */
    PAXCOUNTER_CONFIG = 12;

    /*
     * TODO: REPLACE
     */
    STATUSMESSAGE_CONFIG = 13;

    /*
     * Traffic management module config
     */
    TRAFFICMANAGEMENT_CONFIG = 14;

    /*
     * TAK module config
     */
    TAK_CONFIG = 15;
  }

  enum BackupLocation {
    /*
     * Backup to the internal flash
     */
    FLASH = 0;

    /*
     * Backup to the SD card
     */
    SD = 1;
  }

  /*
   * Input event message to be sent to the node.
   */
  message InputEvent {
    /*
     * The input event code
     */
    uint32 event_code = 1;
    /*
     * Keyboard character code
     */
    uint32 kb_char = 2;
    /*
     * The touch X coordinate
     */
    uint32 touch_x = 3;
    /*
     * The touch Y coordinate
     */
    uint32 touch_y = 4;
  }

  /*
   * User is requesting an over the air update.
   * Node will reboot into the OTA loader
   */
  message OTAEvent {
    /*
     * Tell the node to reboot into OTA mode for firmware update via BLE or WiFi (ESP32 only for now)
     */
    OTAMode reboot_ota_mode = 1;

    /*
     * A 32 byte hash of the OTA firmware.
     * Used to verify the integrity of the firmware before applying an update.
     */
    bytes ota_hash = 2;
  }

  /*
   * TODO: REPLACE
   */
  oneof payload_variant {
    /*
     * Send the specified channel in the response to this message
     * NOTE: This field is sent with the channel index + 1 (to ensure we never try to send 'zero' - which protobufs treats as not present)
     */
    uint32 get_channel_request = 1;

    /*
     * TODO: REPLACE
     */
    Channel get_channel_response = 2;

    /*
     * Send the current owner data in the response to this message.
     */
    bool get_owner_request = 3;

    /*
     * TODO: REPLACE
     */
    User get_owner_response = 4;

    /*
     * Ask for the following config data to be sent
     */
    ConfigType get_config_request = 5;

    /*
     * Send the current Config in the response to this message.
     */
    Config get_config_response = 6;

    /*
     * Ask for the following config data to be sent
     */
    ModuleConfigType get_module_config_request = 7;

    /*
     * Send the current Config in the response to this message.
     */
    ModuleConfig get_module_config_response = 8;

    /*
     * Get the Canned Message Module messages in the response to this message.
     */
    bool get_canned_message_module_messages_request = 10;

    /*
     * Get the Canned Message Module messages in the response to this message.
     */
    string get_canned_message_module_messages_response = 11;

    /*
     * Request the node to send device metadata (firmware, protobuf version, etc)
     */
    bool get_device_metadata_request = 12;

    /*
     * Device metadata response
     */
    DeviceMetadata get_device_metadata_response = 13;

    /*
     * Get the Ringtone in the response to this message.
     */
    bool get_ringtone_request = 14;

    /*
     * Get the Ringtone in the response to this message.
     */
    string get_ringtone_response = 15;

    /*
     * Request the node to send it's connection status
     */
    bool get_device_connection_status_request = 16;

    /*
     * Device connection status response
     */
    DeviceConnectionStatus get_device_connection_status_response = 17;

    /*
     * Setup a node for licensed amateur (ham) radio operation
     */
    HamParameters set_ham_mode = 18;

    /*
     * Get the mesh's nodes with their available gpio pins for RemoteHardware module use
     */
    bool get_node_remote_hardware_pins_request = 19;

    /*
     * Respond with the mesh's nodes with their available gpio pins for RemoteHardware module use
     */
    NodeRemoteHardwarePinsResponse get_node_remote_hardware_pins_response = 20;

    /*
     * Enter (UF2) DFU mode
     * Only implemented on NRF52 currently
     */
    bool enter_dfu_mode_request = 21;

    /*
     * Delete the file by the specified path from the device
     */
    string delete_file_request = 22;

    /*
     * Set zero and offset for scale chips
     */
    uint32 set_scale = 23;

    /*
     * Backup the node's preferences
     */
    BackupLocation backup_preferences = 24;

    /*
     * Restore the node's preferences
     */
    BackupLocation restore_preferences = 25;

    /*
     * Remove backups of the node's preferences
     */
    BackupLocation remove_backup_preferences = 26;

    /*
     * Send an input event to the node.
     * This is used to trigger physical input events like button presses, touch events, etc.
     */
    InputEvent send_input_event = 27;

    /*
     * Set the owner for this node
     */
    User set_owner = 32;

    /*
     * Set channels (using the new API).
     * A special channel is the "primary channel".
     * The other records are secondary channels.
     * Note: only one channel can be marked as primary.
     * If the client sets a particular channel to be primary, the previous channel will be set to SECONDARY automatically.
     */
    Channel set_channel = 33;

    /*
     * Set the current Config
     */
    Config set_config = 34;

    /*
     * Set the current Config
     */
    ModuleConfig set_module_config = 35;

    /*
     * Set the Canned Message Module messages text.
     */
    string set_canned_message_module_messages = 36;

    /*
     * Set the ringtone for ExternalNotification.
     */
    string set_ringtone_message = 37;

    /*
     * Remove the node by the specified node-num from the NodeDB on the device
     */
    uint32 remove_by_nodenum = 38;

    /*
     * Set specified node-num to be favorited on the NodeDB on the device
     */
    uint32 set_favorite_node = 39;

    /*
     * Set specified node-num to be un-favorited on the NodeDB on the device
     */
    uint32 remove_favorite_node = 40;

    /*
     * Set fixed position data on the node and then set the position.fixed_position = true
     */
    Position set_fixed_position = 41;

    /*
     * Clear fixed position coordinates and then set position.fixed_position = false
     */
    bool remove_fixed_position = 42;

    /*
     * Set time only on the node
     * Convenience method to set the time on the node (as Net quality) without any other position data
     */
    fixed32 set_time_only = 43;

    /*
     * Tell the node to send the stored ui data.
     */
    bool get_ui_config_request = 44;

    /*
     * Reply stored device ui data.
     */
    DeviceUIConfig get_ui_config_response = 45;

    /*
     * Tell the node to store UI data persistently.
     */
    DeviceUIConfig store_ui_config = 46;

    /*
     * Set specified node-num to be ignored on the NodeDB on the device
     */
    uint32 set_ignored_node = 47;

    /*
     * Set specified node-num to be un-ignored on the NodeDB on the device
     */
    uint32 remove_ignored_node = 48;

    /*
     * Set specified node-num to be muted
     */
    uint32 toggle_muted_node = 49;

    /*
     * Begins an edit transaction for config, module config, owner, and channel settings changes
     * This will delay the standard *implicit* save to the file system and subsequent reboot behavior until committed (commit_edit_settings)
     */
    bool begin_edit_settings = 64;

    /*
     * Commits an open transaction for any edits made to config, module config, owner, and channel settings
     */
    bool commit_edit_settings = 65;

    /*
     * Add a contact (User) to the nodedb
     */
    SharedContact add_contact = 66;

    /*
     * Initiate or respond to a key verification request
     */
    KeyVerificationAdmin key_verification = 67;

    /*
     * Tell the node to factory reset config everything; all device state and configuration will be returned to factory defaults and BLE bonds will be cleared.
     */
    int32 factory_reset_device = 94;

    /*
     * Tell the node to reboot into the OTA Firmware in this many seconds (or <0 to cancel reboot)
     * Only Implemented for ESP32 Devices. This needs to be issued to send a new main firmware via bluetooth.
     * Deprecated in favor of reboot_ota_mode in 2.7.17
     */
    int32 reboot_ota_seconds = 95 [deprecated = true];

    /*
     * This message is only supported for the simulator Portduino build.
     * If received the simulator will exit successfully.
     */
    bool exit_simulator = 96;

    /*
     * Tell the node to reboot in this many seconds (or <0 to cancel reboot)
     */
    int32 reboot_seconds = 97;

    /*
     * Tell the node to shutdown in this many seconds (or <0 to cancel shutdown)
     */
    int32 shutdown_seconds = 98;

    /*
     * Tell the node to factory reset config; all device state and configuration will be returned to factory defaults; BLE bonds will be preserved.
     */
    int32 factory_reset_config = 99;

    /*
     * Tell the node to reset the nodedb.
     * When true, favorites are preserved through reset.
     */
    bool nodedb_reset = 100;

    /*
     * Tell the node to reset into the OTA Loader
     */
    OTAEvent ota_request = 102;

    /*
     * Parameters and sensor configuration
     */
    SensorConfig sensor_config = 103;

    /*
     * Lockdown passphrase delivery / unlock / lock-now command for hardened
     * firmware builds (see MESHTASTIC_LOCKDOWN). Used to provision the
     * passphrase on first boot, unlock encrypted storage on subsequent
     * reboots, re-verify on already-unlocked devices to authorize a new
     * client connection, or immediately re-lock the device.
     *
     * Replaces the earlier scheme that repurposed SecurityConfig.private_key
     * to carry passphrase bytes; that hack is retired.
     */
    LockdownAuth lockdown_auth = 104;
  }
}

/*
 * Lockdown passphrase delivery payload.
 *
 * One message handles three operations distinguished by content:
 *   - Provision (first-time): passphrase set, lock_now=false. Firmware
 *     generates DEK, wraps with passphrase-derived KEK, persists.
 *   - Unlock: passphrase set, lock_now=false. Firmware verifies
 *     passphrase against stored DEK, unlocks storage, authorizes the
 *     connection that delivered this packet.
 *   - Lock now: lock_now=true, passphrase ignored. Firmware revokes
 *     all client auth and reboots into the locked state.
 *
 * Firmware decides between provision and unlock based on its own state
 * (whether a DEK file already exists). Clients do not need to track
 * which case applies.
 */
message LockdownAuth {
  /*
   * Passphrase bytes (1-32). Empty when lock_now is true.
   * Capped to 32 to match the proto cap on related security fields.
   */
  bytes passphrase = 1;

  /*
   * Optional override of the boot-count token TTL granted on success.
   * 0 = use firmware default (TOKEN_DEFAULT_BOOTS).
   * On reboot the firmware decrements this; when it reaches 0 the
   * device boots fully locked and requires a fresh passphrase.
   */
  uint32 boots_remaining = 2;

  /*
   * Optional wall-clock expiry for the unlock token, as absolute
   * Unix-epoch seconds. 0 = no time limit (only the boot-count TTL
   * applies). On boot, if the device RTC is set and now > this value,
   * the token is treated as expired.
   */
  uint32 valid_until_epoch = 3;

  /*
   * If true, ignore passphrase fields, immediately revoke all
   * connection-level admin authorization, and reboot the device into
   * the locked state. Always honoured regardless of current lock state.
   */
  bool lock_now = 4;

  /*
   * Optional per-boot uptime cap on the unlocked session, in seconds.
   * 0 = unlimited (token-only enforcement, suitable for unattended
   * tower / infrastructure nodes).
   *
   * When non-zero, the firmware arms an uptime timer at unlock. On
   * each expiry, while there is still boot-count budget, the firmware
   * decrements the on-flash boot count in place, revokes per-
   * connection admin auth (clients must re-authenticate to see
   * content), re-engages the screen lock, and re-arms the timer
   * without rebooting. Mesh routing keeps running across session
   * boundaries; only when the boot-count budget reaches zero does
   * the device hard-lock and reboot.
   *
   * Total exposure ceiling = ((resolved boot count) + 1) * max_session_seconds.
   * The +1 accounts for the initial passphrase-unlocked session
   * itself, since boots_remaining is the number of subsequent
   * session rolls (each consuming one boot from the rollback ledger).
   * The resolved boot count is the value the firmware writes into the
   * token at unlock time: the client-supplied boots_remaining when
   * non-zero, otherwise the firmware default (TOKEN_DEFAULT_BOOTS).
   * Note that boots_remaining == 0 in this message means "use firmware
   * default", NOT "zero boots" — a client computing the ceiling for
   * display should mirror that resolution rather than multiplying the
   * raw request value.
   *
   * The cap is persisted in the token, so it survives token-based
   * auto-unlock across reboots. Explicit operator Lock Now still
   * deletes the token and forces passphrase re-entry.
   *
   * Uses millis() (CPU uptime), not wall-clock time, so the cap is
   * immune to GPS spoofing, RTC backup-battery removal, and Faraday
   * cage isolation — none of those move the uptime counter. The only
   * way to reset the session clock is a reboot, which costs a boot
   * from the on-flash, HMAC-bound counter.
   */
  uint32 max_session_seconds = 5;

  /*
   * Disable lockdown mode. Requires a valid passphrase in the same
   * message (the device must prove the operator owns it before
   * reverting at-rest encryption). On success the firmware decrypts
   * every stored config / channel / nodedb file back to plaintext,
   * removes the wrapped DEK, unlock token, monotonic-counter, and
   * backoff files, and reboots out of lockdown.
   *
   * This is the inverse of the provision/unlock path: it is how the
   * client app's "lockdown mode" toggle returns a device to normal
   * operation.
   *
   * NOT reversed by this operation: APPROTECT. Once the debug port
   * lockout has been burned (on silicon where it is effective) it is
   * permanent — disabling lockdown decrypts your data and removes the
   * access gates, but the SWD/JTAG port stays locked for the life of
   * the device (recoverable only via a full chip erase over a debug
   * probe, which destroys all data). Clients should make this
   * irreversibility clear at the moment lockdown is first enabled.
   *
   * When true the passphrase field is still required; boots_remaining,
   * valid_until_epoch, max_session_seconds, and lock_now are ignored.
   */
  bool disable = 6;
}

/*
 * Firmware update mode for OTA updates
 */
enum OTAMode {
  /*
   * Do not reboot into OTA mode
   */
  NO_REBOOT_OTA = 0;

  /*
   * Reboot into OTA mode for BLE firmware update
   */
  OTA_BLE = 1;

  /*
   * Reboot into OTA mode for WiFi firmware update
   */
  OTA_WIFI = 2;
}

/*
 * Parameters for setting up Meshtastic for ameteur radio usage
 */
message HamParameters {
  /*
   * Amateur radio call sign, eg. KD2ABC
   */
  string call_sign = 1;

  /*
   * Transmit power in dBm at the LoRA transceiver, not including any amplification
   */
  int32 tx_power = 2;

  /*
   * The selected frequency of LoRA operation
   * Please respect your local laws, regulations, and band plans.
   * Ensure your radio is capable of operating of the selected frequency before setting this.
   */
  float frequency = 3;

  /*
   * Optional short name of user
   */
  string short_name = 4;

  /*
   * Optional long name of user
   * Appended to callsign
   */
  string long_name = 5;
}

/*
 * Response envelope for node_remote_hardware_pins
 */
message NodeRemoteHardwarePinsResponse {
  /*
   * Nodes and their respective remote hardware GPIO pins
   */
  repeated NodeRemoteHardwarePin node_remote_hardware_pins = 1;
}

message SharedContact {
  /*
   * The node number of the contact
   */
  uint32 node_num = 1;

  /*
   * The User of the contact
   */
  User user = 2;

  /*
   * Add this contact to the blocked / ignored list
   */
  bool should_ignore = 3;

  /*
   * Set the IS_KEY_MANUALLY_VERIFIED bit
   */
  bool manually_verified = 4;
}

/*
 * This message is used by a client to initiate or complete a key verification
 */
message KeyVerificationAdmin {
  /*
   * Three stages of this request.
   */
  enum MessageType {
    /*
     * This is the first stage, where a client initiates
     */
    INITIATE_VERIFICATION = 0;

    /*
     * After the nonce has been returned over the mesh, the client prompts for the security number
     * And uses this message to provide it to the node.
     */
    PROVIDE_SECURITY_NUMBER = 1;

    /*
     * Once the user has compared the verification message, this message notifies the node.
     */
    DO_VERIFY = 2;

    /*
     * This is the cancel path, can be taken at any point
     */
    DO_NOT_VERIFY = 3;
  }

  MessageType message_type = 1;

  /*
   * The nodenum we're requesting
   */
  uint32 remote_nodenum = 2;

  /*
   * The nonce is used to track the connection
   */
  uint64 nonce = 3;

  /*
   * The 4 digit code generated by the remote node, and communicated outside the mesh
   */
  optional uint32 security_number = 4;
}

message SensorConfig {
  /*
   * SCD4X CO2 Sensor configuration
   */
  SCD4X_config scd4x_config = 1;

  /*
   * SEN5X PM Sensor configuration
   */
  SEN5X_config sen5x_config = 2;

  /*
   * SCD30 CO2 Sensor configuration
   */
  SCD30_config scd30_config = 3;

  /*
   * SHTXX temperature and relative humidity sensor configuration
   */
  SHTXX_config shtxx_config = 4;
}

message SCD4X_config {
  /*
   * Set Automatic self-calibration enabled
   */
  optional bool set_asc = 1;

  /*
   * Recalibration target CO2 concentration in ppm (FRC or ASC)
   */
  optional uint32 set_target_co2_conc = 2;

  /*
   * Reference temperature in degC
   */
  optional float set_temperature = 3;

  /*
   * Altitude of sensor in meters above sea level. 0 - 3000m (overrides ambient pressure)
   */
  optional uint32 set_altitude = 4;

  /*
   * Sensor ambient pressure in Pa. 70000 - 120000 Pa (overrides altitude)
   */
  optional uint32 set_ambient_pressure = 5;

  /*
   * Perform a factory reset of the sensor
   */
  optional bool factory_reset = 6;

  /*
   * Power mode for sensor (true for low power, false for normal)
   */
  optional bool set_power_mode = 7;
}

message SEN5X_config {
  /*
   * Reference temperature in degC
   */
  optional float set_temperature = 1;

  /*
   * One-shot mode (true for low power - one-shot mode, false for normal - continuous mode)
   */
  optional bool set_one_shot_mode = 2;
}

message SCD30_config {
  /*
   * Set Automatic self-calibration enabled
   */
  optional bool set_asc = 1;

  /*
   * Recalibration target CO2 concentration in ppm (FRC or ASC)
   */
  optional uint32 set_target_co2_conc = 2;

  /*
   * Reference temperature in degC
   */
  optional float set_temperature = 3;

  /*
   * Altitude of sensor in meters above sea level. 0 - 3000m (overrides ambient pressure)
   */
  optional uint32 set_altitude = 4;

  /*
   * Power mode for sensor (true for low power, false for normal)
   */
  optional uint32 set_measurement_interval = 5;

  /*
   * Perform a factory reset of the sensor
   */
  optional bool soft_reset = 6;
}

message SHTXX_config {
  /*
   * Accuracy mode (0 = low, 1 = medium, 2 = high)
   */
  optional uint32 set_accuracy = 1;
}