Serial, MQTT, and Ambient Light Modules

Serial Module

The Serial module lets external hardware send and receive Meshtastic messages over a UART serial connection - enabling integration with microcontrollers, GPS units, custom sensors, and computer software.

Modes of Operation

Configuration

meshtastic --set serial.enabled true
meshtastic --set serial.mode SIMPLE
meshtastic --set serial.rxd 16
meshtastic --set serial.txd 17
meshtastic --set serial.baud BAUD_9600

RXD/TXD pin numbers are board-specific, and serial.baud takes an enum value (e.g. BAUD_9600, BAUD_115200), not a raw integer. SIMPLE (and DEFAULT) is a raw UART byte tunnel that requires a channel named serial - it does not broadcast to the default text channel. If you want serial input broadcast as ordinary text messages on the default channel (and received text messages printed back out as <Short Name>: <text>), use the TEXTMSG mode instead.

MQTT Module

The MQTT module directly connects a Meshtastic node to an MQTT broker (internet required), enabling cloud integration without a separate gateway computer.

Warning: uplinking to the public broker mqtt.meshtastic.org (with the shared meshdev credentials) publishes your default-channel traffic and node positions to the public internet - readable by anyone and shown on third-party maps such as meshmap.net. Meshtastic also publishes to MQTT unencrypted by default, even on a channel with a PSK, unless you set mqtt.encryption_enabled true. If you do not intend that public exposure, use a private broker and enable encryption.

meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address "mqtt.meshtastic.org"
meshtastic --set mqtt.username "meshdev"
meshtastic --set mqtt.password "large4cats"
meshtastic --set mqtt.root "msh"
meshtastic --set mqtt.uplink_enabled true
meshtastic --set mqtt.downlink_enabled false

uplink_enabled sends local mesh packets to the broker. downlink_enabled receives packets from the broker and re-broadcasts locally - useful for extending the mesh over the internet but can cause feedback loops if misconfigured. Start with downlink disabled until you understand the topology.

Topic Structure

Meshtastic publishes to: msh/REGION/2/e/CHANNELNAME/USERID for raw protobuf packets, or msh/REGION/2/json/CHANNELNAME/USERID when JSON output is enabled. The 2/e (or 2/json) segment is the protocol-version/encoding marker, and the final segment is the gateway node's USERID. There is no per-packet-type topic level - the packet type is a field inside the JSON payload, not a topic segment. (Firmware before 2.3.0 used /c/ in place of /e/.)

Example: msh/US/2/e/LongFast/!abcd1234 for protobuf packets on the LongFast channel in the US region (or msh/US/2/json/LongFast/!abcd1234 when JSON is enabled). Subscribe with wildcards: msh/US/# to receive all traffic from US nodes.

Ambient Lighting Module

The Ambient Lighting module controls an onboard I2C RGB LED controller (the NCP5623, as used on the RAK14001), letting you set the LED on/off state, its drive current, and the red/green/blue levels. It is not a light sensor and does not auto-adjust screen-backlight brightness. (Light-intensity sensors such as the BH1750, VEML7700, or TSL2591 are read by the Telemetry module, not by this module.)

meshtastic --set ambient_lighting.led_state 1
meshtastic --set ambient_lighting.current 10

Use ambient_lighting.led_state (1 to enable, 0 to disable), ambient_lighting.current for the LED output drive, and the red/green/blue fields for color. This module targets an I2C RGB LED driver (e.g. the NCP5623 on the RAK14001); it is not documented to drive addressable NeoPixel/WS2812 strips.