# Meshtastic Configuration Reference Comprehensive reference for all settings under Config > Device, Config > Position, and Config > Network in the Meshtastic firmware. # Device Configuration Settings The Device configuration section (**Config > Device**) controls fundamental node behavior: its role in the network, how it handles rebroadcasting, node info broadcasts, and administrative access. These are the most impactful settings for network performance and should be understood before deploying any node. Access these settings in the [Meshtastic app](https://wiki.meshamerica.com/books/hardware-guide/page/meshtastic-app) under **Settings > Radio Configuration > Device**, via the web interface at `http:///config`, or through the Python CLI with `meshtastic --set device.*`. --- ## Role **Config key:** `device.role` **Default:** `CLIENT` The Role setting is the single most important Device configuration choice. It tells the firmware how this node should behave in the mesh - specifically, how aggressively it should rebroadcast packets, whether it should send periodic node info, and how it prioritizes battery life versus network contribution. ### Available Roles #### CLIENT The standard role for personal devices carried by users. CLIENT nodes: - Participate normally in mesh routing (rebroadcast packets they receive) - Send NodeInfo broadcasts on the configured interval - Receive and send messages on all subscribed channels - Display in other nodes' neighbor lists **Use when:** You are deploying a personal handheld node, a node you carry daily, or any general-purpose device. #### CLIENT\_MUTE Identical to CLIENT but with packet rebroadcasting disabled. A CLIENT\_MUTE node does not relay other nodes' packets (no routing-layer rebroadcast), but it still sends and receives its own messages. **Use when:** You have many devices in close proximity (e.g., all members of a team within radio range of each other). Adding non-muted CLIENT nodes in a dense cluster creates redundant rebroadcasts that waste airtime. Making most of them CLIENT\_MUTE reduces channel utilization while maintaining full message delivery to those devices. **Also useful for:** Devices behind NAT or VPN tunnels acting as monitoring receivers; test devices you don't want to affect mesh traffic. #### ROUTER Designed for fixed infrastructure nodes at high elevation or central locations. ROUTER nodes: - Rebroadcast packets with the highest priority - Use a longer NodeInfo broadcast interval to reduce overhead traffic - Are favored in routing decisions - the mesh prefers to route through ROUTER nodes - Disable the screen and reduce radio/BLE activity by default to save power (ROUTER enables Power Saving automatically on ESP32) **Use when:** Deploying a node on a rooftop, tower, hilltop, or any other fixed elevated location whose primary job is to relay traffic for other nodes. ROUTERs form the backbone of a community mesh. **Important:** Only set ROUTER on nodes that will genuinely be at good RF locations. A ROUTER with poor antenna placement will be preferred for routing but perform poorly, degrading the network. It's better to use CLIENT on a node that isn't actually a good relay point. #### ROUTER\_CLIENT (removed) ROUTER\_CLIENT was a hybrid role that combined ROUTER routing behavior with CLIENT-level NodeInfo and message participation. This role was deprecated and removed in firmware 2.3.15 and is no longer a selectable role in current firmware. **What to use instead:** For a home node that both relays traffic and receives your own messages, use `CLIENT` (which performs smart rebroadcasting via managed flooding) or `ROUTER_LATE`. For a node that is purely infrastructure, use `ROUTER`. #### REPEATER The most minimal infrastructure role. **Note:** REPEATER is deprecated as of firmware 2.7.11; for new infrastructure deployments prefer `ROUTER` (or `ROUTER_LATE`). REPEATER nodes: - Rebroadcast received packets once with prioritized timing similar to ROUTER, with minimal overhead - Do NOT send NodeInfo broadcasts - they are intentionally invisible in the node list - Do NOT participate in messaging - they cannot send or receive application-layer messages - Consume minimal airtime overhead **Use when:** Deploying a relay-only node in a gap in coverage where you only need packet forwarding and don't need the node to participate in messaging or appear in the network map. REPEATER nodes are ideal for embedded or remotely deployed relays with no user interaction. **Caution:** Because REPEATER nodes don't send NodeInfo, they won't appear on your map or in your node list. This makes it harder to verify they are online. Plan for out-of-band monitoring (serial console, MQTT telemetry, physical LED) if using REPEATER in unattended deployments. #### TRACKER Optimized for asset and vehicle tracking use cases. TRACKER nodes: - Send frequent position updates automatically - Are optimized to conserve bandwidth by only broadcasting position data (they reduce other overhead) - Prioritize position packets. Smart position broadcast (transmit when moving, reduce rate when stationary) is configured via the position settings (`position.position_broadcast_smart_enabled` and related fields) and applies regardless of role **Use when:** Attaching a node to a vehicle, pet, person, or asset for location tracking. The TRACKER role signals to the firmware and other nodes that this device's primary purpose is position reporting. #### TAK Designed for interoperability with TAK (Team Awareness Kit) - tactical situational awareness software used by military, law enforcement, SAR teams, and emergency management. TAK role nodes: - Format outgoing position packets in a way compatible with TAK server ingestion - Enable TAK-specific extensions in the Meshtastic packet format - Work alongside ATAK (Android TAK) and WinTAK clients **Use when:** Integrating Meshtastic into a TAK-based operational picture. Requires TAK server infrastructure or ATAK-capable devices on the network. Not useful for general community mesh deployments. #### SENSOR Optimized for sensor nodes that transmit telemetry data (temperature, humidity, air quality, power levels, etc.) rather than user messages. SENSOR nodes: - Still participate in routing messages for other devices, but prioritize sending their own telemetry data; they can reduce routing/airtime and sleep between readings when `power.is_power_saving` is enabled - May sleep between sensor readings - Reduce rebroadcast activity to conserve battery (retransmit while awake only) **Use when:** Deploying a battery-powered environmental sensor, weather station, or power monitor. The node's primary job is to report readings, not to relay traffic. #### LOST\_AND\_FOUND A specialized tracker role for lost-item finders (similar in concept to Apple AirTags or Tile trackers but on the Meshtastic mesh). Lost\_And\_Found nodes: - Broadcast their location as a message to the default channel regularly to assist with device recovery - Are designed for small form-factor nodes attached to items (bags, bikes, pets) - The lost node broadcasts its own location to the default channel; anyone in range receives it and can use it to recover the device **Use when:** Building a lost-item tracker on Meshtastic hardware. Not suitable for primary communication or infrastructure roles. **Note on role availability:** The exact set of selectable roles (and their spelling) depends on your firmware version. Current roles include CLIENT, CLIENT\_MUTE, CLIENT\_HIDDEN, ROUTER, ROUTER\_LATE, REPEATER (deprecated), TRACKER, SENSOR, TAK, TAK\_TRACKER, and LOST\_AND\_FOUND. If a role above does not appear in your app's role dropdown, update to current firmware. --- ## Serial Console Enabled **Config key:** `security.serial_enabled` (this setting lives under the `security.*` namespace, not `device.*`) **Default:** `true` Controls whether the firmware exposes a serial console on the USB/UART port. When enabled, you can connect to the node via USB serial (commonly at 115200 baud) and interact with the device (view logs, run CLI commands). Disabling this prevents the Serial Console from initializing the Stream API. **Disable when:** Deploying a node in an environment where unauthorized USB access is a concern, or to reduce power consumption marginally in deeply embedded deployments. Most users should leave this enabled - it is the primary recovery mechanism if you lose network access to the node. **Warning:** If you disable Serial Console and also lose WiFi/Bluetooth access to the node, recovery may require a full firmware reflash. --- ## Debug Log Enabled **Config key:** `security.debug_log_api_enabled` (under the `security.*` namespace) **Default:** `false` When enabled, the firmware outputs verbose debug messages to the serial console. These messages include detailed information about packet processing, routing decisions, radio layer events, and subsystem state changes. **Enable when:** Troubleshooting connectivity issues, investigating unexpected behavior, or developing integrations. Debug logging produces a high volume of output that can make normal serial console use harder to read. **Disable in production:** Debug logging adds slight CPU overhead and can fill serial buffers. Leave disabled on deployed infrastructure nodes unless actively troubleshooting. --- ## Rebroadcast Mode **Config key:** `device.rebroadcast_mode` **Default:** `ALL` Controls which received packets this node will rebroadcast (relay) to other nodes. This setting interacts with the Role setting - Role determines the priority and frequency of rebroadcasting; Rebroadcast Mode determines what gets rebroadcast at all. ### ALL The default mode. This node rebroadcasts all received packets that pass the hop limit and deduplication filters, regardless of source or content. This is the correct mode for most nodes. ### ALL\_SKIP\_DECODING The node rebroadcasts all packets but skips attempting to decode their payload. This mode is primarily useful for REPEATER-role nodes where you want maximum rebroadcast speed and don't need the node to process message content. Slightly reduces CPU overhead per packet. **Use when:** Operating a dedicated relay node where content processing is unnecessary and you want to minimize latency and CPU load. ### LOCAL\_ONLY The node ignores observed messages from foreign meshes that are open or that it cannot decrypt, and only rebroadcasts traffic on its own local primary/secondary channels. LOCAL\_ONLY filters by local channel membership / decryptability - it does *not* filter by hop count. **Use when:** You share RF space with neighboring meshes on the same modem preset and want to avoid relaying traffic from foreign meshes you are not part of. LOCAL\_ONLY restricts rebroadcasting to your own configured channels. ### KNOWN\_ONLY The node only rebroadcasts packets from nodes that appear in its local node database (nodes it has seen NodeInfo from). Unknown nodes - those that have never sent a NodeInfo the local node has received - are not relayed. **Use when:** Running a private or semi-private mesh where you want to restrict relay behavior to known network members. This can reduce relay of stray packets from neighboring networks that share the same channel. --- ## Node Info Broadcast Interval **Config key:** `device.node_info_broadcast_secs` **Default:** `10800` seconds (3 hours). This default is the same for all roles - it is not role-dependent. How often (in seconds) the node broadcasts a NodeInfo packet - the announcement that includes the node's name, hardware model, and public key. NodeInfo packets allow other nodes to know you exist and update their neighbor lists. **Lower values:** More frequent announcements - nodes see each other more quickly after joining the network, and the map updates faster. Costs more airtime. **Higher values:** Less frequent announcements - reduces channel utilization overhead, especially important on busy networks. As user-tunable guidance, fixed infrastructure nodes can keep the default or longer intervals (up to UINT MAX) since their presence is stable; the firmware default is 10800 s for all roles. **Minimum:** 3600 seconds (1 hour). The firmware enforces 3600 s as the minimum accepted value; lower values such as 300 s are not permitted and will be rejected or clamped. --- ## Double-Tap as Button **Config key:** `device.double_tap_as_button_press` **Default:** `false` On devices with an accelerometer (such as the RAK WisBlock with RAK1904 accelerometer module), enabling this option allows a physical double-tap on the device to simulate a button press. Useful for waking a device from sleep or triggering notifications on nodes that don't have physical buttons. **Enable when:** Using a device in a case without easy access to physical buttons, or when you want tap-to-wake functionality. Requires compatible hardware with an accelerometer. --- ## Managed Mode **Config key:** `security.is_managed` (boolean; set via `meshtastic --set security.is_managed true`). Managed Mode lives under the `security.*` namespace - it is not a `device.role` value and not `device.is_managed`. **Default:** `false` When Managed Mode is enabled, client applications are blocked from writing configuration to the radio locally (configurations may still be read). Once enabled, radio configurations can only be changed through PKC Remote Admin messages on firmware 2.5+ or the legacy Admin channel on firmware prior to 2.5. This is a security feature for remotely deployed infrastructure nodes. **Enable when:** Deploying a ROUTER node (or other infrastructure node) that should be centrally managed and protected from unauthorized local modification. For example, a rooftop node that community members can physically access - Managed Mode prevents casual configuration changes. **Warning:** Enabling Managed Mode without first verifying you can administer the node remotely (via PKC Remote Admin on firmware 2.5+, or a configured legacy admin channel on older firmware) will lock you out of local configuration. Managed Mode blocks config writes over all local interfaces, including USB/serial. Confirm remote admin works before enabling this. --- ## Admin Channel (Legacy) and Remote Admin **Config key:** `security.admin_channel_enabled` (boolean, default `false` / disabled). This enables the insecure legacy admin channel. The older integer `admin_channel_index` field is deprecated. **Modern remote admin:** `security.admin_key` (PKC Remote Admin keys) On current firmware (2.5+), administrative access is normally provided by PKC Remote Admin: you authorize one or more public keys via `security.admin_key`, and only messages signed by those keys are accepted for administrative control. The legacy admin channel - enabled by the boolean `security.admin_channel_enabled` - is the older mechanism, where admin messages are protected only by a channel PSK. Admin messages can change device configuration, reboot the node, and perform other privileged operations. If you must use the legacy admin channel, configure a dedicated secondary channel with its own strong PSK so administrative messages are kept separate from user traffic. For example: - Channel 0: public mesh channel (LongFast or community key) - Channel 1: private admin channel (strong PSK known only to node operators) - Enable `security.admin_channel_enabled` With this legacy setup, only operators with the channel 1 PSK can remotely reconfigure the node, while anyone on channel 0 can use the mesh normally. Note that the default public channel's PSK (`AQ==`) is publicly known, so never rely on channel 0 for admin. **Best practice for infrastructure nodes:** Prefer PKC Remote Admin (`security.admin_key`) on firmware 2.5+ for separating and authenticating admin traffic. If you use the legacy admin channel, always give it a dedicated strong PSK. Never leave admin access on the default public channel in a production deployment. # Position Configuration Settings The Position configuration section (**Config > 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 > Position** (Android) or **Settings > Device Configuration > 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 --setlon ` (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 > Position > "Set to current location" or enter coordinates manually (Android); Settings > Device Configuration > 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:**
Use CaseRecommended IntervalRationale
Vehicle tracker (active event)60 - 120 secondsFrequent updates needed for real-time tracking
Hiking/walking node120 - 300 secondsBalance between track fidelity and airtime
Fixed CLIENT node900 - 1800 secondsPosition doesn't change; reduce overhead
Fixed ROUTER/infrastructure3600 - 10800 secondsMinimal overhead for stable fixed nodes
**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`.
FlagData AddedUse When
ALTITUDEInclude an altitude value (if available)Mountainous terrain, aviation, 3D positioning
ALTITUDE\_MSLInterpret the altitude value as height above mean sea level (vs ellipsoid); a modifier on ALTITUDE, not a separate fieldWhen sea-level altitude is specifically needed
GEOIDAL\_SEPARATIONDifference between WGS84 ellipsoid and geoidPrecision surveying; not needed for most uses
DOPDilution of Precision (accuracy estimate)When position accuracy qualification is important
HVDOPWhen DOP is enabled, send separate HDOP and VDOP instead of a single PDOPPrecision tracking applications
SATINVIEWNumber of GPS satellites in viewDiagnostics, signal quality assessment
SEQ\_NOSequence number (incremented per packet)When multiple position sources must be ordered
TIMESTAMPTimestamp of the GPS fixWhen time-of-fix (vs time-of-transmission) matters
HEADINGCourse over ground in degreesVehicle and vessel tracking, direction of travel
SPEEDSpeed over groundVehicle tracking, activity analysis
*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.*
GPS ModeApproximate Current Draw (estimate)Use When
Continuous (always on)30 - 50 mA continuousReal-time tracking where every second matters
Duty-cycle (120s interval)2 - 8 mA averageStandard mobile node
Duty-cycle (600s interval)0.5 - 2 mA averageLow-power mobile node
DISABLED (fixed position)0 mA for GPSFixed infrastructure nodes
# Network Configuration Settings The Network configuration section (**Config > Network**) controls how ESP32-based Meshtastic nodes connect to IP networks - WiFi and Ethernet - and associated services like NTP and remote logging. These settings are only relevant for ESP32 hardware; nRF52-based boards (like the RAK4631) do not support WiFi natively and these settings have no effect on them, with the exception of Ethernet on RAK builds fitted with a RAK13800 module. Access these settings in the [Meshtastic app](https://wiki.meshamerica.com/books/hardware-guide/page/meshtastic-app) under **Settings > Radio Configuration > Network**, or via the Python CLI with `meshtastic --set network.*`. **Note:** Network connectivity unlocks important Meshtastic features: the web interface, MQTT gateway, APRS bridging, NTP time synchronization, and remote syslog. If you are using ESP32-based hardware (T-Beam, T-Lora, Heltec WiFi LoRa, Station G2, etc.), understanding these settings is important for gateway and infrastructure deployments. --- ## WiFi SSID **Config key:** `network.wifi_ssid` **Default:** Empty (WiFi disabled) The SSID (network name) of the WiFi network the node should connect to as a client. Case-sensitive. Maximum 32 characters. **To enable WiFi:** Set both WiFi SSID and WiFi Password. The node will attempt to join the network on boot and reconnect if the connection drops. **Important considerations:** - Enabling WiFi disables Bluetooth - only one connection method works at a time on ESP32 devices. Enabling WiFi also increases power consumption noticeably compared to running LoRa with Bluetooth only. - A node with WiFi enabled and a good internet connection can serve as an MQTT gateway, APRS-IS gateway, and NTP time source for the mesh - On battery-powered mobile nodes, WiFi should generally be disabled to preserve battery life. Enable WiFi on mains-powered infrastructure nodes. --- ## WiFi Password **Config key:** `network.wifi_psk` **Default:** Empty The passphrase for the WiFi network specified by WiFi SSID (max 64 characters). Stored in the device's flash memory. Supports open networks (leave password empty if the network has no password, though this is strongly discouraged for security reasons). **Security note:** The WiFi password is stored in plaintext in the device's NVS (Non-Volatile Storage) flash partition. Anyone with physical access to the device and a serial connection can potentially extract it. Do not configure a node with your primary home WiFi password on a device that could be physically compromised; consider using a dedicated IoT VLAN or guest network. --- ## WiFi Mode ESP32-based Meshtastic nodes connect to WiFi in **client (station / STA) mode only**. The firmware does **not** support SoftAP (Access Point) mode - there is no setting to make the node create its own WiFi access point, and there is no `network.wifi_mode` config key. WiFi is controlled simply by whether a WiFi SSID and password are set. In client mode the node connects to an existing WiFi network as a client (station). This is the standard mode for gateway nodes that need internet access. In client mode, the node: - Obtains an IP address via DHCP (or a configured static IP) - Can reach the internet for MQTT, NTP, APRS-IS, and other services - Is accessible on the local network at its assigned IP address - Serves the Meshtastic web client at `http:///` (or via the mDNS alias `http://meshtastic.local/`) **No phone-direct AP option:** Because SoftAP mode is not supported, you cannot connect a phone or laptop directly to the node's own WiFi. For field configuration without an existing WiFi network, use Bluetooth or a USB serial connection instead. --- ## Ethernet Enabled **Config key:** `network.eth_enabled` **Default:** `false` Enables the Ethernet interface on hardware that supports it. The documented Ethernet reference hardware is the **RAK4631 paired with the RAK13800 Ethernet module** (a W5500-class SPI Ethernet controller). Note that JSON MQTT output is not supported on the nRF52 platform. **Advantages of Ethernet over WiFi for infrastructure nodes:** - More reliable and stable connection - no RF interference, no re-association delays - Lower and more consistent latency - Generally lower and steadier power consumption than active WiFi - No PSK to manage or expose **Use when:** Deploying a fixed infrastructure node (ROUTER or gateway) at a location with Ethernet infrastructure - server room, communications closet, network rack. Ethernet-connected gateway nodes are more reliable than WiFi-connected ones for long-term unattended operation. --- ## NTP Server **Config key:** `network.ntp_server` **Default:** `meshtastic.pool.ntp.org` The hostname or IP address of the NTP (Network Time Protocol) server the node uses to synchronize its real-time clock when IP networking is available. Accurate time is important for: - Correct message timestamps displayed in the app - Log entries with accurate timestamps for troubleshooting - MQTT message timestamps - Coordinating time-dependent operations across the mesh Meshtastic nodes without internet connectivity rely on time received from other nodes on the mesh (nodes share time information in packets). An NTP-synced node improves its own clock accuracy; that time can then propagate to other nodes via the normal packet exchange, but the firmware docs do not promise that a single NTP node becomes an authoritative time source for the entire mesh. ### Recommended NTP Servers
ServerDescriptionUse When
`meshtastic.pool.ntp.org`Default NTP pool used by the firmwareGeneral use, internet-connected nodes
`time.cloudflare.com`Cloudflare NTP (anycast, fast)Reliable alternative with good global coverage
`time.google.com`Google Public NTPReliable alternative
`time.nist.gov`NIST time serverWhen US government standard time is needed
`192.168.x.x` (local)Your own local NTP serverIsolated networks, high-accuracy requirements, no internet
**Local NTP server:** If your deployment has a local NTP server (common in enterprise and government networks, and in some emergency operations centers), set this to that server's address. This reduces internet dependency and may improve synchronization accuracy. **NTP without internet:** If the node has no internet access but is on a local network with a router that provides NTP (most home routers do), using the router's IP address as the NTP server works well: `192.168.1.1` or similar. --- ## rsyslog Server **Config key:** `network.rsyslog_server` **Default:** Empty (disabled) Configures remote syslog logging. When set to a hostname or IP address (with optional port, e.g., `192.168.1.100:514`), the node sends its log output to a remote syslog server over UDP using the standard syslog protocol (RFC 3164/5424). **Why use remote logging:** - Centralized log collection from multiple nodes - see all infrastructure logs in one place - Persistent log storage - node logs that would otherwise be lost on reboot are captured on the server - Real-time alerting - syslog servers can trigger alerts on specific log messages (errors, reconnections, etc.) - Troubleshooting unattended nodes - diagnose issues without physically connecting a serial cable **Setup requirements:** - A syslog server running on the local network (rsyslog, syslog-ng, Graylog, or any standard syslog receiver) - The node and syslog server must be on the same network (or routable to each other) - UDP port 514 is the IANA standard and conventional default syslog port, but the port is configurable per the docs **Recommended syslog servers for small deployments:** - **rsyslog** on Linux (Raspberry Pi, server): Simple, lightweight, standard - **Graylog**: Full log management with search and dashboards - good for larger deployments - **Loki + Grafana**: Modern log aggregation with excellent visualization **Example rsyslog configuration** to receive Meshtastic logs on a Linux server: ``` # /etc/rsyslog.d/meshtastic.conf module(load="imudp") input(type="imudp" port="514") # Save Meshtastic logs to a dedicated file if $fromhost-ip == '192.168.1.50' then /var/log/meshtastic/node1.log ``` --- ## Practical Configuration Guidance ### Standard Home Gateway Node For a mains-powered T-Beam or Station G2 acting as a gateway and router at home: - WiFi SSID: your home network SSID (or use IoT VLAN if available) - WiFi Password: your network password - NTP Server: `meshtastic.pool.ntp.org` (default is fine) - rsyslog Server: empty unless you have a log server ### Field Deployment - No Internet For a node deployed at an event or emergency operation without internet access: - Leave WiFi SSID empty - there is no AP mode, so configure the node over Bluetooth or USB serial instead - NTP Server: empty or your EOC's local network NTP if available - Time will sync from other mesh nodes that have NTP access ### Ethernet-Connected Infrastructure For a fixed ROUTER node on a rack or network closet: - Ethernet Enabled: true - WiFi: disabled (leave SSID empty) - NTP Server: your organization's NTP server or `time.cloudflare.com` - rsyslog Server: your organization's syslog collector - Managed Mode: true (set via `security.is_managed true`, with admin keys configured) ### Local Web Access When the node is connected to your WiFi or Ethernet network, you can reach the Meshtastic web client in a browser: - Open `http:///`, or the mDNS alias `http://meshtastic.local/` - The node serves the web client over its API (port 4403); this is the web client, not a separate self-hosted admin site - For configuration when no network is available, use Bluetooth or a USB serial connection