Skip to main content
Version: 2.8

Serial Module Configuration

The serial module lets you talk to and control your Meshtastic device over a UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge. serial port. Set the mode to match your use-case — from plain text bridging to raw binary tunnels, NMEA output, and packet logging.

Serial console showing text messages bridged over the Meshtastic serial module

Serial Module Config Values

Enabled

Enables the serial module.

Echo

If set, any packets you send will be echoed back to your device. Useful for confirming transmissions in TEXTMSG mode.

Mode

Defaults to SIMPLE.

ModeDescription
DEFAULTAlias for SIMPLE.
SIMPLERaw binary pass-through. Bytes in are sent as a mesh packet on a channel named serial; received packets are written back as raw bytes.
PROTOExposes the Meshtastic Protobuf Client API on the serial port — the same protocol used by phone apps and the Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic.. Produces no human-readable output; use meshtastic --port <FTDI_PORT> --listen to observe the stream.
TEXTMSGAny string sent to the serial port is broadcast as a text message on the default channel. Received messages are printed as <ShortName>: <text>.
NMEAOutputs NMEA 0183 sentences every 2 seconds: one $GNGGA sentence for the device's own position, plus $GPWPL sentences for each mesh node with a valid position.
CALTOPOSends NMEA $GPWPL Waypoint sentences every 10 seconds for all nodes with valid positions, for use with CalTopo / SARTopo.
WS85Parses wind speed data from an Ecowitt WS85 connected over serial and transmits telemetry every 5 minutes. Requires hardware modification of the WS85.
VE_DIRECTReceives the VE.Direct protocol from Victron Energy products.
MS_CONFIGConfigures and views parameters of MeshSolar.
LOGOutputs a formatted log line for every packet sent or received by the node, including text, telemetry, and position packets.
LOGTEXTLogs only text packets (channel messages and direct messages) sent or received by the node.

Receive GPIO Pin

The GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. pin connected to the RXRX (Receive). The receiving of data over the radio link. line of your serial adapter.

tip

On the RAK4631 with the RAK19007 or some RAK19003 baseboards, use TXD1 (16) and RXD1 (15). Set GPS Mode to Not_Present for this combination. On other RAK19003 variants, use TXD0 (20) and RXD0 (19).

Transmit GPIO Pin

The GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. pin connected to the TXTX (Transmit). The transmitting of data over the radio link. line of your serial adapter. Always cross-connect: device TXTX (Transmit). The transmitting of data over the radio link. → adapter RXRX (Receive). The receiving of data over the radio link., and device RXRX (Receive). The receiving of data over the radio link. → adapter TXTX (Transmit). The transmitting of data over the radio link..

Baud Rate

The serial baud rate. BAUD_DEFAULT is 38400.

Timeout

How long the module waits after the last received byte before treating the accumulated data as a complete packet. Only relevant in SIMPLE mode. Default (0) corresponds to 250 ms.

Override Console Serial Port

When enabled, redirects the primary USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. serial port to serial module output instead of the debug console. Only valid with NMEA and CALTOPO modes — using it with any other mode will produce a configuration error and the module will not start. Has no effect if TXTX (Transmit). The transmitting of data over the radio link./RXRX (Receive). The receiving of data over the radio link. GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. pins are also configured (pogo-pin output takesTAK (Team Awareness Kit). A situational awareness ecosystem. Meshtastic bridges to it by converting mesh messages to and from Cursor on Target format. precedence).

Serial Module Config Client Availability

Apple

info

All serial module config options are available on iOS, iPadOS and macOS at Settings > Module Configuration > Serial.

SenseCAP T1000-E Serial Setup

The SenseCAP Card Tracker T1000-E is a credit-card-sized Meshtastic tracker running a Nordic nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption.. It supports the serial module via two connection methods.

Pogo Pin Connection (TEXTMSG, SIMPLE, LOG, LOGTEXT modes)

The T1000-E exposes its debug UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge. (Serial2) on the four pogo pins at the bottom edge of the device. Connect a USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial.-to-UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge. adapter (FTDI FT232, CP2102, CH340, or similar — 3.3 V logic level) using the following wiring:

T1000-E Pogo PinUSBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial.-UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge. Adapter
GNDGND
TXTX (Transmit). The transmitting of data over the radio link. (P0.16)RXRX (Receive). The receiving of data over the radio link.
RXRX (Receive). The receiving of data over the radio link. (P0.17)TXTX (Transmit). The transmitting of data over the radio link.
3V3(do not connect — device is self-powered)
tip

Use a 3.3 V logic-level adapter. A 5 V adapter will damage the nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption..

Once wired, configure the module using the T1000-E's USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. CDC port (the magnetic charging cable):

