mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-15 18:14:19 -08:00
209 lines
9.7 KiB
Plaintext
209 lines
9.7 KiB
Plaintext
---
|
|
id: position
|
|
title: Position Configuration
|
|
sidebar_label: Position
|
|
description: GPS position configuration settings for your Meshtastic device including update intervals, broadcast settings, and GPIO.
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
Position data from GPS is provided by either the radio or your paired phone. It is not required to use Meshtastic, but time calculations require at least one device on the mesh to have either a GPS, RTC, or internet connection for NTP.
|
|
|
|
The position config uses an admin message to send a `Config.Position` protobuf. The position config options are: GPS Mode, GPS Update Interval, Fixed Position, Smart Broadcast, Smart Broadcast Minimum Distance, Smart Broadcast Minimum Interval, Broadcast Interval, Position Packet Flags, and GPS RX/TX Pins.
|
|
|
|
## Position Config Values
|
|
|
|
### GPS Mode
|
|
|
|
Configures whether the GPS functionality is enabled, disabled, or not present on the node.
|
|
|
|
Acceptable values: `Disabled`, `Enabled`, and `Not_Present`.
|
|
|
|
Generally, depending on the device and its configuration, this value will default to either `Enabled` or `Not Present`.
|
|
|
|
### GPS Update Interval
|
|
|
|
How often we should try to get GPS position (in seconds), or zero for the default of once every 2 minutes, or a very large value (maxint) to update only once at boot.
|
|
|
|
### Fixed Position
|
|
|
|
Acceptable values: `true` or `false`
|
|
|
|
False by default
|
|
|
|
If set, this node is at a fixed position. The device will generate GPS updates at the regular GPS update interval, but use whatever the last lat/lon/alt it saved for the node. The lat/lon/alt can be set by an internal GPS or with the help of the mobile device's GPS.
|
|
|
|
### Smart Broadcast
|
|
|
|
Acceptable values: `true` or `false`
|
|
|
|
True by default
|
|
|
|
Smart broadcast will send out your position at an increased frequency only if your location has changed enough for a position update to be useful.
|
|
|
|
Smart broadcast complements broadcast interval (doesn't override that setting) but will apply an algorithm to more frequently update your mesh network if you are in motion and then throttle it down when you are standing still. If you use this feature, it's best to leave broadcast interval at the default.
|
|
|
|
Smart broadcast will calculate an ideal position update interval based on the data rate of your selected channel configuration.
|
|
|
|
### Smart Broadcast Minimum Distance
|
|
|
|
Default of `0` is 100 meters
|
|
|
|
The minimum distance in meters traveled (since the last send) before we can send a position to the mesh if smart broadcast is enabled.
|
|
|
|
### Smart Broadcast Minimum Interval
|
|
|
|
Default of `0` is 30 seconds
|
|
|
|
The minimum number of seconds (since the last send) before we can send a position to the mesh if smart broadcast is enabled.
|
|
|
|
### Broadcast Interval
|
|
|
|
Default of `0` is 15 minutes
|
|
|
|
If smart broadcast is off we should send our position this often.
|
|
|
|
The GPS updates will be sent out every broadcast interval, either with the actual GPS location or an empty location if no GPS fix was achieved.
|
|
|
|
### Position Flags
|
|
|
|
Defines which options are sent in POSITION messages. Values are stored as a bit field of boolean configuration options (bitwise OR of PositionFlags).
|
|
|
|
| Value | Description |
|
|
| :----------------: | :--------------------------------------------------------------: |
|
|
| UNSET | Required for compilation |
|
|
| ALTITUDE | Include an altitude value (if available) |
|
|
| ALTITUDE_MSL | Altitude value is MSL |
|
|
| GEOIDAL_SEPARATION | Include geoidal separation |
|
|
| DOP | Include the DOP value ; PDOP used by default, see below |
|
|
| HVDOP | If POS_DOP set, send separate HDOP / VDOP values instead of PDOP |
|
|
| SATINVIEW | Include number of "satellites in view" |
|
|
| SEQ_NO | Include a sequence number incremented per packet |
|
|
| TIMESTAMP | Include positional timestamp (from GPS solution) |
|
|
| HEADING | Include positional heading (from GPS solution) |
|
|
| SPEED | Include positional speed (from GPS solution) |
|
|
|
|
### GPIO RX/TX for GPS Module
|
|
|
|
If your device does not have a fixed GPS chip, you can define the GPIO pins for the RX and TX pins of a GPS module.
|
|
|
|
## Position 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
|
|
|
|
Position Config options are available for Android.
|
|
|
|
1. Open the Meshtastic App
|
|
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Position**
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="apple">
|
|
|
|
#### Apple
|
|
|
|
:::info
|
|
All position config values are available on iOS, iPadOS and macOS at Settings > Device Configuration > Position.
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="cli">
|
|
|
|
#### CLI
|
|
|
|
:::info
|
|
|
|
All Position config commands are available in the python CLI. Example commands are below:
|
|
|
|
:::
|
|
|
|
| Setting | Acceptable Values | Default |
|
|
| :------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------: |
|
|
| position.gps_mode | `enabled`, `disabled`, `not_present` | `Enabled` or `Not Present` |
|
|
| position.gps_update_interval | `integer` (seconds) | Default `0` is 2 Minutes |
|
|
| position.fixed_position | `true`, `false` | `false` |
|
|
| position.position_broadcast_smart_enabled | `true`, `false` | `true` |
|
|
| position.broadcast_smart_minimum_distance | `integer` (meters) | Default of `0` is 100 Meters |
|
|
|position.broadcast_smart_minimum_interval_secs| `integer` (seconds) | Default of `0` is 15 Minutes |
|
|
| position.position_broadcast_secs | `integer` (seconds) | Default of `0` is 15 minutes |
|
|
| position.flags | `UNSET`, `ALTITUDE`, `ALTITUDE_MSL`, `GEOIDAL_SEPARATION`, `DOP`, `HVDOP`, `PDOP`, `SATINVIEW`, `SEQ_NO`, `TIMESTAMP`, `HEADING`, `SPEED` | `UNSET` |
|
|
| position.rx_gpio | `integer` (0-39) | `UNSET` |
|
|
| position.tx_gpio | `integer` (0-34) | `UNSET` |
|
|
|
|
:::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. **This is especially important for position values to ensure they are set at the same time and avoid being overwritten by subsequent commands.**
|
|
|
|
```shell title="Example:"
|
|
meshtastic --set position.fixed_position true --setlat 37.8651 --setlon -119.5383
|
|
```
|
|
|
|
:::
|
|
|
|
```shell title="Set GPS update interval (Default of 0 is 2 Minutes)"
|
|
meshtastic --set position.gps_update_interval 0
|
|
meshtastic --set position.gps_update_interval 45
|
|
```
|
|
|
|
```shell title="Set Fixed Position - Current Location"
|
|
meshtastic --set position.fixed_position true
|
|
```
|
|
|
|
:::note
|
|
The device will continue to acquire GPS coordinates according to the `gps_update_interval`, but will use the last saved coordinates as its fixed point.
|
|
:::
|
|
|
|
```shell title="Set and Enable Fixed Position - User Defined"
|
|
meshtastic --setlat 37.8651 --setlon -119.5383
|
|
```
|
|
|
|
```shell title="Remove and Unset Fixed Position"
|
|
meshtastic --remove-position
|
|
```
|
|
|
|
```shell title="Enable / Disable Smart position broadcast (Enabled by default)"
|
|
meshtastic --set position.position_broadcast_smart_enabled true
|
|
meshtastic --set position.position_broadcast_smart_enabled false
|
|
```
|
|
|
|
```shell title="Set Position Broadcast Interval (Default of 0 is 15 minutes)"
|
|
meshtastic --set position.broadcast_secs 0
|
|
meshtastic --set position.broadcast_secs 60
|
|
```
|
|
|
|
:::note
|
|
It may take some time to see that the change has taken effect. The GPS location is updated according to the value specified on `gps_update_interval` and the mesh will be notified of the new position in relation to the `position_broadcast_secs` value.
|
|
:::
|
|
|
|
```shell title="Set / Unset Position Flags"
|
|
meshtastic --pos-fields ALTITUDE ALTITUDE_MSL
|
|
meshtastic --pos-fields UNSET
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="web">
|
|
|
|
#### Web
|
|
|
|
:::info
|
|
All position config options are available in the Web UI.
|
|
:::
|
|
|
|
</TabItem>
|
|
</Tabs>
|