mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-09-20 08:07:33 -07:00
a5c740f542
* Initial Update to Encryption Overview for 2.5 PKI Updates * Additional changes from @Jorropo comments. * Padding and some seperation of Pre/Post 2.5 changes for DM and Admin Control * Added a Encryption Technical Located Under Dev > Reference Material Seperate for the Encryption Overview * Minor edits * Integrity updates for post v2.5.0 * trunk fmt and add security section (moves needed ones too) * formatting technical page, change PKI to PKC. * move comments to its own sub-page * feedback, change PKI to PKC, formatting * DontMqttMeBro * Fix Grammar in Mqtt Page * oopsies * add android and web * test * more fixes --------- Co-authored-by: rcarteraz <robert.l.carter2@gmail.com>
186 lines
13 KiB
Plaintext
186 lines
13 KiB
Plaintext
---
|
|
id: device
|
|
title: Device Configuration
|
|
sidebar_label: Device
|
|
description: Learn about and compare device roles such as Client, Repeater, and Router as well as other Device settings.
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
The device config options are: Role, Serial Output, and Debug Log. Device config uses an admin message sending a `Config.Device` protobuf.
|
|
|
|
## Device Config Values
|
|
|
|
## Roles
|
|
|
|
| Device Role | Description | Best Uses |
|
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| CLIENT | App connected or stand alone messaging device. | General use for individuals needing to communicate over the Meshtastic network with support for client applications. |
|
|
| CLIENT_MUTE | Device that does not forward packets from other devices. | Situations where a device needs to participate in the network without assisting in packet routing, reducing network load. |
|
|
| CLIENT_HIDDEN | Device that only broadcasts as needed for stealth or power savings. | Use in stealth/hidden deployments or to reduce airtime/power consumption while still participating in the network. |
|
|
| TRACKER | Broadcasts GPS position packets as priority. | Tracking the location of individuals or assets, especially in scenarios where timely and efficient location updates are critical. |
|
|
| LOST_AND_FOUND | Broadcasts location as message to default channel regularly for to assist with device recovery. | Used for recovery efforts of a lost device. |
|
|
| SENSOR | Broadcasts telemetry packets as priority. | Deploying in scenarios where gathering environmental or other sensor data is crucial, with efficient power usage and frequent updates. |
|
|
| TAK | Optimized for ATAK system communication, reduces routine broadcasts. | Integration with ATAK systems (via the Meshtastic ATAK Plugin) for communication in tactical or coordinated operations. |
|
|
| TAK_TRACKER | Enables automatic TAK PLI broadcasts and reduces routine broadcasts. | Standalone PLI integration with ATAK systems for communication in tactical or coordinated operations. |
|
|
| REPEATER | Infrastructure node for extending network coverage by relaying messages with minimal overhead. Not visible in Nodes list. | Best positioned in strategic locations to maximize the network's overall coverage. Device is not shown in topology. |
|
|
| ROUTER | Infrastructure node for extending network coverage by relaying messages. Visible in Nodes list. | Best positioned in strategic locations to maximize the network's overall coverage. Device is shown in topology. |
|
|
|
|
:::tip
|
|
Still not sure which role to use? Check out the [role configuration tips](/docs/configuration/tips/#roles)
|
|
:::
|
|
|
|
Looking for ROUTER_CLIENT? This role was deprecated in firmware 2.3.15. Learn more in the [2.3.15 release notes](https://github.com/meshtastic/firmware/releases/tag/v2.3.15.deb7c27)
|
|
|
|
### Role Comparison
|
|
|
|
This table shows the **default** values after selecting a preset. As always, individual settings can be adjusted after choosing a preset.
|
|
|
|
| Device Role | BLE/WiFi/Serial | Screen Enabled | Power Consumption | Retransmit | Prioritized Routing | Visible in Nodes List |
|
|
| -------------- | --------------- | -------------- | ----------------- | -------------- | ------------------- | --------------------- |
|
|
| CLIENT | Yes | Yes | Regular | Yes | No | Yes |
|
|
| CLIENT_MUTE | Yes | Yes | Lowest | No | No | Yes |
|
|
| CLIENT_HIDDEN | Yes | Yes | Lowest | Local Only | No | No |
|
|
| TRACKER | Yes | No | Regular / Low | Awake Only[^1] | No | Yes |
|
|
| LOST_AND_FOUND | Yes | No | Regular | Yes | No | Yes |
|
|
| SENSOR | Yes | No | Regular / Low | Awake Only[^1] | No | Yes |
|
|
| TAK | Yes | Optional | Regular | Yes | No | Yes |
|
|
| TAK_TRACKER | Yes | Optional | Regular | Yes | No | Yes |
|
|
| ROUTER | No[^2] | No | High | Yes | Yes | Yes |
|
|
| REPEATER | Yes | No | High | Yes | Yes | No |
|
|
|
|
[^1]: **Awake Only** indicates retransmissions will occur normally but not while asleep between transmission intervals.
|
|
|
|
[^2]: The `ROUTER` role enables [Power Saving](/docs/configuration/radio/power/#power-saving) by default (ESP32 only). When needing to update a `ROUTER` via BLE, it's recommended you utilize an admin channel to temporarily change the role in order to update and then revert when done.
|
|
|
|
## Notes about Power Saving + Role behavior
|
|
|
|
### ESP32 Platform Only
|
|
|
|
Every role except for the `TRACKER` and `SENSOR` roles are capable of traditional _sleep_ behavior using the `power.is_power_saving` setting. When a node goes to sleep, in general, the serial console, peripherals, GPS, and WiFi/Bluetooth radio are all shut down to conserve power. The CPU will enter a low power state (light sleep or deep sleep on the ESP32). The LoRA radio will be left on stand-by for receiving any packets which will _wake up_ the device to resume services and respond.
|
|
|
|
Timeout configurations of `display.screen_on_secs` (Screen timeout), `power.min_wake_secs` (Minimum time till sleep), and `power.wait_bluetooth_secs` (Bluetooth timeout) will delay a node's transition to a sleep state. The timeouts and subsequent transition to sleep states may also be _reset_ by external events or actions such as receiving a packet, pressing a button, or connecting via client through serial or other means.
|
|
|
|
For the `ROUTER` role, the `power.is_power_saving` behavior of sleep is enabled automatically and cannot be turned off.
|
|
|
|
### ESP32 and NRF52 Platforms
|
|
|
|
In the `TRACKER` and `SENSOR` roles, there are special sleep behaviors when combined with `power.is_power_saving`. For `TRACKER`, the device will go to sleep for `position.position_broadcast_secs` and upon waking will send a position packet when the GPS provides a valid location and repeat the cycle. For `SENSOR`, the device will go to sleep for `telemetry.environment_update_interval` and upon waking will gather environment data and send a telemetry packet and repeat the cycle. For both of these roles, the LoRA radio does not remain in standby mode to accept packets and wake up the device. Sleep remains constrained to their respective transmission intervals.
|
|
|
|
## Rebroadcast Mode
|
|
|
|
This setting defines the device's behavior for how messages are rebroadcasted.
|
|
|
|
| Value | Description |
|
|
| :-----------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|
|
| `ALL` | ALL (Default) - This setting will rebroadcast ALL messages from its primary mesh as well as other meshes with the same modem settings, including when encryption settings differ. |
|
|
| `ALL_SKIP_DECODING` | ALL_SKIP_DECODING - Same as behavior as ALL, but skips packet decoding and simply rebroadcasts them. **Only available with Repeater role.** |
|
|
| `LOCAL_ONLY` | LOCAL_ONLY - Ignores observed messages from foreign meshes that are open or those which it cannot decrypt. Only rebroadcasts message on the nodes local primary / secondary channels. |
|
|
| `KNOWN_ONLY` | KNOWN_ONLY - Ignores observed messages from foreign meshes like LOCAL_ONLY, but takes it a step further by also ignoring messages from nodenums not in the node's known list (NodeDB). |
|
|
|
|
## TZDEF (Timezone Definition)
|
|
|
|
The `tzdef` setting allows the local offset to be defined for the device. It uses the TZ Database format to display the correct local time on the device display and in its logs.
|
|
|
|
To set the timezone, use the POSIX TZ Database string for the relevant region. Here is a list of [supported timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv). For example, if your region is `America/Los_Angeles`, you would input `PST8PDT,M3.2.0,M11.1.0` as the timezone.
|
|
|
|
## GPIO for user button
|
|
|
|
This is the GPIO pin number that will be used for the user button, if your device does not come with a predefined user button.
|
|
|
|
## GPIO for PWM Buzzer
|
|
|
|
This is the GPIO pin number that will be used for the PWM buzzer, if your device does not come with a predefined buzzer.
|
|
|
|
## Node Info Broadcast Seconds
|
|
|
|
This is the number of seconds between NodeInfo message (containing i.a. long and short name) broadcasts from the device. The device will still respond ad-hoc to NodeInfo messages when a response is wanted. When the device hears any packet from a node it doesn't know yet, it will send its NodeInfo and ask for a response automatically.
|
|
|
|
## Double Tap as Button Press
|
|
|
|
This option will enable a double tap, when a supported accelerometer is attached to the device, to be treated as a button press.
|
|
|
|
## Device Config Client Availability
|
|
|
|
<Tabs
|
|
groupId="settings"
|
|
defaultValue="apple"
|
|
values={[
|
|
{label: 'Android', value: 'android'},
|
|
{label: 'Apple', value: 'apple'},
|
|
{label: 'CLI', value: 'cli'},
|
|
{label: 'Web', value: 'web'},
|
|
]}>
|
|
<TabItem value="android">
|
|
|
|
#### Android
|
|
|
|
:::info
|
|
|
|
Device Config is available for Android.
|
|
|
|
1. Open the Meshtastic App
|
|
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Device**
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="apple">
|
|
|
|
#### Apple
|
|
|
|
:::info
|
|
All device config options other than NTP Server are available on iOS, iPadOS and macOS at Settings > Device Configuration > Device.
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="cli">
|
|
|
|
#### CLI
|
|
|
|
:::info
|
|
|
|
All device config options are available in the python CLI. Example commands are below:
|
|
|
|
:::
|
|
|
|
| Setting | Acceptable Values | Default |
|
|
| --------------------------------- | ------------------------------------------------------------------ | ----------------- |
|
|
| device.role | `CLIENT`, `CLIENT_MUTE`, `ROUTER`, `REPEATER`, `TRACKER`, `SENSOR` | `CLIENT` |
|
|
| device.rebroadcast_mode | `ALL`, `ALL_SKIP_DECODING`, `LOCAL_ONLY` | `ALL` |
|
|
| device.button_gpio | `0` - `34` | `0` |
|
|
| device.buzzer_gpio | `0` - `34` | `0` |
|
|
| device.node_info_broadcast_secs | `3600` - `UINT MAX` | `10800` (3 hours) |
|
|
| device.double_tap_as_button_press | `false`, `true` | `false` |
|
|
|
|
:::tip
|
|
|
|
Because the device will reboot after each command is sent via CLI, it is recommended when setting multiple values in a config section that commands be chained together as one.
|
|
|
|
```shell title="Example:"
|
|
meshtastic --set device.role CLIENT --set device.tzdef UTC0
|
|
```
|
|
|
|
:::
|
|
|
|
```shell title="Set the role to client"
|
|
meshtastic --set device.role CLIENT
|
|
```
|
|
|
|
```shell title="Set tzdef"
|
|
meshtastic --set device.tzdef UTC0
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="web">
|
|
|
|
#### Web
|
|
|
|
:::info
|
|
All device config options are available in the Web UI.
|
|
:::
|
|
|
|
</TabItem>
|
|
</Tabs>
|