T1000-E TEXTMSG mode — one-shot config
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode TEXTMSG \
--set serial.baud BAUD_DEFAULT

After the device reboots, open the FTDI adapter port at 38400 8N1 to send and receive messages.

USB-Direct Connection (NMEA and CalTopo modes only)

For NMEA and CalTopo output modes, the T1000-E can stream data over its built-in USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. CDC port without any extra hardware:

T1000-E NMEA mode via USB
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.override_console_serial_port true \
--set serial.mode NMEA

After the device reboots, open the same USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. port at 38400 8N1 to receive NMEA sentences.

Finding Your Serial Port

USB CDC port (magnetic charging cable):

ls /dev/cu.usbmodem*
# Example output: /dev/cu.usbmodem0000001

FTDI / CP2102 pogo-pin adapter:

ls /dev/cu.usbserial-* /dev/cu.SLAB_USBtoUART 2>/dev/null
# Example output: /dev/cu.usbserial-A10KMFPL

Mode Examples

TEXTMSG — Send and Receive Text Messages

TEXTMSG mode bridges the serial port to the Meshtastic text message channel. Any string sent to the serial port is broadcast as a text message; any received text message is printed as <ShortName>: <message>.

Step 1 — Configure the T1000-E:

Configure TEXTMSG mode
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode TEXTMSG \
--set serial.baud BAUD_DEFAULT

Step 2 — Open the pogo-pin UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge. (<FTDI_PORT>) at 38400 8N1:

tio (recommended)
brew install tio
tio -b 38400 -e <FTDI_PORT>
screen (built-in)
screen <FTDI_PORT> 38400
# Exit with Ctrl-A, then k, then y

Step 3 — Type a message and press Enter. It is broadcast over the mesh. Incoming messages appear as:

CALLSIGN: Hello from the mesh!
tip

Enable echo to confirm your own transmissions: meshtastic --port <USB_PORT> --set serial.echo true


SIMPLE — Transparent UART Tunnel

SIMPLE mode is a raw binary pass-through. Bytes written to the serial port are sent as a mesh packet on a channel named serial; received packets on that channel are written as raw bytes back to the serial port.

note

A channel named serial must exist on the device. Create one with:

meshtastic --port <USB_PORT> --ch-add serial
Configure SIMPLE mode
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode SIMPLE \
--set serial.baud BAUD_DEFAULT \
--set serial.timeout 250

Connect at 38400 8N1 and send up to 237 bytes per packet. The module frames a packet by detecting a gap of serial.timeout milliseconds in the byte stream (default 250 ms).


PROTO — Protobuf Client API

PROTO mode exposes the full Meshtastic Protobuf Client API on the serial port — the same protocol used by phone apps and the Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic.. It produces no human-readable output.

Configure PROTO mode
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode PROTO
Listen to protobuf stream on FTDI port
meshtastic --port <FTDI_PORT> --listen

For embedded integration, use the Meshtastic Arduino client library.


NMEA — GPS Position Stream (USB or Pogo Pins)

NMEA mode outputs NMEA 0183 sentences every 2 seconds: a $GNGGA sentence for the device's own position, plus $GPWPL sentences for each mesh node with a valid position. Position is zero until the device acquires a GNSSGNSS (Global Navigation Satellite System). A multi-constellation satellite positioning receiver. Hardware listing GNSS support typically receives GPS, BeiDou, GLONASS and QZSS. fix.

Option A — USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. direct (recommended for T1000-E):

Configure NMEA mode via USB
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.override_console_serial_port true \
--set serial.mode NMEA \
--set serial.baud BAUD_DEFAULT

After the device reboots, open <USB_PORT> at 38400 8N1 to read the stream.

macOS — USB re-enumeration

On macOS with the T1000-E, after the device reboots into NMEA override mode the USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. CDC port (/dev/cu.usbmodem*) may drop and not automatically re-appear. If the port disappears, unplug and replug the magnetic charging cable and the port will re-enumerate. This is a known nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption. USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. CDC behavior.

Option B — Via pogo pins:

Configure NMEA mode via pogo pins
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode NMEA \
--set serial.baud BAUD_DEFAULT

Reading NMEA output:

tio -b 38400 <PORT>

Compatible with GPSBabel, OpenCPN, and any app that accepts a serial NMEA feed.


CALTOPO — Search and Rescue Mapping

CALTOPO mode sends NMEA $GPWPL Waypoint sentences every 10 seconds for all nodes in the mesh with a valid position. Designed for CalTopo / SARTopo to display mesh nodes on a rescue map in real time.

Configure CalTopo mode via USB
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.override_console_serial_port true \
--set serial.mode CALTOPO \
--set serial.baud BAUD_DEFAULT
macOS — USB re-enumeration

