315 lines
7.8 KiB
Markdown
315 lines
7.8 KiB
Markdown
# 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.
|