# 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

<table id="bkmrk-modedescriptionuse-c"><thead><tr><th>Mode</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>DEFAULT</td><td>Same as SIMPLE - a raw (dumb) UART byte tunnel</td><td>Generic byte bridging</td></tr><tr><td>SIMPLE</td><td>Raw byte UART tunnel (no framing); requires a channel named `serial`</td><td>Bridging arbitrary bytes between two nodes</td></tr><tr><td>TEXTMSG</td><td>Sends/receives strings as text messages on the default text channel</td><td>Simple text message bridging</td></tr><tr><td>PROTO</td><td>Protobuf framing</td><td>Programmatic Arduino/ESP32 integration / full access</td></tr><tr><td>NMEA</td><td>Outputs NMEA sentences from node GPS</td><td>Feeding position to chartplotters</td></tr><tr><td>CALTOPO</td><td>CalTopo-compatible position format</td><td>SAR map integration</td></tr></tbody></table>

### 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.