# 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.