After applying this config the T1000-E reboots. On macOS the port may disappear — unplug and replug the magnetic charging cable to bring it back.

Open <USB_PORT> in CalTopo's GPSGPS (Global Positioning System). A satellite positioning system. A node with a GPS module determines its own location and can report that position to the mesh. input at 38400 8N1. Each node with a position appears as a waypoint, refreshed every 10 seconds.


LOG — Mesh Packet Activity Logger

LOG mode outputs a formatted log line for every packet the node sends or receives — text, telemetry, position, and more. Ideal for logging mesh activity to a data logger such as a SparkFun OpenLog connected to the T1000-E pogo pins.

Configure LOG mode
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode LOG \
--set serial.baud BAUD_DEFAULT
tip

If your CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. reports that LOG is not a valid enum value, use the numeric form instead: --set serial.mode 9. This occurs with CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. versions older than 2.7.10.

Open the FTDI port at 38400 8N1 to watch the stream. Example output:

[TX] TEXT ch=0 from=!deadbeef to=!ffffffff "Hello mesh!"
[RX] POSN ch=0 from=!cafebabe to=!ffffffff lat=47.6062 lon=-122.3321
[RX] TELE ch=0 from=!cafebabe bat=87% temp=22.3C

LOGTEXT — Text Message Logger

LOGTEXT mode logs only text packets (channel messages and direct messages) sent or received by the node.

Configure LOGTEXT mode
meshtastic --port <USB_PORT> \
--set serial.enabled true \
--set serial.txd 16 \
--set serial.rxd 17 \
--set serial.mode LOGTEXT \
--set serial.baud BAUD_DEFAULT
tip

If your CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. reports that LOGTEXT is not a valid enum value, use the numeric form instead: --set serial.mode 10. This occurs with CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. versions older than 2.7.10.

Output format: <ShortName>: <message>.


Python Scripting Examples

The Meshtastic Python package can configure and interact with the serial module programmatically:

pip install meshtastic

Configure Serial Module via Python

configure_serial.py
import meshtastic
import meshtastic.serial_interface

iface = meshtastic.serial_interface.SerialInterface(devPath="<USB_PORT>")

iface.localNode.moduleConfig.serial.enabled = True
iface.localNode.moduleConfig.serial.txd = 16
iface.localNode.moduleConfig.serial.rxd = 17
iface.localNode.moduleConfig.serial.mode = 3
iface.localNode.moduleConfig.serial.baud = 0

iface.localNode.writeConfig("serial")
print("Serial module configured. Device will reboot.")
iface.close()

Send a Text Message via Serial (TEXTMSG mode)

send_via_serial.py
import serial
import time

with serial.Serial("<FTDI_PORT>", baudrate=38400, timeout=1) as ser:
message = "Hello from serial module!\n"
ser.write(message.encode("ascii"))
print(f"Sent: {message.strip()}")
time.sleep(0.5)

Receive Text Messages via Serial (TEXTMSG mode)

receive_via_serial.py
import serial

with serial.Serial("<FTDI_PORT>", baudrate=38400, timeout=5) as ser:
print("Listening for mesh messages... (Ctrl-C to stop)")
while True:
line = ser.readline().decode("ascii", errors="replace").strip()
if line:
print(f"Received: {line}")

Read NMEA Stream and Parse Positions

read_nmea.py
import serial

with serial.Serial("<PORT>", baudrate=38400, timeout=2) as ser:
print("Reading NMEA sentences... (Ctrl-C to stop)")
while True:
line = ser.readline().decode("ascii", errors="replace").strip()
if line.startswith("$GN") or line.startswith("$GP"):
print(line)

Device GPIO Pin Reference

warning

Incorrect GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. configuration can physically damage your hardware. Verify the schematic for your specific device before wiring anything up.

DeviceArchitectureSerial Module TXDSerial Module RXDNotes
SenseCAP T1000-EnRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption.16 (P0.16)17 (P0.17)Pogo-pin debug UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge.
T-Beam v1.1ESP32ESP32A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than nRF52, but often cheaper and supports Wi-Fi if desired.1535GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. header
T-Beam v1.1 (recommended)ESP32ESP32A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than nRF52, but often cheaper and supports Wi-Fi if desired.1413Alternative GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. header
RAK4631 (RAK19007)nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption.16 (TXD1)15 (RXD1)Set GPSGPS (Global Positioning System). A satellite positioning system. A node with a GPS module determines its own location and can report that position to the mesh. Mode to Not_Present
RAK4631 (RAK19003 v2)nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption.20 (TXD0)19 (RXD0)

Interfacing PIR Sensor With External Microcontroller

