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
- Platform: What the MCU/core can do
- Pinmap: Which serial roles are exposed on this board
- Feature: Whether the transport is actually a good fit for the workload
Examples
- GPS over
SoftSerialcan be fine - TMC2209 over
SoftSerialmay 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_ASERIAL_BSERIAL_CSERIAL_DSERIAL_ESERIAL_GPSSERIAL_TMCSERIAL_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 = HardSerialwith 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 = SerialUSB1andSERIAL_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
SoftwareSerialsupport 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 = Serial2SERIAL_TMC = Serial1
and then separately define
SERIAL_B_RXSERIAL_B_TXSERIAL_TMC_RXSERIAL_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
SoftSerialfor 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_TMCis 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
SoftSerialmay be acceptable for one-time setup at bootSoftSerialis 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
SoftSerialmay 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
If the serial link is mostly needed at boot
SoftSerialmay be acceptable
If the serial link is needed continuously during runtime
- 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.