This commit is contained in:
sagiferi
2026-05-20 21:48:13 +02:00
parent a907d8ba74
commit d3c13f997e
446 changed files with 70716 additions and 0 deletions
+314
View File
@@ -0,0 +1,314 @@
# 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
## If the serial link is mostly needed at boot
- `SoftSerial` may 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.