meshtastic/docs/configuration/radio/device.mdx

182 lines
12 KiB
Plaintext
Raw Normal View History

2022-06-24 19:40:15 -07:00
---
id: device
title: Device Configuration
sidebar_label: Device
---
2023-01-19 05:01:57 -08:00
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
2022-06-24 19:40:15 -07:00
2023-01-19 05:01:57 -08:00
The device config options are: Role, Serial Output, and Debug Log. Device config uses an admin message sending a `Config.Device` protobuf.
2022-06-24 19:40:15 -07:00
## 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. |
2024-02-19 08:48:16 -08:00
| TAK | Optimized for ATAK system communication, reduces routine broadcasts. | Integration with ATAK systems (via the Mesthastic 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. |
| ROUTER_CLIENT | Combination of both ROUTER and CLIENT. Not for mobile devices. | Devices in a strategic position for priority routing that need to also serve as a standard CLIENT. |
2023-01-30 08:32:18 -08:00
2024-02-04 18:15:41 -08:00
#### 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 | No | No | Yes |
| LOST_AND_FOUND | Yes | No | Regular | No | No | Yes |
| SENSOR | Yes | No | High | No | No | Yes |
| TAK | Yes | Optional | Regular | Yes | No | Yes |
| TAK_TRACKER | Yes | Optional | Regular | Yes | No | Yes |
| ROUTER | No<sup>1</sup> | No | High | Yes | Yes | Yes |
| ROUTER_CLIENT | Yes | Yes | Highest | Yes | Yes | Yes |
| REPEATER | Yes | No | High | Yes | Yes | No |
##### Citations
1. Caution: The Router role enables [Power Saving](/docs/configuration/radio/power/#power-saving) by default. Consider ROUTER_CLIENT if BLE/WiFi/Serial are still needed.
2024-02-04 18:15:41 -08:00
2023-01-30 08:32:18 -08:00
### Rebroadcast Mode
2023-04-26 11:51:20 -07:00
This setting defines the device's behavior for how messages are rebroadcasted.
2023-01-30 08:32:18 -08:00
2023-12-17 08:31:14 -08:00
| 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). |
2022-06-24 19:40:15 -07:00
2023-01-19 05:01:57 -08:00
### Serial Console
2022-06-24 19:40:15 -07:00
Acceptable values: `true` or `false`
Disabling this will disable the SerialConsole by not initializing the StreamAPI.
2022-06-24 19:40:15 -07:00
### Debug Log
2023-01-19 05:01:57 -08:00
2022-06-24 19:40:15 -07:00
Acceptable values: `true` or `false`
By default we turn off logging as soon as an API client connects. Set this to true to leave the debug log outputting even when API is active.
2022-06-24 19:40:15 -07:00
### 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.
2023-02-11 17:59:58 -08:00
### 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.
2023-02-11 17:59:58 -08:00
2023-05-09 11:31:11 -07:00
### 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.
### Managed Mode
Enabling Managed mode will restrict access to all radio configurations via client applications. Radio configurations will only be accessible through the Admin channel. To avoid being locked out, make sure the Admin channel is working properly before enabling it.
2022-06-24 19:40:15 -07:00
## Device Config Client Availability
<Tabs
groupId="settings"
defaultValue="apple"
2022-06-24 19:40:15 -07:00
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
2022-06-29 22:33:26 -07:00
{label: 'CLI', value: 'cli'},
2022-06-24 19:40:15 -07:00
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
2024-02-22 13:09:26 -08:00
#### Android
2022-06-24 19:40:15 -07:00
:::info
2022-12-04 13:01:17 -08:00
2022-12-04 12:59:56 -08:00
Device Config is available for Android.
1. Open the Meshtastic App
2023-06-17 22:06:11 -07:00
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Device**
2022-12-04 12:59:56 -08:00
2022-06-24 19:40:15 -07:00
:::
</TabItem>
<TabItem value="apple">
2024-02-22 13:09:26 -08:00
#### Apple
2022-06-24 19:40:15 -07:00
:::info
All device config options other than NTP Server are available on iOS, iPadOS and macOS at Settings > Radio Configuration > Device.
:::
</TabItem>
<TabItem value="cli">
2024-02-22 13:09:26 -08:00
#### CLI
:::info
2022-08-03 08:14:18 -07:00
All device config options are available in the python CLI. Example commands are below:
2022-06-24 19:40:15 -07:00
:::
2023-05-09 11:31:11 -07:00
| Setting | Acceptable Values | Default |
| --------------------------------- | ----------------------------------------------------------------------------------- | ----------------- |
| device.debug_log_enabled | `true`, `false` | `false` |
| device.role | `CLIENT`, `CLIENT_MUTE`, `ROUTER`, `ROUTER_CLIENT`, `REPEATER`, `TRACKER`, `SENSOR` | `CLIENT` |
| device.rebroadcast_mode | `ALL`, `ALL_SKIP_DECODING`, `LOCAL_ONLY` | `ALL` |
| device.serial_enabled | `true`, `false` | `true` |
| device.button_gpio | `0` - `34` | `0` |
| device.buzzer_gpio | `0` - `34` | `0` |
| device.node_info_broadcast_secs | `0` - `UINT MAX` | `10800` (3 hours) |
| device.double_tap_as_button_press | `false`, `true` | `false` |
| device.is_managed | `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.debug_log_enabled true
```
:::
2022-06-24 19:40:15 -07:00
```shell title="Set the role to client"
meshtastic --set device.role CLIENT
2022-06-24 19:40:15 -07:00
```
```shell title="Disable serial console"
2022-09-22 15:41:16 -07:00
meshtastic --set device.serial_enabled false
2022-06-24 19:40:15 -07:00
```
```shell title="Enable debug logging"
meshtastic --set device.debug_log_enabled true
2022-06-24 19:40:15 -07:00
```
</TabItem>
<TabItem value="web">
2022-06-24 19:40:15 -07:00
2024-02-22 13:09:26 -08:00
#### Web
2022-06-24 19:40:15 -07:00
:::info
All device config options are available in the Web UI.
2022-06-24 19:40:15 -07:00
:::
2023-01-19 05:01:57 -08:00
2024-02-22 13:09:26 -08:00
</TabItem>
</Tabs>