Files
onstep/docs/SERIAL_NOTES.md
2026-05-20 21:48:13 +02:00

7.8 KiB
Executable File

Serial Notes

Purpose

These notes explain how serial interfaces are used in OnStepX and why serial configuration can be confusing across platforms.

The short version is

  • a platform may support several kinds of serial interfaces
  • a pinmap chooses which ones are exposed for a given board
  • a feature may or may not be well suited to the chosen serial transport

So "serial is supported" does not always mean

  • easy to configure
  • portable to another board
  • good for real-time runtime use

Quick Summary

Think about serial in three layers

  1. Platform: What the MCU/core can do
  2. Pinmap: Which serial roles are exposed on this board
  3. Feature: Whether the transport is actually a good fit for the workload

Examples

  • GPS over SoftSerial can be fine
  • TMC2209 over SoftSerial may compile but still be a poor runtime fit
  • Teensy can expose extra USB virtual serial ports
  • ESP32 can often move hardware UARTs to different pins

The Main Serial Roles

OnStepX uses generic serial role names instead of hard-coding one board's port names everywhere.

Common roles include

  • SERIAL_A
  • SERIAL_B
  • SERIAL_C
  • SERIAL_D
  • SERIAL_E
  • SERIAL_GPS
  • SERIAL_TMC
  • SERIAL_DEBUG

These are best thought of as roles, not fixed physical ports.

One board might make

  • SERIAL_B = Serial2

Another board might make

  • SERIAL_B = HardSerial with configured RX/TX pins

Another board might not expose SERIAL_B at all.

The Main Serial Types

In practice, OnStepX may use

  • built-in hardware serial ports such as Serial1, Serial2, etc.
  • created hardware serial objects using chosen RX/TX pins
  • SoftwareSerial
  • USB virtual serial ports
  • internal pseudo-serial helpers such as SERIAL_LOCAL

All of these may look stream-like in code, but they are not equally suitable for all jobs.

Platform Differences

This is where a lot of confusion starts.

Teensy

  • often has multiple hardware UARTs
  • can also expose extra USB virtual serial ports depending on USB mode
  • some pinmaps use that to expose SERIAL_D = SerialUSB1 and SERIAL_E = SerialUSB2

ESP32

  • usually has flexible hardware UART routing
  • can often place UART RX/TX on non-default pins
  • that makes created hardware serial or remapped UART use more practical than on some other Arduino-class targets
  • also has optional Bluetooth serial support in the HAL

STM32

  • often supports created/remapped hardware serial well
  • also pulls in SoftwareSerial support early in the HAL because library/core behavior can otherwise get awkward

Why ESP32 Is Worth Calling Out

ESP32 is a good example of why "hardware serial" does not always mean "hard-wired fixed pins."

In OnStepX, some ESP32 pinmaps define roles like

  • SERIAL_B = Serial2
  • SERIAL_TMC = Serial1

and then separately define

  • SERIAL_B_RX
  • SERIAL_B_TX
  • SERIAL_TMC_RX
  • SERIAL_TMC_TX

That means the feature gets a real hardware UART, but the board still has some freedom to place it where it makes sense.

This is one reason ESP32 can be a nice middle ground

  • better than SoftSerial for runtime work
  • more flexible than boards with only fixed UART pin assignments

Pinmaps Decide What Exists

The pinmap layer is where generic serial roles become concrete.

This means

  • a feature may request SERIAL_GPS
  • but whether that becomes SoftSerial, HardSerial, Serial1, or something else depends on the pinmap and platform

Compile-time validation catches some problems, for example

  • a baud rate is enabled for a serial role that the pinmap did not define
  • a TMC UART driver is enabled but SERIAL_TMC is missing

What validation does not prove

  • that the chosen serial transport is a good runtime fit
  • that it is non-blocking enough
  • that the underlying library behaves well on that platform

Best Uses For Each Type

Built-in or created hardware serial

Usually best for

  • continuous runtime traffic
  • higher baud rates
  • frequent bidirectional communication
  • motion-control related serial work

Examples

  • shared TMC2209 UART on boards designed for it
  • a secondary MCU link
  • frequent device polling

SoftwareSerial

Usually best for

  • one-time configuration at boot
  • low-rate telemetry
  • devices that become less important once startup finishes

Examples

  • GPS
  • boot-time driver setup in some constrained builds

USB virtual serial

Usually best for

  • extra host-side channels
  • debug, tooling, or auxiliary control on supported platforms

Examples

  • Teensy SerialUSB1
  • Teensy SerialUSB2

Why SoftwareSerial Is Tricky

SoftwareSerial is often the most confusing case because it is sometimes very useful and sometimes a terrible fit.

General concerns

  • it is often blocking or close enough to blocking to matter
  • support quality varies by platform
  • timing behavior varies by core and library
  • library code sitting on top of it may own the actual read/write behavior

So if a feature "supports SoftSerial", that should not automatically be read as:

  • well tested
  • non-blocking
  • appropriate for real-time runtime use

Example: GPS

GPS is one of the better cases for less-than-perfect serial.

Why

  • relatively low-rate
  • mostly an input stream
  • used to establish time/location
  • OnStepX may close the GPS serial port once current time has been acquired

So GPS over SoftSerial can be a reasonable trade on many builds.

That does not make SoftSerial universally good. It just means GPS is a feature that can often tolerate it.

Example: TMC2209 UART

TMC2209 is the opposite kind of example.

Why it is harder

  • runtime UART interaction can matter
  • mode changes may happen during operation
  • status/config traffic may be needed while the rest of the mount is busy
  • blocking behavior is much more painful in a real-time motion system

So for TMC2209

  • SoftSerial may be acceptable for one-time setup at boot
  • SoftSerial is much less attractive for active runtime interaction

That does not mean SoftSerial is useless here. It means the use case matters.

Example: More Than Four TMC2209s

There is one place where SoftSerial can still be attractive for TMC2209

  • per-device links can make scaling easier when a shared hardware UART bus gets awkward

So there is a real trade

  • shared hardware UART is usually better for runtime quality
  • per-device SoftSerial may make some larger or stranger topologies possible

This is why the answer is not simply

  • "never use SoftSerial"

It is more like

  • use it carefully
  • prefer it for boot/setup or unusual topologies
  • do not assume it is ideal for active runtime control

Library Ownership Matters

Another subtle point

OnStepX may define the transport, but the feature library often performs the real reads and writes.

That means serial behavior depends on

  • the platform core
  • the chosen transport
  • the feature library

This is especially relevant for

  • TMC driver libraries
  • any feature with frequent serial traffic

So a configuration can be theoretically valid while still being lightly tested or operationally uncertain.

Practical Rules Of Thumb

  • SoftSerial may be acceptable
  • prefer hardware UART where possible

If the board/platform offers extra USB serial channels

  • treat that as a platform-specific bonus, not a general Arduino assumption

If a user is choosing between "works in theory" and "works robustly"

  • favor the more boring hardware-UART option

Good Mental Summary

The simplest reliable way to think about serial in OnStepX is

  • HAL defines what the platform can plausibly do
  • the pinmap assigns generic serial roles to actual transports
  • the feature decides whether that transport is really suitable

That last step is where most serial surprises come from.