RaftSerialConsoleSysMod

SerialConsole SysMod

Built-in SysMod that exposes the REST API over the console port - a UART, or the USB-Serial-JTAG port when that is the console (CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG). Lets a developer type API requests directly into the serial console and receive JSON responses, while simultaneously carrying a binary protocol channel (RICSerial / RICJSON) for tool-driven access.

Source: RaftSysMods/components/SerialConsole/

What it provides

• ASCII command entry: type subscription?topic=devjson&rateHz=10 + Enter.
• Binary channel multiplexed on the same UART using ProtocolOverAscii (MSB-set bytes carry framed binary; MSB-clear bytes are user input).
• Registers a Comms Channel so the binary side participates fully in the channel system.
• XON/XOFF flow control hint via getXonXoff().

SysType configuration

{
    "name": "SerialConsole",
    "enable": 1,
    "uartNum": 0,
    "baudRate": 115200,
    "rxBuf": 1024,
    "txBuf": 4096,
    "crlfOnTx": 1,
    "protocol": "RICSerial"
}

Key	Default	Meaning
enable	false	Master switch
uartNum	0	ESP32 UART number
baudRate	115200	Baud rate
rxBuf / txBuf	1024 / 4096	UART driver buffer sizes
crlfOnTx	true	Send CRLF on tx line endings
protocol	"RICSerial"	Protocol codec attached to the binary side

REST endpoints exposed

Endpoint	Method	Purpose
console	GET	Console control (e.g. show registered endpoints)

JSON commands (receiveCmdJSON)

Sent from another SysMod with getSysManager()->sendCmdJSON("SerialConsole", ...):

Command	Effect
{"cmd":"releasePort"}	Stop reading from and writing to the port (console input, replies, and the binary channel - sendMsg returns false) until reclaimed. The driver stays installed.
{"cmd":"reclaimPort"}	Resume normal operation.
{"cmd":"set","baudRate":n,"txBuf":n,"rxBuf":n}	UART consoles only: change baud rate or driver buffer sizes.

Releasing the port

releasePort is for an owner that needs the console's port as a clean byte pipe for a while - the RaftROS serial link uses it on USB-Serial-JTAG. It only stops SerialConsole itself; other console output (Raft and ESP-IDF logging, printf, ROM printf) is silenced by RaftConsolePort, which the owner claims at the same time.

Notes

• This is the recommended way to test Raft REST endpoints during bring-up — no network required.
• Logging output (LOG_I etc.) shares the same port; the binary protocol uses MSB-set bytes so it does not collide with log text.
• On a USB-Serial-JTAG console SerialConsole installs the USB-Serial-JTAG driver (with rxBuf / txBuf as its ring sizes) and an ESP-IDF log hook that writes to it.
• When nothing on the host is reading the USB port (no terminal has it open), the driver's transmit ring fills and stays full. Each console write then waits up to 10 ms (RAFT_LOGGER_USB_JTAG_WRITE_TIMEOUT_MS) and the text is dropped. In RaftCore versions after 1.58.1, once a write has timed out, later writes don't wait (and are dropped) until one succeeds again. A burst of log lines therefore costs one wait rather than 10 ms per line on the logging task, which is often the main loop. When a host starts reading again, output resumes with no lines lost after that point.
  • In RaftSysMods versions after 1.23.1 the ESP-IDF log hook writes through the same code (LoggerCore::writeToConsole()), so this applies to ESP-IDF logging as well as Raft logging.
  • Main-loop timing measured with a terminal attached can differ from timing with nothing reading the port, so measure both.

Related

• Communications Stack Overview
• Comms Channels
• Console Port Sharing