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)
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_channel_request | uint32 | 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) |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_owner_request | bool | Send the current owner data in the response to this message. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_config_request | [`AdminMessage.ConfigType`](#adminmessageconfigtype) | Ask for the following config data to be sent |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_config_response | [`Config`](#config) | Send the current Config in the response to this message. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_module_config_request | [`AdminMessage.ModuleConfigType`](#adminmessagemoduleconfigtype) | Ask for the following config data to be sent |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_module_config_response | [`ModuleConfig`](#moduleconfig) | Send the current Config in the response to this message. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_canned_message_module_messages_request | bool | Get the Canned Message Module messages in the response to this message. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_canned_message_module_messages_response | string | Get the Canned Message Module messages in the response to this message. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.get_device_metadata_request | bool | Request the node to send device metadata (firmware, protobuf version, etc) |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.set_owner | [`User`](#user) | Set the owner for this node |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.set_channel | [`Channel`](#channel) | 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. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.set_config | [`Config`](#config) | Set the current Config |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.set_module_config | [`ModuleConfig`](#moduleconfig) | Set the current Config |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.set_canned_message_module_messages | string | Set the Canned Message Module messages text. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.confirm_set_config | bool | Sent immediatly after a config change has been sent to ensure comms, if this is not recieved, the config will be reverted after 10 mins |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.confirm_set_module_config | bool | Sent immediatly after a config change has been sent to ensure comms, if this is not recieved, the config will be reverted after 10 mins |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.confirm_set_channel | bool | Setting channels/radio config remotely carries the risk that you might send an invalid config and the radio never talks to your mesh again. Therefore if setting either of these properties remotely, you must send a confirm_xxx message within 10 minutes. If you fail to do so, the radio will assume loss of comms and revert your changes. These messages are optional when changing the local node. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.reboot_ota_seconds | int32 | 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. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.exit_simulator | bool | This message is only supported for the simulator porduino build. If received the simulator will exit successfully. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.reboot_seconds | int32 | Tell the node to reboot in this many seconds (or <0 to cancel reboot) |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.shutdown_seconds | int32 | Tell the node to shutdown in this many seconds (or <0 to cancel shutdown) |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.factory_reset | int32 | Tell the node to factory reset, all device settings will be returned to factory defaults. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.nodedb_reset | int32 | Tell the node to reset the nodedb. |
| messages | string | Predefined messages for canned message module separated by '|' characters. |
## channel.proto
### Channel
:::note `message` description
A pair of a channel number, mode and the (sharable) settings for that channel
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| index | int32 | The index of this channel in the channel table (from 0 to MAX_NUM_CHANNELS-1) (Someday - not currently implemented) An index of -1 could be used to mean "set by name", in which case the target node will find and set the channel by settings.name. |
| settings | [`ChannelSettings`](#channelsettings) | The new settings, or NULL to disable that channel |
| role | [`Channel.Role`](#channelrole) | TODO: REPLACE |
### ChannelSettings
:::note `message` description
Full settings (center freq, spread factor, pre-shared secret key etc...)
needed to configure a radio for speaking on a particular channel This
information can be encoded as a QRcode/url so that other users can configure
their radio to join the same channel.
A note about how channel names are shown to users: channelname-Xy
poundsymbol is a prefix used to indicate this is a channel name (idea from @professr).
Where X is a letter from A-Z (base 26) representing a hash of the PSK for this
channel - so that if the user changes anything about the channel (which does
force a new PSK) this letter will also change. Thus preventing user confusion if
two friends try to type in a channel name of "BobsChan" and then can't talk
because their PSKs will be different.
The PSK is hashed into this letter by "0x41 + [xor all bytes of the psk ] modulo 26"
This also allows the option of someday if people have the PSK off (zero), the
users COULD type in a channel name and be able to talk.
Y is a lower case letter from a-z that represents the channel 'speed' settings
(for some future definition of speed)
FIXME: Add description of multi-channel support and how primary vs secondary channels are used.
FIXME: explain how apps use channels for security.
explain how remote settings and remote gpio are managed as an example
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| channel_num | uint32 | Deprecated in favor of LoraConfig.channel_num |
| psk | bytes | A simple pre-shared key for now for crypto. Must be either 0 bytes (no crypto), 16 bytes (AES128), or 32 bytes (AES256). A special shorthand is used for 1 byte long psks. These psks should be treated as only minimally secure, because they are listed in this source code. Those bytes are mapped using the following scheme: `0` = No crypto `1` = The special "default" channel key: {0xd4, 0xf1, 0xbb, 0x3a, 0x20, 0x29, 0x07, 0x59, 0xf0, 0xbc, 0xff, 0xab, 0xcf, 0x4e, 0x69, 0xbf} `2` through 10 = The default channel key, except with 1 through 9 added to the last byte. Shown to user as simple1 through 10 |
| name | string | A SHORT name that will be packed into the URL. Less than 12 bytes. Something for end users to call the channel If this is the empty string it is assumed that this channel is the special (minimally secure) "Default"channel. In user interfaces it should be rendered as a local language translation of "X". For channel_num hashing empty string will be treated as "X". Where "X" is selected based on the English words listed above for ModemPreset |
| id | fixed32 | Used to construct a globally unique channel ID. The full globally unique ID will be: "name.id" where ID is shown as base36. Assuming that the number of meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. And the penalty for collision is low as well, it just means that anyone trying to decrypt channel messages might need to try multiple candidate channels. Any time a non wire compatible change is made to a channel, this field should be regenerated. There are a small number of 'special' globally known (and fairly) insecure standard channels. Those channels do not have a numeric id included in the settings, but instead it is pulled from a table of well known IDs. (see Well Known Channels FIXME) |
| uplink_enabled | bool | If true, messages on the mesh will be sent to the *public* internet by any gateway ndoe |
| downlink_enabled | bool | If true, messages seen on the internet will be forwarded to the local mesh. |
### Channel.Role
:::note `enum` description
How this channel is being used (or not).
Note: this field is an enum to give us options for the future.
In particular, someday we might make a 'SCANNING' option.
SCANNING channels could have different frequencies and the radio would
occasionally check that freq to see if anything is being transmitted.
For devices that have multiple physical radios attached, we could keep multiple PRIMARY/SCANNING channels active at once to allow
cross band routing as needed.
If a device has only a single radio (the common case) only one channel can be PRIMARY at a time
(but any number of SECONDARY channels can't be sent received on that common frequency)
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `DISABLED` | `0` | This channel is not in use right now |
| `PRIMARY` | `1` | This channel is used to set the frequency for the radio - all other enabled channels must be SECONDARY |
| `SECONDARY` | `2` | Secondary channels are only used for encryption/decryption/authentication purposes. Their radio settings (freq etc) are ignored, only psk is used. |
| enabled | bool | Enable Bluetooth on the device |
| mode | [`Config.BluetoothConfig.PairingMode`](#configbluetoothconfigpairingmode) | Determines the pairing strategy for the device |
| fixed_pin | uint32 | Specified pin for PairingMode.FixedPin |
### Config.DeviceConfig
:::note `message` description
Configuration
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| role | [`Config.DeviceConfig.Role`](#configdeviceconfigrole) | Sets the role of node |
| serial_enabled | bool | Disabling this will disable the SerialConsole by not initilizing the StreamAPI |
| debug_log_enabled | bool | By default we turn off logging as soon as an API client connects (to keep shared serial link quiet). Set this to true to leave the debug log outputting even when API is active. |
### Config.DisplayConfig
:::note `message` description
Display Config
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| screen_on_secs | uint32 | Number of seconds the screen stays on after pressing the user button or receiving a message 0 for default of one minute MAXUINT for always on |
| gps_format | [`Config.DisplayConfig.GpsCoordinateFormat`](#configdisplayconfiggpscoordinateformat) | How the GPS coordinates are formatted on the OLED screen. |
| auto_screen_carousel_secs | uint32 | Automatically toggles to the next page on the screen like a carousel, based the specified interval in seconds. Potentially useful for devices without user buttons. |
| compass_north_top | bool | If this is set, the displayed compass will always point north. if unset, the old behaviour (top of display is heading direction) is used. |
| flip_screen | bool | Flip screen vertically, for cases that mount the screen upside down |
| units | [`Config.DisplayConfig.DisplayUnits`](#configdisplayconfigdisplayunits) | Perferred display units |
| use_preset | bool | When enabled, the `modem_preset` fields will be adheared to, else the `bandwidth`/`spread_factor`/`coding_rate` will be taked from their respective manually defined fields |
| modem_preset | [`Config.LoRaConfig.ModemPreset`](#configloraconfigmodempreset) | Either modem_config or bandwidth/spreading/coding will be specified - NOT BOTH. As a heuristic: If bandwidth is specified, do not use modem_config. Because protobufs take ZERO space when the value is zero this works out nicely. This value is replaced by bandwidth/spread_factor/coding_rate. If you'd like to experiment with other options add them to MeshRadio.cpp in the device code. |
| bandwidth | uint32 | Bandwidth in MHz Certain bandwidth numbers are 'special' and will be converted to the appropriate floating point value: 31 -> 31.25MHz |
| spread_factor | uint32 | A number from 7 to 12. Indicates number of chirps per symbol as 1<<spread_factor. |
| coding_rate | uint32 | The denominator of the coding rate. ie for 4/5, the value is 5. 4/8 the value is 8. |
| frequency_offset | float | This parameter is for advanced users with advanced test equipment, we do not recommend most users use it. A frequency offset that is added to to the calculated band center frequency. Used to correct for crystal calibration errors. |
| region | [`Config.LoRaConfig.RegionCode`](#configloraconfigregioncode) | The region code for the radio (US, CN, EU433, etc...) |
| hop_limit | uint32 | Maximum number of hops. This can't be greater than 7. Default of 3 |
| tx_enabled | bool | Disable TX from the LoRa radio. Useful for hot-swapping antennas and other tests. Defaults to false |
| tx_power | int32 | If zero then, use default max legal continuous power (ie. something that won't burn out the radio hardware) In most cases you should use zero here. Units are in dBm. |
| channel_num | uint32 | This is controlling the actual hardware frequency the radio is transmitting on. Most users should never need to be exposed to this field/concept. A channel number between 1 and NUM_CHANNELS (whatever the max is in the current region). If ZERO then the rule is "use the old channel name hash based algorithm to derive the channel number") If using the hash algorithm the channel number will be: hash(channel_name) % NUM_CHANNELS (Where num channels depends on the regulatory region). |
| ignore_incoming | uint32 | For testing it is useful sometimes to force a node to never listen to particular other nodes (simulating radio out of range). All nodenums listed in ignore_incoming will have packets they send droped on receive (by router.cpp) |
| position_broadcast_secs | uint32 | We should send our position this often (but only if it has changed significantly) Defaults to 15 minutes |
| position_broadcast_smart_enabled | bool | Adaptive position braoadcast, which is now the default. |
| fixed_position | bool | If set, this node is at a fixed position. We will generate GPS position updates at the regular interval, but use whatever the last lat/lon/alt we have for the node. The lat/lon/alt can be set by an internal GPS or with the help of the app. |
| gps_enabled | bool | Is GPS enabled for this node? |
| gps_update_interval | uint32 | How often should we try to get GPS position (in seconds) or zero for the default of once every 30 seconds or a very large value (maxint) to update only once at boot. |
| gps_attempt_time | uint32 | How long should we try to get our position during each gps_update_interval attempt? (in seconds) Or if zero, use the default of 30 seconds. If we don't get a new gps fix in that time, the gps will be put into sleep until the next gps_update_rate window. |
| position_flags | uint32 | Bit field of boolean configuration options for POSITION messages (bitwise OR of PositionFlags) |
### Config.PowerConfig
:::note `message` description
Power Config\
See [Power Config](/docs/settings/config/power) for additional power config details.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| is_power_saving | bool | If set, we are powered from a low-current source (i.e. solar), so even if it looks like we have power flowing in we should try to minimize power consumption as much as possible. YOU DO NOT NEED TO SET THIS IF YOU'VE set is_router (it is implied in that case). Advanced Option |
| on_battery_shutdown_after_secs | uint32 | If non-zero, the device will fully power off this many seconds after external power is removed. |
| adc_multiplier_override | float | Ratio of voltage divider for battery pin eg. 3.20 (R1=100k, R2=220k) Overrides the ADC_MULTIPLIER defined in variant for battery voltage calculation. Should be set to floating point value between 2 and 4 Fixes issues on Heltec v2 |
| wait_bluetooth_secs | uint32 | Wait Bluetooth Seconds The number of seconds for to wait before turning off BLE in No Bluetooth states 0 for default of 1 minute |
| mesh_sds_timeout_secs | uint32 | Mesh Super Deep Sleep Timeout Seconds While in Light Sleep if this value is exceeded we will lower into super deep sleep for sds_secs (default 1 year) or a button press 0 for default of two hours, MAXUINT for disabled |
| sds_secs | uint32 | Super Deep Sleep Seconds While in Light Sleep if mesh_sds_timeout_secs is exceeded we will lower into super deep sleep for this value (default 1 year) or a button press 0 for default of one year |
| ls_secs | uint32 | Light Sleep Seconds In light sleep the CPU is suspended, LoRa radio is on, BLE is off an GPS is on ESP32 Only 0 for default of 300 |
| min_wake_secs | uint32 | Minimum Wake Seconds While in light sleep when we receive packets on the LoRa radio we will wake and handle them and stay awake in no BLE mode for this value 0 for default of 10 seconds |
### Config.BluetoothConfig.PairingMode
| Name | Number | Description |
| ---- | ------ | ----------- |
| `RANDOM_PIN` | `0` | Device generates a random pin that will be shown on the screen of the device for pairing |
| `FIXED_PIN` | `1` | Device requires a specified fixed pin for pairing |
| `NO_PIN` | `2` | Device requires no pin for pairing |
### Config.DeviceConfig.Role
:::note `enum` description
Defines the device's role on the Mesh network
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `CLIENT` | `0` | Client device role |
| `CLIENT_MUTE` | `1` | Client Mute device role Same as a client except packets will not hop over this node, does not contribute to routing packets for mesh. |
| `ROUTER` | `2` | Router device role. Mesh packets will prefer to be routed over this node. This node will not be used by client apps. The wifi/ble radios and the oled screen will be put to sleep. |
| `ROUTER_CLIENT` | `3` | Router Client device role Mesh packets will prefer to be routed over this node. The Router Client can be used as both a Router and an app connected Client. |
### Config.DisplayConfig.DisplayUnits
:::note `enum` description
Unit display preference
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `METRIC` | `0` | Metric (Default) |
| `IMPERIAL` | `1` | Imperial |
### Config.DisplayConfig.GpsCoordinateFormat
:::note `enum` description
How the GPS coordinates are displayed on the OLED screen.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `DEC` | `0` | GPS coordinates are displayed in the normal decimal degrees format: DD.DDDDDD DDD.DDDDDD |
| `DMS` | `1` | GPS coordinates are displayed in the degrees minutes seconds format: DD°MM'SS"C DDD°MM'SS"C, where C is the compass point representing the locations quadrant |
| `UTM` | `2` | Universal Transverse Mercator format: ZZB EEEEEE NNNNNNN, where Z is zone, B is band, E is easting, N is northing |
| `MGRS` | `3` | Military Grid Reference System format: ZZB CD EEEEE NNNNN, where Z is zone, B is band, C is the east 100k square, D is the north 100k square, E is easting, N is northing |
| `OLC` | `4` | Open Location Code (aka Plus Codes). |
| `OSGR` | `5` | Ordnance Survey Grid Reference (the National Grid System of the UK). Format: AB EEEEE NNNNN, where A is the east 100k square, B is the north 100k square, E is the easting, N is the northing |
| `HEADING` | `256` | Include positional heading Intended for use with vehicle not walking speeds walking speeds are likely to be error prone like the compass |
| `SPEED` | `512` | Include positional speed Intended for use with vehicle not walking speeds walking speeds are likely to be error prone like the compass |
## device_metadata.proto
### DeviceMetadata
:::note `message` description
Device metadata response
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| firmware_version | string | Device firmware version string |
| device_state_version | uint32 | Device state version |
| canShutdown | bool | Indicates whether the device can shutdown CPU natively or via power management chip |
| hasWifi | bool | Indicates that the device has native wifi capability |
| hasBluetooth | bool | Indicates that the device has native bluetooth capability |
| hasEthernet | bool | Indicates that the device has an ethernet peripheral |
## deviceonly.proto
### ChannelFile
:::note `message` description
The on-disk saved channels
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| channels | [`Channel`](#channel) | The channels our node knows about |
| version | uint32 | A version integer used to invalidate old save files when we make incompatible changes This integer is set at build time and is private to NodeDB.cpp in the device code. |
### DeviceState
:::note `message` description
This message is never sent over the wire, but it is used for serializing DB
state to flash in the device code
FIXME, since we write this each time we enter deep sleep (and have infinite
flash) it would be better to use some sort of append only data structure for
the receive queue and use the preferences store for the other stuff
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| my_node | [`MyNodeInfo`](#mynodeinfo) | Read only settings/info about this node |
| receive_queue | [`MeshPacket`](#meshpacket) | Received packets saved for delivery to the phone |
| version | uint32 | A version integer used to invalidate old save files when we make incompatible changes This integer is set at build time and is private to NodeDB.cpp in the device code. |
| rx_text_message | [`MeshPacket`](#meshpacket) | We keep the last received text message (only) stored in the device flash, so we can show it on the screen. Might be null |
| no_save | bool | Used only during development. Indicates developer is testing and changes should never be saved to flash. |
| did_gps_reset | bool | Some GPSes seem to have bogus settings from the factory, so we always do one factory reset. |
### OEMStore
:::note `message` description
This can be used for customizing the firmware distribution. If populated,
show a secondary bootup screen with cuatom logo and text for 2.5 seconds.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| oem_icon_width | uint32 | The Logo width in Px |
| oem_icon_height | uint32 | The Logo height in Px |
| oem_icon_bits | bytes | The Logo in xbm bytechar format |
| oem_font | [`ScreenFonts`](#screenfonts) | Use this font for the OEM text. |
| oem_text | string | Use this font for the OEM text. |
| oem_aes_key | bytes | The default device encryption key, 16 or 32 byte |
### ScreenFonts
:::note `enum` description
TODO: REPLACE
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `FONT_SMALL` | `0` | TODO: REPLACE |
| `FONT_MEDIUM` | `1` | TODO: REPLACE |
| `FONT_LARGE` | `2` | TODO: REPLACE |
## localonly.proto
### LocalConfig
| Field | Type | Description |
| ----- | ---- | ----------- |
| device | [`Config.DeviceConfig`](#configdeviceconfig) | The part of the config that is specific to the Device |
| position | [`Config.PositionConfig`](#configpositionconfig) | The part of the config that is specific to the GPS Position |
| power | [`Config.PowerConfig`](#configpowerconfig) | The part of the config that is specific to the Power settings |
| network | [`Config.NetworkConfig`](#confignetworkconfig) | The part of the config that is specific to the Wifi Settings |
| display | [`Config.DisplayConfig`](#configdisplayconfig) | The part of the config that is specific to the Display |
| lora | [`Config.LoRaConfig`](#configloraconfig) | The part of the config that is specific to the Lora Radio |
| bluetooth | [`Config.BluetoothConfig`](#configbluetoothconfig) | The part of the config that is specific to the Bluetooth settings |
| version | uint32 | A version integer used to invalidate old save files when we make incompatible changes This integer is set at build time and is private to NodeDB.cpp in the device code. |
### LocalModuleConfig
| Field | Type | Description |
| ----- | ---- | ----------- |
| mqtt | [`ModuleConfig.MQTTConfig`](#moduleconfigmqttconfig) | The part of the config that is specific to the MQTT module |
| serial | [`ModuleConfig.SerialConfig`](#moduleconfigserialconfig) | The part of the config that is specific to the Serial module |
| external_notification | [`ModuleConfig.ExternalNotificationConfig`](#moduleconfigexternalnotificationconfig) | The part of the config that is specific to the ExternalNotification module |
| store_forward | [`ModuleConfig.StoreForwardConfig`](#moduleconfigstoreforwardconfig) | The part of the config that is specific to the Store & Forward module |
| range_test | [`ModuleConfig.RangeTestConfig`](#moduleconfigrangetestconfig) | The part of the config that is specific to the RangeTest module |
| telemetry | [`ModuleConfig.TelemetryConfig`](#moduleconfigtelemetryconfig) | The part of the config that is specific to the Telemetry module |
| canned_message | [`ModuleConfig.CannedMessageConfig`](#moduleconfigcannedmessageconfig) | The part of the config that is specific to the Canned Message module |
| version | uint32 | A version integer used to invalidate old save files when we make incompatible changes This integer is set at build time and is private to NodeDB.cpp in the device code. |
## mesh.proto
### Compressed
:::note `message` description
Compressed message payload
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| portnum | [`PortNum`](#portnum) | PortNum to determine the how to handle the compressed payload. |
| data | bytes | Compressed data. |
### Data
:::note `message` description
(Formerly called SubPacket)
The payload portion fo a packet, this is the actual bytes that are sent
inside a radio packet (because from/to are broken out by the comms library)
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| portnum | [`PortNum`](#portnum) | Formerly named typ and of type Type |
| payload | bytes | TODO: REPLACE |
| want_response | bool | Not normally used, but for testing a sender can request that recipient responds in kind (i.e. if it received a position, it should unicast back it's position). Note: that if you set this on a broadcast you will receive many replies. |
| dest | fixed32 | The address of the destination node. This field is is filled in by the mesh radio device software, application layer software should never need it. RouteDiscovery messages _must_ populate this. Other message types might need to if they are doing multihop routing. |
| source | fixed32 | The address of the original sender for this message. This field should _only_ be populated for reliable multihop packets (to keep packets small). |
| request_id | fixed32 | Only used in routing or response messages. Indicates the original message ID that this message is reporting failure on. (formerly called original_id) |
| reply_id | fixed32 | If set, this message is intened to be a reply to a previously sent message with the defined id. |
| emoji | fixed32 | Defaults to false. If true, then what is in the payload should be treated as an emoji like giving a message a heart or poop emoji. |
### FromRadio
:::note `message` description
Packets from the radio to the phone will appear on the fromRadio characteristic.
It will support READ and NOTIFY. When a new packet arrives the device will BLE notify?
It will sit in that descriptor until consumed by the phone,
at which point the next item in the FIFO will be populated.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| id | uint32 | The packet id, used to allow the phone to request missing read packets from the FIFO, see our bluetooth docs |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.packet | [`MeshPacket`](#meshpacket) | Log levels, chosen to match python logging conventions. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.my_info | [`MyNodeInfo`](#mynodeinfo) | Tells the phone what our node number is, can be -1 if we've not yet joined a mesh. NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.node_info | [`NodeInfo`](#nodeinfo) | One packet is sent for each node in the on radio DB starts over with the first node in our DB |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.config | [`Config`](#config) | Include a part of the config (was: RadioConfig radio) |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.log_record | [`LogRecord`](#logrecord) | Set to send debug console output over our protobuf stream |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.config_complete_id | uint32 | Sent as true once the device has finished sending all of the responses to want_config recipient should check if this ID matches our original request nonce, if not, it means your config responses haven't started yet. NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.rebooted | bool | Sent to tell clients the radio has just rebooted. Set to true if present. Not used on all transports, currently just used for the serial console. NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.moduleConfig | [`ModuleConfig`](#moduleconfig) | Include module config |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.channel | [`Channel`](#channel) | One packet is sent for each channel |
### LogRecord
:::note `message` description
Debug output from the device.
To minimize the size of records inside the device code, if a time/source/level is not set
on the message it is assumed to be a continuation of the previously sent message.
This allows the device code to use fixed maxlen 64 byte strings for messages,
and then extend as needed by emitting multiple records.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| message | string | Log levels, chosen to match python logging conventions. |
| time | fixed32 | Seconds since 1970 - or 0 for unknown/unset |
| source | string | Usually based on thread name - if known |
| level | [`LogRecord.Level`](#logrecordlevel) | Not yet set |
### MeshPacket
:::note `message` description
A packet envelope sent/received over the mesh
only payload_variant is sent in the payload portion of the LORA packet.
The other fields are either not sent at all, or sent in the special 16 byte LORA header.
| from | fixed32 | The sending node number. Note: Our crypto implementation uses this field as well. See [crypto](/docs/overview/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| to | fixed32 | The (immediatSee Priority description for more details.y should be fixed32 instead, this encoding only hurts the ble link though. |
| channel | uint32 | (Usually) If set, this indicates the index in the secondary_channels table that this packet was sent/received on. If unset, packet was on the primary channel. A particular node might know only a subset of channels in use on the mesh. Therefore channel_index is inherently a local concept and meaningless to send between nodes. Very briefly, while sending and receiving deep inside the device Router code, this field instead contains the 'channel hash' instead of the index. This 'trick' is only used while the payload_variant is an 'encrypted'. |
| id | fixed32 | A unique ID for this packet. Always 0 for no-ack packets or non broadcast packets (and therefore take zero bytes of space). Otherwise a unique ID for this packet, useful for flooding algorithms. ID only needs to be unique on a _per sender_ basis, and it only needs to be unique for a few minutes (long enough to last for the length of any ACK or the completion of a mesh broadcast flood). Note: Our crypto implementation uses this id as well. See [crypto](/docs/overview/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| rx_time | fixed32 | The time this message was received by the esp32 (secs since 1970). Note: this field is _never_ sent on the radio link itself (to save space) Times are typically not sent over the mesh, but they will be added to any Packet (chain of SubPacket) sent to the phone (so the phone can know exact time of reception) |
| rx_snr | float | Never* sent over the radio links. Set during reception to indicate the SNR of this packet. Used to collect statistics on current link quality. |
| hop_limit | uint32 | If unset treated as zero (no forwarding, send to adjacent nodes only) if 1, allow hopping through one node, etc... For our usecase real world topologies probably have a max of about 3. This field is normally placed into a few of bits in the header. |
| want_ack | bool | This packet is being sent as a reliable message, we would prefer it to arrive at the destination. We would like to receive a ack packet in response. Broadcasts messages treat this flag specially: Since acks for broadcasts would rapidly flood the channel, the normal ack behavior is suppressed. Instead, the original sender listens to see if at least one node is rebroadcasting this packet (because naive flooding algorithm). If it hears that the odds (given typical LoRa topologies) the odds are very high that every node should eventually receive the message. So FloodingRouter.cpp generates an implicit ack which is delivered to the original sender. If after some time we don't hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic. Note: This flag is normally sent in a flag bit in the header when sent over the wire |
| priority | [`MeshPacket.Priority`](#meshpacketpriority) | The priority of this message for sending. See MeshPacket.Priority description for more details. |
| rx_rssi | int32 | rssi of received packet. Only sent to phone for dispay purposes. |
| delayed | [`MeshPacket.Delayed`](#meshpacketdelayed) | Describe if this message is delayed |
### MyNodeInfo
:::note `message` description
Unique local debugging info for this node
Note: we don't include position or the user info, because that will come in the
Sent to the phone in response to WantNodes.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| my_node_num | uint32 | Tells the phone what our node number is, default starting value is lowbyte of macaddr, but it will be fixed if that is already in use |
| has_gps | bool | Note: This flag merely means we detected a hardware GPS in our node. Not the same as UserPreferences.location_sharing |
| max_channels | uint32 | The maximum number of 'software' channels that can be set on this node. |
| firmware_version | string | 0.0.5 etc... |
| error_code | [`CriticalErrorCode`](#criticalerrorcode) | An error message we'd like to report back to the mothership through analytics. It indicates a serious bug occurred on the device, the device coped with it, but we still want to tell the devs about the bug. This field will be cleared after the phone reads MyNodeInfo (i.e. it will only be reported once) a numeric error code to go with error message, zero means no error |
| error_address | uint32 | A numeric error address (nonzero if available) |
| error_count | uint32 | The total number of errors this node has ever encountered (well - since the last time we discarded preferences) |
| reboot_count | uint32 | The total number of reboots this node has ever encountered (well - since the last time we discarded preferences) |
| bitrate | float | Calculated bitrate of the current channel (in Bytes Per Second) |
| message_timeout_msec | uint32 | How long before we consider a message abandoned and we can clear our caches of any messages in flight Normally quite large to handle the worst case message delivery time, 5 minutes. Formerly called FLOOD_EXPIRE_TIME in the device code |
| min_app_version | uint32 | The minimum app version that can talk to this device. Phone/PC apps should compare this to their build number and if too low tell the user they must update their app |
| air_period_tx | uint32 | 24 time windows of 1hr each with the airtime transmitted out of the device per hour. |
| air_period_rx | uint32 | 24 time windows of 1hr each with the airtime of valid packets for your mesh. |
| has_wifi | bool | Is the device wifi capable? |
| channel_utilization | float | Utilization for the current channel, including well formed TX, RX and malformed RX (aka noise). |
| air_util_tx | float | Percent of airtime for transmission used within the last hour. |
### NodeInfo
:::note `message` description
The bluetooth to device link:
Old BTLE protocol docs from TODO, merge in above and make real docs...
use protocol buffers, and NanoPB
messages from device to phone:
POSITION_UPDATE (..., time)
TEXT_RECEIVED(from, text, time)
OPAQUE_RECEIVED(from, payload, time) (for signal messages or other applications)
messages from phone to device:
SET_MYID(id, human readable long, human readable short) (send down the unique ID
string used for this node, a human readable string shown for that id, and a very
short human readable string suitable for oled screen) SEND_OPAQUE(dest, payload)
(for signal messages or other applications) SEND_TEXT(dest, text) Get all
nodes() (returns list of nodes, with full info, last time seen, loc, battery
level etc) SET_CONFIG (switches device to a new set of radio params and
preshared key, drops all existing nodes, force our node to rejoin this new group)
Full information about a node on the mesh
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| num | uint32 | The node number |
| user | [`User`](#user) | The user info for this node |
| position | [`Position`](#position) | This position data. Note: before 1.2.14 we would also store the last time we've heard from this node in position.time, that is no longer true. Position.time now indicates the last time we received a POSITION from that node. |
| snr | float | Returns the Signal-to-noise ratio (SNR) of the last received message, as measured by the receiver. Return SNR of the last received message in dB |
| last_heard | fixed32 | Set to indicate the last time we received a packet from this node |
| device_metrics | [`DeviceMetrics`](#devicemetrics) | The latest device metrics for the node. |
### Position
:::note `message` description
a gps position
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| latitude_i | sfixed32 | The new preferred location encoding, multiply by 1e-7 to get degrees in floating point |
| longitude_i | sfixed32 | TODO: REPLACE |
| altitude | int32 | In meters above MSL (but see issue #359) |
| time | fixed32 | This is usually not sent over the mesh (to save space), but it is sent from the phone so that the local device can set its RTC If it is sent over the mesh (because there are devices on the mesh without GPS), it will only be sent by devices which has a hardware GPS clock. seconds since 1970 |
| timestamp | fixed32 | Positional timestamp (actual timestamp of GPS solution) in integer epoch seconds |
| timestamp_millis_adjust | int32 | Pos. timestamp milliseconds adjustment (rarely available or required) |
| altitude_hae | sint32 | HAE altitude in meters - can be used instead of MSL altitude |
| altitude_geoidal_separation | sint32 | Geoidal separation in meters |
| PDOP | uint32 | Horizontal, Vertical and Position Dilution of Precision, in 1/100 units - PDOP is sufficient for most cases - for higher precision scenarios, HDOP and VDOP can be used instead, in which case PDOP becomes redundant (PDOP=sqrt(HDOP^2 + VDOP^2)) TODO: REMOVE/INTEGRATE |
| HDOP | uint32 | TODO: REPLACE |
| VDOP | uint32 | TODO: REPLACE |
| gps_accuracy | uint32 | GPS accuracy (a hardware specific constant) in mm multiplied with DOP to calculate positional accuracy Default: "'bout three meters-ish" :) |
| ground_speed | uint32 | Ground speed in m/s and True North TRACK in 1/100 degrees Clarification of terms: - "track" is the direction of motion (measured in horizontal plane) - "heading" is where the fuselage points (measured in horizontal plane) - "yaw" indicates a relative rotation about the vertical axis TODO: REMOVE/INTEGRATE |
| sats_in_view | uint32 | GPS "Satellites in View" number |
| sensor_id | uint32 | Sensor ID - in case multiple positioning sensors are being used |
| next_update | uint32 | Estimated/expected time (in seconds) until next update: - if we update at fixed intervals of X seconds, use X - if we update at dynamic intervals (based on relative movement etc), but "AT LEAST every Y seconds", use Y |
| seq_number | uint32 | A sequence number, incremented with each Position message to help detect lost updates if needed |
### RouteDiscovery
:::note `message` description
A message used in our Dynamic Source Routing protocol (RFC 4728 based)
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| route | fixed32 | The list of nodenums this packet has visited so far |
### Routing
:::note `message` description
A Routing control Data packet handled by the routing module
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) variant.route_request | [`RouteDiscovery`](#routediscovery) | A route request going from the requester |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) variant.route_reply | [`RouteDiscovery`](#routediscovery) | A route reply |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) variant.error_reason | [`Routing.Error`](#routingerror) | A failure in delivering a message (usually used for routing control messages, but might be provided in addition to ack.fail_id to provide details on the type of failure). |
### ToRadio
:::note `message` description
Packets/commands to the radio will be written (reliably) to the toRadio characteristic.
Once the write completes the phone can assume it is handled.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.packet | [`MeshPacket`](#meshpacket) | Send this packet on the mesh |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.want_config_id | uint32 | Phone wants radio to send full node db to the phone, This is typically the first packet sent to the radio when the phone gets a bluetooth connection. The radio will respond by sending back a MyNodeInfo, a owner, a radio config and a series of FromRadio.node_infos, and config_complete the integer you write into this field will be reported back in the config_complete_id response this allows clients to never be confused by a stale old partially sent config. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.disconnect | bool | Tell API server we are disconnecting now. This is useful for serial links where there is no hardware/protocol based notification that the client has dropped the link. (Sending this message is optional for clients) |
### User
:::note `message` description
Broadcast when a newly powered mesh node wants to find a node num it can use
Sent from the phone over bluetooth to set the user id for the owner of this node.
Also sent from nodes to each other when a new node signs on (so all clients can have this info)
The algorithm is as follows:
when a node starts up, it broadcasts their user and the normal flow is for all
other nodes to reply with their User as well (so the new node can build its nodedb)
If a node ever receives a User (not just the first broadcast) message where
the sender node number equals our node number, that indicates a collision has
occurred and the following steps should happen:
If the receiving node (that was already in the mesh)'s macaddr is LOWER than the
new User who just tried to sign in: it gets to keep its nodenum.
We send a broadcast message of OUR User (we use a broadcast so that the other node can
receive our message, considering we have the same id - it also serves to let
observers correct their nodedb) - this case is rare so it should be okay.
If any node receives a User where the macaddr is GTE than their local macaddr,
they have been vetoed and should pick a new random nodenum (filtering against
whatever it knows about the nodedb) and rebroadcast their User.
A few nodenums are reserved and will never be requested:
0xff - broadcast
0 through 3 - for future use
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| id | string | A globally unique ID string for this user. In the case of Signal that would mean +16504442323, for the default macaddr derived id it would be !<8 hexidecimal bytes>. Note: app developers are encouraged to also use the following standard node IDs "^all" (for broadcast), "^local" (for the locally connected node) |
| long_name | string | A full name for this user, i.e. "Kevin Hester" |
| short_name | string | A VERY short name, ideally two characters. Suitable for a tiny OLED screen |
| macaddr | bytes | This is the addr of the radio. Not populated by the phone, but added by the esp32 when broadcasting |
| hw_model | [`HardwareModel`](#hardwaremodel) | TBEAM, HELTEC, etc... Starting in 1.2.11 moved to hw_model enum in the NodeInfo object. Apps will still need the string here for older builds (so OTA update can find the right image), but if the enum is available it will be used instead. |
| is_licensed | bool | In some regions Ham radio operators have different bandwidth limitations than others. If this user is a licensed operator, set this flag. Also, "long_name" should be their licence number. |
### Waypoint
:::note `message` description
Waypoint message, used to share arbitrary locations across the mesh
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| id | uint32 | Id of the waypoint |
| latitude_i | sfixed32 | latitude_i |
| longitude_i | sfixed32 | longitude_i |
| expire | uint32 | Time the waypoint is to expire (epoch) |
| locked | bool | If true, only allow the original sender to update the waypoint. |
| name | string | Name of the waypoint - max 30 chars |
| description | string | Description of the waypoint - max 100 chars |
### Constants
:::note `enum` description
Shared constants between device and phone
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `ZERO` | `0` | First enum must be zero, and we are just using this enum to pass int constants between two very different environments |
| `DATA_PAYLOAD_LEN` | `237` | From mesh.options note: this payload length is ONLY the bytes that are sent inside of the Data protobuf (excluding protobuf overhead). The 16 byte header is outside of this envelope |
### CriticalErrorCode
:::note `enum` description
Error codes for critical errors
The device might report these fault codes on the screen.
If you encounter a fault code, please post on the meshtastic.discourse.group
and we'll try to help.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `NONE` | `0` | TODO: REPLACE |
| `TX_WATCHDOG` | `1` | A software bug was detected while trying to send lora |
| `SLEEP_ENTER_WAIT` | `2` | A software bug was detected on entry to sleep |
| `NO_RADIO` | `3` | No Lora radio hardware could be found |
| `UNSPECIFIED` | `4` | Not normally used |
| `UBLOX_UNIT_FAILED` | `5` | We failed while configuring a UBlox GPS |
| `NO_AXP192` | `6` | This board was expected to have a power management chip and it is missing or broken |
| `INVALID_RADIO_SETTING` | `7` | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined. |
| `TRANSMIT_FAILED` | `8` | Radio transmit hardware failure. We sent data to the radio chip, but it didn't reply with an interrupt. |
| `BROWNOUT` | `9` | We detected that the main CPU voltage dropped below the minumum acceptable value |
| `SX1262_FAILURE` | `10` | Selftest of SX1262 radio chip failed |
| `RADIO_SPI_BUG` | `11` | A (likely software but possibly hardware) failure was detected while trying to send packets. If this occurs on your board, please post in the forum so that we can ask you to collect some information to allow fixing this bug |
### HardwareModel
:::note `enum` description
Note: these enum names must EXACTLY match the string used in the device
bin/build-all.sh script.
Because they will be used to find firmware filenames in the android app for OTA updates.
To match the old style filenames, _ is converted to -, p is converted to .
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `UNSET` | `0` | TODO: REPLACE |
| `TLORA_V2` | `1` | TODO: REPLACE |
| `TLORA_V1` | `2` | TODO: REPLACE |
| `TLORA_V2_1_1P6` | `3` | TODO: REPLACE |
| `TBEAM` | `4` | TODO: REPLACE |
| `HELTEC_V2_0` | `5` | The original heltec WiFi_Lora_32_V2, which had battery voltage sensing hooked to GPIO 13 (see HELTEC_V2 for the new version). |
| `TBEAM_V0P7` | `6` | TODO: REPLACE |
| `T_ECHO` | `7` | TODO: REPLACE |
| `TLORA_V1_1P3` | `8` | TODO: REPLACE |
| `RAK4631` | `9` | TODO: REPLACE |
| `HELTEC_V2_1` | `10` | The new version of the heltec WiFi_Lora_32_V2 board that has battery sensing hooked to GPIO 37. Sadly they did not update anything on the silkscreen to identify this board |
| `HELTEC_V1` | `11` | Ancient heltec WiFi_Lora_32 board |
| `LILYGO_TBEAM_S3_CORE` | `12` | New T-BEAM with ESP32-S3 CPU |
| `M5STACK` | `42` | M5 esp32 based MCU modules with enclosure, TFT and LORA Shields. All Variants (Basic, Core, Fire, Core2, Paper) https://m5stack.com/ |
| `PRIVATE_HW` | `255` | Reserved ID For developing private Ports. These will show up in live traffic sparsely, so we can use a high number. Keep it within 8 bits. |
### LogRecord.Level
:::note `enum` description
Log levels, chosen to match python logging conventions.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `UNSET` | `0` | Log levels, chosen to match python logging conventions. |
| `CRITICAL` | `50` | Log levels, chosen to match python logging conventions. |
| `ERROR` | `40` | Log levels, chosen to match python logging conventions. |
| `WARNING` | `30` | Log levels, chosen to match python logging conventions. |
| `INFO` | `20` | Log levels, chosen to match python logging conventions. |
| `DEBUG` | `10` | Log levels, chosen to match python logging conventions. |
| `TRACE` | `5` | Log levels, chosen to match python logging conventions. |
### MeshPacket.Delayed
:::note `enum` description
Identify if this is a delayed packet
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `NO_DELAY` | `0` | If unset, the message is being sent in real time. |
| `DELAYED_BROADCAST` | `1` | The message is delayed and was originally a broadcast |
| `DELAYED_DIRECT` | `2` | The message is delayed and was originally a direct message |
### MeshPacket.Priority
:::note `enum` description
The priority of this message for sending.
Higher priorities are sent first (when managing the transmit queue).
This field is never sent over the air, it is only used internally inside of a local device node.
API clients (either on the local node or connected directly to the node)
can set this parameter if necessary.
(values must be <= 127 to keep protobuf field to one byte in size.
Detailed background on this field:
I noticed a funny side effect of lora being so slow: Usually when making
a protocol there isn’t much need to use message priority to change the order
of transmission (because interfaces are fairly fast).
But for lora where packets can take a few seconds each, it is very important
to make sure that critical packets are sent ASAP.
In the case of meshtastic that means we want to send protocol acks as soon as possible
(to prevent unneeded retransmissions), we want routing messages to be sent next,
then messages marked as reliable and finally ‘background’ packets like periodic position updates.
So I bit the bullet and implemented a new (internal - not sent over the air)
field in MeshPacket called ‘priority’.
And the transmission queue in the router object is now a priority queue.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `UNSET` | `0` | Treated as Priority.DEFAULT |
| `MIN` | `1` | TODO: REPLACE |
| `BACKGROUND` | `10` | Background position updates are sent with very low priority - if the link is super congested they might not go out at all |
| `DEFAULT` | `64` | This priority is used for most messages that don't have a priority set |
| `RELIABLE` | `70` | If priority is unset but the message is marked as want_ack, assume it is important and use a slightly higher priority |
| `ACK` | `120` | Ack/naks are sent with very high priority to ensure that retransmission stops as soon as possible |
| `MAX` | `127` | TODO: REPLACE |
### Position.AltSource
:::note `enum` description
How the altitude was acquired: manual, GPS int/ext, etc
Default: same as location_source if present
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `ALT_UNSET` | `0` | TODO: REPLACE |
| `ALT_MANUAL` | `1` | TODO: REPLACE |
| `ALT_INTERNAL` | `2` | TODO: REPLACE |
| `ALT_EXTERNAL` | `3` | TODO: REPLACE |
| `ALT_BAROMETRIC` | `4` | TODO: REPLACE |
### Position.LocSource
:::note `enum` description
How the location was acquired: manual, onboard GPS, external (EUD) GPS
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `LOC_UNSET` | `0` | TODO: REPLACE |
| `LOC_MANUAL` | `1` | TODO: REPLACE |
| `LOC_INTERNAL` | `2` | TODO: REPLACE |
| `LOC_EXTERNAL` | `3` | TODO: REPLACE |
### Routing.Error
:::note `enum` description
A failure in delivering a message (usually used for routing control messages, but might be provided in addition to ack.fail_id to provide
details on the type of failure).
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `NONE` | `0` | This message is not a failure |
| `NO_ROUTE` | `1` | Our node doesn't have a route to the requested destination anymore. |
| `GOT_NAK` | `2` | We received a nak while trying to forward on your behalf |
| `TIMEOUT` | `3` | TODO: REPLACE |
| `NO_INTERFACE` | `4` | No suitable interface could be found for delivering this packet |
| `MAX_RETRANSMIT` | `5` | We reached the max retransmission count (typically for naive flood routing) |
| `NO_CHANNEL` | `6` | No suitable channel was found for sending this packet (i.e. was requested channel index disabled?) |
| `TOO_LARGE` | `7` | The packet was too big for sending (exceeds interface MTU after encoding) |
| `NO_RESPONSE` | `8` | The request had want_response set, the request reached the destination node, but no service on that node wants to send a response (possibly due to bad channel permissions) |
| `BAD_REQUEST` | `32` | The application layer service on the remote node received your request, but considered your request somehow invalid |
| `NOT_AUTHORIZED` | `33` | The application layer service on the remote node received your request, but considered your request not authorized (i.e you did not send the request on the required bound channel) |
| inputbroker_event_cw | [`ModuleConfig.CannedMessageConfig.InputEventChar`](#moduleconfigcannedmessageconfiginputeventchar) | Generate input event on CW of this kind. |
| inputbroker_event_ccw | [`ModuleConfig.CannedMessageConfig.InputEventChar`](#moduleconfigcannedmessageconfiginputeventchar) | Generate input event on CCW of this kind. |
| inputbroker_event_press | [`ModuleConfig.CannedMessageConfig.InputEventChar`](#moduleconfigcannedmessageconfiginputeventchar) | Generate input event on Press of this kind. |
| updown1_enabled | bool | Enable the Up/Down/Select input device. Can be RAK rotary encoder or 3 buttons. Uses the a/b/press definitions from inputbroker. |
| allow_input_source | string | Input event origin accepted by the canned message module. Can be e.g. "rotEnc1", "upDownEnc1" or keyword "_any" |
| send_bell | bool | CannedMessageModule also sends a bell character with the messages. ExternalNotificationModule can benefit from this feature. |
### ModuleConfig.ExternalNotificationConfig
:::note `message` description
External Notifications Config
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| enabled | bool | Preferences for the ExternalNotificationModule FIXME - Move this out of UserPreferences and into a section for module configuration. |
| output_ms | uint32 | TODO: REPLACE |
| output | uint32 | TODO: REPLACE |
| active | bool | TODO: REPLACE |
| alert_message | bool | TODO: REPLACE |
| alert_bell | bool | TODO: REPLACE |
### ModuleConfig.MQTTConfig
:::note `message` description
MQTT Client Config
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| enabled | bool | If a meshtastic node is able to reach the internet it will normally attempt to gateway any channels that are marked as is_uplink_enabled or is_downlink_enabled. |
| address | string | The server to use for our MQTT global message gateway feature. If not set, the default server will be used |
| username | string | MQTT username to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default username |
| password | string | MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default password |
| encryption_enabled | bool | Whether to send encrypted or decrypted packets to MQTT. This parameter is only honoured if you also set server (the default official mqtt.meshtastic.org server can handle encrypted packets) Decrypted packets may be useful for external systems that want to consume meshtastic packets |
| json_enabled | bool | Whether to send / consume json packets on MQTT |
### ModuleConfig.RangeTestConfig
:::note `message` description
Preferences for the RangeTestModule
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| enabled | bool | Enable the Range Test Module |
| sender | uint32 | Send out range test messages from this node |
| save | bool | Bool value indicating that this node should save a RangeTest.csv file. ESP32 Only |
### ModuleConfig.SerialConfig
:::note `message` description
Serial Config
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| enabled | bool | Preferences for the SerialModule FIXME - Move this out of UserPreferences and into a section for module configuration. |
| environment_display_fahrenheit | bool | We'll always read the sensor in Celsius, but sometimes we might want to display the results in Fahrenheit as a "user preference". |
This message wraps a MeshPacket with extra metadata about the sender and how it arrived.
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| packet | [`MeshPacket`](#meshpacket) | The (probably encrypted) packet |
| channel_id | string | The global channel ID it was sent on |
| gateway_id | string | The sending gateway node ID. Can we use this to authenticate/prevent fake nodeid impersonation for senders? - i.e. use gateway/mesh id (which is authenticated) + local node id as the globally trusted nodenum |
## portnums.proto
### PortNum
:::note `enum` description
For any new 'apps' that run on the device or via sister apps on phones/PCs they should pick and use a
unique 'portnum' for their application.
If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to this
master table.
PortNums should be assigned in the following range:
0-63 Core Meshtastic use, do not use for third party apps
64-127 Registered 3rd party apps, send in a pull request that adds a new entry to portnums.proto to register your application
256-511 Use one of these portnums for your private applications that you don't want to register publically
All other values are reserved.
Note: This was formerly a Type enum named 'typ' with the same id #
We have change to this 'portnum' based scheme for specifying app handlers for particular payloads.
This change is backwards compatible by treating the legacy OPAQUE/CLEAR_TEXT values identically.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `UNKNOWN_APP` | `0` | Deprecated: do not use in new code (formerly called OPAQUE) A message sent from a device outside of the mesh, in a form the mesh does not understand NOTE: This must be 0, because it is documented in IMeshService.aidl to be so |
| `TEXT_MESSAGE_APP` | `1` | A simple UTF-8 text message, which even the little micros in the mesh can understand and show on their screen eventually in some circumstances even signal might send messages in this form (see below) |
| `REMOTE_HARDWARE_APP` | `2` | Reserved for built-in GPIO/example app. See remote_hardware.proto/HardwareMessage for details on the message sent/received to this port number |
| `REPLY_APP` | `32` | Provides a 'ping' service that replies to any packet it receives. Also serves as a small example module. |
| `IP_TUNNEL_APP` | `33` | Used for the python IP tunnel feature |
| `SERIAL_APP` | `64` | Provides a hardware serial interface to send and receive from the Meshtastic network. Connect to the RX/TX pins of a device with 38400 8N1. Packets received from the Meshtastic network is forwarded to the RX pin while sending a packet to TX will go out to the Mesh network. Maximum packet size of 240 bytes. Module is disabled by default can be turned on by setting SERIAL_MODULE_ENABLED = 1 in SerialPlugh.cpp. |
| `STORE_FORWARD_APP` | `65` | STORE_FORWARD_APP (Work in Progress) Maintained by Jm Casler (MC Hamster) : jm@casler.org |
| `RANGE_TEST_APP` | `66` | Optional port for messages for the range test module. |
| `TELEMETRY_APP` | `67` | Provides a format to send and receive telemetry data from the Meshtastic network. Maintained by Charles Crossan (crossan007) : crossan007@gmail.com |
| `ZPS_APP` | `68` | Experimental tools for estimating node position without a GPS Maintained by Github user a-f-G-U-C (a Meshtastic contributor) Project files at https://github.com/a-f-G-U-C/Meshtastic-ZPS |
| `SIMULATOR_APP` | `69` | Used to let multiple instances of Linux native applications communicate as if they did using their LoRa chip. Maintained by GitHub user GUVWAF. Project files at https://github.com/GUVWAF/Meshtasticator |
| `PRIVATE_APP` | `256` | Private applications should use portnums >= 256. To simplify initial development and testing you can use "PRIVATE_APP" in your code without needing to rebuild protobuf files (via [regen-protos.sh](https://github.com/meshtastic/firmware/blob/master/bin/regen-protos.sh)) |
| `ATAK_FORWARDER` | `257` | ATAK Forwarder Module https://github.com/paulmandal/atak-forwarder |
| `MAX` | `511` | Currently we limit port nums to no higher than this value |
## remote_hardware.proto
### HardwareMessage
:::note `message` description
An example app to show off the module system. This message is used for
REMOTE_HARDWARE_APP PortNums.
Also provides easy remote access to any GPIO.
In the future other remote hardware operations can be added based on user interest
(i.e. serial output, spi/i2c input/output).
FIXME - currently this feature is turned on by default which is dangerous
because no security yet (beyond the channel mechanism).
It should be off by default and then protected based on some TBD mechanism
(a special channel once multichannel support is included?)
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| type | [`HardwareMessage.Type`](#hardwaremessagetype) | What type of HardwareMessage is this? |
| gpio_mask | uint64 | What gpios are we changing. Not used for all MessageTypes, see MessageType for details |
| gpio_value | uint64 | For gpios that were listed in gpio_mask as valid, what are the signal levels for those gpios. Not used for all MessageTypes, see MessageType for details |
### HardwareMessage.Type
:::note `enum` description
TODO: REPLACE
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `UNSET` | `0` | Unset/unused |
| `WRITE_GPIOS` | `1` | Set gpio gpios based on gpio_mask/gpio_value |
| `WATCH_GPIOS` | `2` | We are now interested in watching the gpio_mask gpios. If the selected gpios change, please broadcast GPIOS_CHANGED. Will implicitly change the gpios requested to be INPUT gpios. |
| `GPIOS_CHANGED` | `3` | The gpios listed in gpio_mask have changed, the new values are listed in gpio_value |
| `READ_GPIOS` | `4` | Read the gpios specified in gpio_mask, send back a READ_GPIOS_REPLY reply with gpio_value populated |
| `READ_GPIOS_REPLY` | `5` | A reply to READ_GPIOS. gpio_mask and gpio_value will be populated |
| gas_resistance | float | Gas resistance in mOhm measured |
| voltage | float | Voltage measured |
| current | float | Current measured |
### Telemetry
:::note `message` description
Types of Measurements the telemetry module is equipped to handle
:::
| Field | Type | Description |
| ----- | ---- | ----------- |
| time | fixed32 | This is usually not sent over the mesh (to save space), but it is sent from the phone so that the local device can set its RTC If it is sent over the mesh (because there are devices on the mesh without GPS), it will only be sent by devices which has a hardware GPS clock (IE Mobile Phone). seconds since 1970 |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) variant.device_metrics | [`DeviceMetrics`](#devicemetrics) | Key native device metrics such as battery level |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) variant.environment_metrics | [`EnvironmentMetrics`](#environmentmetrics) | Weather station or other environmental metrics |