The following examples connect a Raspberry Pi Pico or Arduino Mini Pro to a PIR motion sensor. When motion is detected, the microcontroller sends a message over serial and the device broadcasts it as a text message using TEXTMSG mode.

T1000-E Configuration

  • Serial module enabled, mode: TEXTMSG
  • GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. Pins: TXD 16, RXD 17 (pogo-pin UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge.)
  • Baud: 38400

Raspberry Pi Pico BOM

Raspberry Pi Pico Wiring

Wiring diagram: PIR sensor connected to a Raspberry Pi Pico for the serial module

For T1000-E (pogo-pin UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge.):

  • TXTX (Transmit). The transmitting of data over the radio link. pogo pin (P0.16) → RXRX (Receive). The receiving of data over the radio link. (GP1) on the Pico
  • RXRX (Receive). The receiving of data over the radio link. pogo pin (P0.17) → TXTX (Transmit). The transmitting of data over the radio link. (GP0) on the Pico
  • GND pogo pin → GND pin 38 on the Pico

For T-Beam V1.1 (GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. header):

  • TXTX (Transmit). The transmitting of data over the radio link. pin 14 on the T-Beam → RXRX (Receive). The receiving of data over the radio link. pin 2 on the Pico
  • RXRX (Receive). The receiving of data over the radio link. pin 13 on the T-Beam → TXTX (Transmit). The transmitting of data over the radio link. pin 1 on the Pico
  • GND pin on T-Beam → GND pin 38 on the Pico

PIR sensor connections (both boards):

  • PIR Vcc → Pico 3V3 (pin 36)
  • PIR GND → Pico GND (pin 38)
  • PIR trigger → Pico GPIO28 (pin 34)

CircuitPython Code

pir_to_mesh.py
import time
import board
import busio
import digitalio

pir = digitalio.DigitalInOut(board.GP28)
pir.direction = digitalio.Direction.INPUT

uart = busio.UART(board.GP0, board.GP1, baudrate=38400, timeout=0)

while True:
if pir.value:
uart.write(bytes("Motion Detected\n", "ascii"))
time.sleep(30)
time.sleep(0.5)

Arduino Mini Pro BOM

  • An Arduino Pro Mini 3.3V/8MHz variant (required for T1000-E — 5V variant outputs 5V on TXTX (Transmit). The transmitting of data over the radio link. which will damage the nRF52840nRF52840A Nordic microcontroller from the nRF52 family, used in devices such as the RAK WisBlock core modules. Provides Bluetooth LE 5.0 and very low power consumption. pogo pins)
  • SenseCAP T1000-E (or T-Beam V1.1) running Meshtastic
  • PIR Sensor (Adafruit Breadboard Model)

Arduino Mini Pro Wiring

Wiring diagram: PIR sensor connected to an Arduino Pro Mini for the serial module

For T1000-E (pogo-pin UARTUART (Universal Asynchronous Receiver-Transmitter). A serial interface used to communicate with a device over its pins or through a USB-to-serial bridge.):

  • TXTX (Transmit). The transmitting of data over the radio link. pogo pin (P0.16) → RXRX (Receive). The receiving of data over the radio link. pin on the Arduino Mini Pro
  • RXRX (Receive). The receiving of data over the radio link. pogo pin (P0.17) → TXTX (Transmit). The transmitting of data over the radio link. pin on the Arduino Mini Pro
  • GND pogo pin → GND on the Arduino Mini Pro

For T-Beam V1.1 (GPIOGPIO (General Purpose Input/Output). An uncommitted digital signal pin on a device. header):

  • T-Beam RXRX (Receive). The receiving of data over the radio link. (pin 13) → TXTX (Transmit). The transmitting of data over the radio link. on the Arduino Mini Pro
  • T-Beam TXTX (Transmit). The transmitting of data over the radio link. (pin 14) → RXRX (Receive). The receiving of data over the radio link. on the Arduino Mini Pro
  • T-Beam 3.3V → 3.3V on the Arduino Mini Pro
  • T-Beam GND → GND on the Arduino Mini Pro

PIR sensor connections (both boards):

  • Arduino Mini Pro pin 2 → PIR OUT
  • PIR Vcc → 3.3V rail
  • PIR GND → GND rail

Arduino Sketch

pir_to_mesh.ino
const int PIR_PIN = 2;
unsigned long lastTrigger = 0;
const unsigned long DEBOUNCE_MS = 30000;

void setup() {
Serial.begin(38400);
pinMode(PIR_PIN, INPUT);
}

void loop() {
if (digitalRead(PIR_PIN) == HIGH) {
unsigned long now = millis();
if (now - lastTrigger > DEBOUNCE_MS) {
lastTrigger = now;
Serial.println("Motion Detected");
}
}
delay(500);
}