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

Mode	Description	Use Case
DEFAULT	RawSame bytesas in/out,SIMPLE app-layer- messagesa raw (dumb) UART byte tunnel	Arduino/ESP32Generic integrationbyte bridging
SIMPLE	Newline-delimitedRaw byte UART tunnel (no framing); requires a channel named serial	Bridging arbitrary bytes between two nodes

TEXTMSGSends/receives strings as text in/outmessages on the default text channelSimple text message bridging PROTOProtobuf framingFullProgrammatic programmaticArduino/ESP32 integration / full access NMEAOutputs NMEA sentences from node GPSFeeding position to chartplotters CALTOPOCalTopo-compatible position formatSAR map integration

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.specific, Inand serial.baud takes an enum value (e.g. BAUD_9600, BAUD_115200), not a raw integer. SIMPLE mode,(and textDEFAULT) sentis a raw UART byte tunnel that requires a channel named serial - it does not broadcast to the default text channel. If you want serial port (terminated with newline) isinput broadcast as aordinary meshtext message;messages on the default channel (and received meshtext messages areprinted printedback out as <Short Name>: <text>), touse the serialTEXTMSG port.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}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 /{channel_name}c/ in place of /{packet_type}e/.)

Example: msh/US/2/e/LongFast/text!abcd1234 for textprotobuf messagespackets on the LongFast channel in the US region.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 Light SensorLighting Module

WhenThe 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 supported ambient light sensor and does not auto-adjust screen-backlight brightness. (Light-intensity sensors such as the BH1750, VEML7700, or TSL2591)TSL2591 isare connectedread viaby I2C,the Telemetry module, not by this module adjusts the screen backlight brightness automatically based on ambient light conditions - reducing battery drain in dark environments and ensuring readability in sunlight.module.)

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

AlsoUse worksambient_lighting.led_state with(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 hardwaredriver (NeoPixel/WS2812)e.g. the NCP5623 on the RAK14001); it is not documented to setdrive aaddressable statusNeoPixel/WS2812 color. current is the LED current in milliamps (for current-controlled LEDs). For the screen backlight use case, no explicit configuration is needed beyond enabling the module - brightness is automatically managed.strips.