# Position Configuration Settings

The Position configuration section (**Config &gt; Position**) controls how your node acquires, reports, and manages GPS and location data. Getting position configuration right affects mesh map accuracy, battery life, and channel airtime - particularly important for mobile nodes and large networks.

Access these settings in the [Meshtastic app](https://wiki.meshamerica.com/books/hardware-guide/page/meshtastic-app) under **Settings &gt; Position** (Android) or **Settings &gt; Device Configuration &gt; Position** (Apple), or via the Python CLI with `meshtastic --set position.*`.

---

## GPS Mode

**Config key:** `position.gps_mode`  
**Default:** `ENABLED` or `NOT_PRESENT` depending on the device/variant (ENABLED on devices with GPS hardware)

Controls the GPS receiver's operating state. This is a top-level switch that determines whether GPS hardware is used at all. Note: `position.gps_mode` (an enum) is the current control and replaced the legacy `position.gps_enabled` boolean.

### ENABLED

The GPS receiver is active and continuously seeks satellite fixes. The node uses live GPS data for position reporting. This is the default for devices with GPS hardware (e.g., T-Beam, WisBlock with RAK1910/RAK12500 GPS module).

### DISABLED

GPS is disabled. The node will use a fixed position if one has been set (see Fixed Position below), or will report no position if no fixed position is configured. Disabling GPS when you don't need real-time position significantly reduces power consumption.

**Use when:** The node is permanently fixed and its position is set manually via Fixed Position. A rooftop ROUTER node, for example, has no reason to run its GPS continuously - set a fixed position once and disable GPS to save power.

### NOT\_PRESENT

Informs the firmware that no GPS hardware is present on this device. This prevents the firmware from attempting to initialize GPS hardware that doesn't exist, which can cause startup delays and error log noise. Set this on devices without any GPS module (e.g., a bare ESP32 LoRa board without GPS, or a RAK4631 with no GPS WisBlock attached).

---

## Fixed Position

**Config key:** Set via app "Set Fixed Position" action or CLI `meshtastic --setlat <lat> --setlon <lon>` (altitude is set via the Python API `setFixedPosition(alt=...)` or the app, not a CLI flag)  
**Default:** Not set

A manually entered GPS coordinate that the node broadcasts as its position instead of (or in addition to, depending on GPS Mode) GPS-derived coordinates. Fixed position is stored in non-volatile memory and persists across reboots.

**Use cases:**

- Fixed infrastructure nodes (rooftop ROUTER, indoor gateway) - set their exact location once, disable GPS
- Devices without GPS hardware - allow them to appear on the map at a known location
- Privacy-conscious users who want to broadcast an approximate location rather than precise GPS coordinates

**Privacy note:** Any position the node broadcasts - fixed or live, precise or coarse - is published to the channel and, on any channel that is uplinked to MQTT, to the public internet (and third-party maps such as meshmap.net). An "approximate" fixed position is still exposed. For truly sensitive sites, disable position entirely (GPS Mode DISABLED with no fixed position set) rather than relying on a coarse fixed point.

**Setting a fixed position:**

- In the Meshtastic app: Settings &gt; Position &gt; "Set to current location" or enter coordinates manually (Android); Settings &gt; Device Configuration &gt; Position on Apple
- Via CLI: `meshtastic --setlat 37.7749 --setlon -122.4194` (there is no `--setalt` flag; set altitude via the app or Python API)
- Via Python API: `iface.localNode.setFixedPosition(lat=37.7749, lon=-122.4194, alt=15)`

**To clear a fixed position:** Use `meshtastic --remove-position` in the CLI.

---

## Position Broadcast SMART Enabled

**Config key:** `position.position_broadcast_smart_enabled`  
**Default:** `true`

Smart position broadcasting adapts broadcast frequency based on movement. When enabled, the node transmits position updates more frequently when moving and less frequently when stationary. This significantly reduces channel airtime for mobile nodes compared to fixed-interval broadcasting.

**How smart beaconing works:**

1. If the node has moved more than the configured Minimum Distance since the last broadcast (and the Smart Broadcast Minimum Interval has elapsed), a position broadcast is triggered
2. If the node has not moved, it waits up to the configured Broadcast Interval before broadcasting
3. Speed is factored in: faster movement triggers more frequent updates

**Enable for:** Any mobile node (vehicle tracker, handheld carried by a walking/driving user). Smart beaconing is almost always beneficial for mobile nodes.

**Consider disabling for:** Fixed infrastructure nodes with a set position - they should broadcast at a fixed, low-frequency interval (see Broadcast SECS below) rather than smart beaconing, which adds minor computational overhead.

---

## Broadcast SECS (Position Broadcast Interval)

**Config key:** `position.position_broadcast_secs`  
**Default:** `0` (interpreted as 900 seconds / 15 minutes)

The maximum interval in seconds between position broadcasts. When Smart Beaconing is enabled, this is the upper bound - the node will not go longer than this interval without broadcasting, even if stationary. When Smart Beaconing is disabled, this is the fixed broadcast interval.

**Guidance by use case:**

<table id="bkmrk-use-caserecommended-"> <thead> <tr><th>Use Case</th><th>Recommended Interval</th><th>Rationale</th></tr> </thead> <tbody> <tr><td>Vehicle tracker (active event)</td><td>60 - 120 seconds</td><td>Frequent updates needed for real-time tracking</td></tr> <tr><td>Hiking/walking node</td><td>120 - 300 seconds</td><td>Balance between track fidelity and airtime</td></tr> <tr><td>Fixed CLIENT node</td><td>900 - 1800 seconds</td><td>Position doesn't change; reduce overhead</td></tr> <tr><td>Fixed ROUTER/infrastructure</td><td>3600 - 10800 seconds</td><td>Minimal overhead for stable fixed nodes</td></tr> </tbody></table>

**Channel utilization impact:** Position packets are among the longer Meshtastic packets. On a busy network with many nodes, unnecessarily frequent position broadcasts are a significant source of channel congestion. Always use the longest interval consistent with your tracking needs.

---

## Smart Minimum Distance

**Config key:** `position.broadcast_smart_minimum_distance`  
**Default:** `0` (interpreted as 100 meters)

When Smart Position Broadcasting is enabled, this is the minimum distance (in meters) the node must travel from its last broadcast location before a new position broadcast is triggered by movement. If the node moves less than this distance, the movement does not by itself trigger a new broadcast.

**Tuning guidance:**

- **Walking/hiking:** 50 - 100 meters - captures meaningful position changes at walking speed
- **Vehicle tracking:** 100 - 500 meters - avoids rapid-fire updates at slow speeds (parking lots, traffic)
- **Emergency/rescue:** 25 - 50 meters - fine-grained position updates for close-range coordination

---

## GPS Update Interval

**Config key:** `position.gps_update_interval`  
**Default:** `0` (interpreted as 120 seconds / 2 minutes)

How often (in seconds) the firmware polls the GPS module for a new position fix. This is distinct from the broadcast interval - the GPS may update frequently internally while position broadcasts happen less often.

A shorter GPS update interval means the firmware always has a more current fix available when it decides to broadcast. A longer interval reduces GPS power consumption (the GPS receiver is one of the most power-hungry components on nodes like the T-Beam).

**Recommended values:**

- Active mobile use: 30 - 60 seconds
- Occasional position checks: 120 - 300 seconds
- Mostly stationary: 600 - 1800 seconds (or disable GPS and use fixed position)

---

## Position Flags

**Config key:** `position.flags`  
**Default:** `UNSET`

Position flags are a bitmask that controls which optional data fields are included in position packets. Each additional field adds bytes to the packet, increasing airtime. Choose only the flags relevant to your use case. On the CLI these are set with `meshtastic --pos-fields ALTITUDE ALTITUDE_MSL ...` (a space-separated list of flag names), not via `--set position.flags`.

<table id="bkmrk-flagdata-addedpacket"> <thead> <tr><th>Flag</th><th>Data Added</th><th>Use When</th></tr> </thead> <tbody> <tr><td>ALTITUDE</td><td>Include an altitude value (if available)</td><td>Mountainous terrain, aviation, 3D positioning</td></tr> <tr><td>ALTITUDE\_MSL</td><td>Interpret the altitude value as height above mean sea level (vs ellipsoid); a modifier on ALTITUDE, not a separate field</td><td>When sea-level altitude is specifically needed</td></tr> <tr><td>GEOIDAL\_SEPARATION</td><td>Difference between WGS84 ellipsoid and geoid</td><td>Precision surveying; not needed for most uses</td></tr> <tr><td>DOP</td><td>Dilution of Precision (accuracy estimate)</td><td>When position accuracy qualification is important</td></tr> <tr><td>HVDOP</td><td>When DOP is enabled, send separate HDOP and VDOP instead of a single PDOP</td><td>Precision tracking applications</td></tr> <tr><td>SATINVIEW</td><td>Number of GPS satellites in view</td><td>Diagnostics, signal quality assessment</td></tr> <tr><td>SEQ\_NO</td><td>Sequence number (incremented per packet)</td><td>When multiple position sources must be ordered</td></tr> <tr><td>TIMESTAMP</td><td>Timestamp of the GPS fix</td><td>When time-of-fix (vs time-of-transmission) matters</td></tr> <tr><td>HEADING</td><td>Course over ground in degrees</td><td>Vehicle and vessel tracking, direction of travel</td></tr> <tr><td>SPEED</td><td>Speed over ground</td><td>Vehicle tracking, activity analysis</td></tr> </tbody></table>

*Note:* The exact byte cost, units, and field encoding of each flag are defined in the firmware `mesh.proto` Position definition; consult it (or the firmware protobuf) before relying on per-flag size estimates. Enabling more flags increases packet size and airtime.

**Minimal position packet (lat/lon only):** Omit all optional flags. Suitable for fixed nodes or simple presence-only tracking.

**Full vehicle tracking:** Enable Altitude, DOP, Heading, Speed. Gives a complete picture without the rarely useful fields.

**Airtime consciousness:** On the default LongFast channel (250 kHz bandwidth, ~1.07 kbps effective data rate), each position packet with all flags enabled may be 40+ bytes longer than a minimal packet, translating to measurably more on-air time per broadcast.

---

## GPS Fix Acquisition Timeout

**Config key:** Handled internally by the firmware - there is no separate `position.gps_attempt_time` CLI config key.  
**Default:** Determined by the firmware

In power-save GPS mode the firmware will attempt to acquire a GPS fix for a bounded period before giving up and putting the GPS to sleep until the next update cycle. This timeout is managed internally by the firmware; it is not exposed as a user-settable `position.gps_attempt_time` value. If the GPS acquires a fix before the internal timeout, it sleeps early; if it cannot get a fix, it stops trying until the next GPS update interval.

**In open sky environments:** A fix is typically acquired within 30 - 60 seconds, so the internal fix-attempt window is rarely a limiting factor.

**In challenging environments** (indoors, urban canyons, dense tree cover): GPS may struggle to get a fix. To save power in places where a fix is unlikely, increase the GPS Update Interval (so the GPS wakes less often) or disable GPS and use a fixed position.

---

## GPS Power Management (Power Saving)

**Config key:** GPS power management is handled automatically based on GPS Mode and the GPS Update Interval - there is no separate `position.gps_power_mode` key.  
**Default:** Automatic

On battery-powered nodes, GPS is one of the largest power consumers. A typical GPS receiver draws on the order of 20 - 50 mA when actively tracking, versus roughly 2 - 5 mA for the LoRa transceiver in sleep (figures vary by module; consult your GPS module datasheet and the SX126x/SX127x datasheet for exact values). Several strategies minimize GPS power draw:

### Duty-Cycle GPS (Recommended for Mobile Nodes)

The GPS receiver powers on only when a new fix is needed (based on GPS Update Interval), acquires a fix, then powers down. Between updates, the GPS is completely off. This can dramatically reduce GPS-related power consumption compared to continuous operation - the longer the update interval, the larger the saving.

Meshtastic duty-cycles the GPS automatically based on the GPS Update Interval: larger intervals mean the GPS sleeps for longer between fixes. Set a longer GPS Update Interval to reduce GPS polling and power draw.

### Fixed Position + GPS Disabled (Best for Fixed Nodes)

The most power-efficient approach for fixed nodes: enter the position manually once, set GPS Mode to DISABLED. The GPS receiver is never powered, eliminating all GPS power consumption entirely.

### GPS NOT\_PRESENT (For Devices Without GPS)

On boards without GPS hardware, setting GPS Mode to NOT\_PRESENT prevents any attempt to initialize GPS, eliminating initialization delay and preventing power being applied to a non-existent module.

### Practical Power Impact

*The figures below are rough estimates derived from common GPS-module active currents and duty-cycle math (active current x on-time / period); actual draw depends on your specific module and time-to-first-fix. Treat them as ballpark, not measured Meshtastic values.*

<table id="bkmrk-gps-modeapproximate-"> <thead> <tr><th>GPS Mode</th><th>Approximate Current Draw (estimate)</th><th>Use When</th></tr> </thead> <tbody> <tr><td>Continuous (always on)</td><td>30 - 50 mA continuous</td><td>Real-time tracking where every second matters</td></tr> <tr><td>Duty-cycle (120s interval)</td><td>2 - 8 mA average</td><td>Standard mobile node</td></tr> <tr><td>Duty-cycle (600s interval)</td><td>0.5 - 2 mA average</td><td>Low-power mobile node</td></tr> <tr><td>DISABLED (fixed position)</td><td>0 mA for GPS</td><td>Fixed infrastructure nodes</td></tr> </tbody></table>