Doc updates.

Author: jscott3201

docs/architecture.md

@@ -106,6 +106,27 @@ MAC address format varies by transport:
 
 `AnyTransport<S>` is a type-erased enum wrapping all transport types, enabling mixed-transport routing (e.g., BIP + MS/TP + Loopback on the same router).
 
+### RS-485 Direction Control (MS/TP)
+
+RS-485 is half-duplex — the transceiver's DE/RE pin must be toggled between transmit and receive. The stack supports three modes:
+
+```
+                              ┌──────────────────────────┐
+USB RS-485 Adapter ──────────>│  TokioSerialPort         │  Auto-direction
+(FTDI, CH340, etc.)           │  (no config needed)      │  (hardware handles DE/RE)
+                              └──────────────────────────┘
+
+UART + RTS → DE/RE ──────────>│  TokioSerialPort         │  Kernel RS-485
+(DE wired to UART RTS pin)    │  .enable_kernel_rs485()  │  (TIOCSRS485 ioctl)
+                              └──────────────────────────┘
+
+UART + GPIO → DE/RE ─────────>│  GpioDirectionPort<S>    │  GPIO direction
+(Pi hat, GPIO pin for DE)     │  wraps any SerialPort    │  (gpiocdev, serial-gpio feature)
+                              └──────────────────────────┘
+```
+
+`GpioDirectionPort` is a composable wrapper — it wraps any `SerialPort` and toggles a GPIO pin via the Linux character device API (`/dev/gpiochipN`) before and after each write. This keeps `TokioSerialPort` simple and platform-independent.
+
 ## Object Model
 
 Every BACnet object implements the `BACnetObject` trait:

docs/rust-api.md

@@ -249,7 +249,8 @@ Transport-layer implementations. All implement the `TransportPort` trait.
 | (default) | all | BIP (UDP/IPv4) |
 | `ipv6` | all | BIP6 (UDP/IPv6 multicast) |
 | `sc-tls` | all | BACnet/SC (WebSocket + TLS) + SC Hub |
-| `serial` | Linux | MS/TP (serial token-passing) |
+| `serial` | all | MS/TP (serial token-passing via `tokio-serial`) |
+| `serial-gpio` | Linux | MS/TP + GPIO direction control (adds `gpiocdev`) |
 | `ethernet` | Linux | BACnet Ethernet (BPF) |
 
 ### BIP (IPv4)
@@ -301,6 +302,82 @@ let addr = hub.start().await?;  // Returns SocketAddr
 
 The SC hub is a TLS WebSocket relay. Both clients and servers connect to it as spoke nodes. Messages are routed by VMAC address.
 
+### MS/TP (Serial RS-485)
+
+MS/TP is a token-passing protocol over RS-485 serial, commonly used for field-level BACnet devices. The serial I/O is abstracted behind the `SerialPort` trait, with three RS-485 direction control modes.
+
+#### Auto-Direction (USB RS-485 Adapters)
+
+Most USB RS-485 adapters (FTDI, CH340, CP2102) handle direction switching in hardware — no configuration needed.
+
+```rust
+use bacnet_transport::mstp_serial::{TokioSerialPort, SerialConfig};
+
+let serial = TokioSerialPort::open(&SerialConfig {
+    port_name: "/dev/ttyUSB0".into(),   // Linux
+    // port_name: "/dev/cu.usbserial-xxx".into(),  // macOS
+    baud_rate: 76800,
+})?;
+
+// Use with BACnetClient or BACnetServer via generic_builder
+let client = BACnetClient::generic_builder()
+    .transport(MstpTransport::new(serial, 1, 127))  // station 1, max_master 127
+    .build()
+    .await?;
+```
+
+#### Kernel RS-485 Mode (Linux, RTS-based)
+
+When DE/RE is wired to the UART's RTS pin, the Linux kernel can toggle it automatically via the `TIOCSRS485` ioctl. Zero userspace overhead.
+
+```rust
+let serial = TokioSerialPort::open(&config)?;
+serial.enable_kernel_rs485(
+    false,  // invert_rts: false = RTS HIGH during TX
+    0,      // delay_before_send_us
+    0,      // delay_after_send_us
+)?;
+```
+
+#### GPIO Direction Control (RS-485 Hats)
+
+For RS-485 hats where DE/RE is wired to a GPIO pin (e.g., Seeed Studio RS-485 Shield on Raspberry Pi with GPIO18), use `GpioDirectionPort` to wrap any `SerialPort`. Requires the `serial-gpio` feature.
+
+```rust
+use bacnet_transport::mstp_serial::{GpioDirectionPort, TokioSerialPort, SerialConfig};
+
+let serial = TokioSerialPort::open(&SerialConfig {
+    port_name: "/dev/ttyS0".into(),
+    baud_rate: 76800,
+})?;
+
+// Wrap with GPIO direction control: gpiochip0, line 18, active-high
+let port = GpioDirectionPort::new(serial, "/dev/gpiochip0", 18, true)?;
+
+// Or with explicit post-TX delay (microseconds before switching to RX):
+let port = GpioDirectionPort::with_post_tx_delay(
+    serial, "/dev/gpiochip0", 18, true, 200,
+)?;
+```
+
+The `GpioDirectionPort` wrapper:
+- Sets GPIO to receive mode (DE deasserted) on creation
+- Switches to TX mode before each `write()`
+- Waits for optional post-TX delay after write completes
+- Switches back to RX mode after each `write()`
+- Uses the Linux GPIO character device (`/dev/gpiochipN`) via `gpiocdev` — not deprecated sysfs
+
+#### SerialPort Trait
+
+The MS/TP state machine is hardware-agnostic. Custom serial implementations (e.g., for testing) can implement:
+
+```rust
+pub trait SerialPort: Send + Sync + 'static {
+    fn write(&self, data: &[u8]) -> impl Future<Output = Result<(), Error>> + Send;
+    fn read(&self, buf: &mut [u8]) -> impl Future<Output = Result<usize, Error>> + Send;
+}
+```
+
 ### Loopback Transport
 
 ```rust
@@ -856,3 +933,40 @@ let client = BACnetClient::sc_builder()
     .build()
     .await?;
 ```
+
+### MS/TP with USB Adapter
+
+```rust
+use bacnet_transport::mstp::MstpTransport;
+use bacnet_transport::mstp_serial::{TokioSerialPort, SerialConfig};
+
+let serial = TokioSerialPort::open(&SerialConfig {
+    port_name: "/dev/ttyUSB0".into(),
+    baud_rate: 76800,
+})?;
+
+let client = BACnetClient::generic_builder()
+    .transport(MstpTransport::new(serial, 1, 127))
+    .build()
+    .await?;
+```
+
+### MS/TP with Raspberry Pi RS-485 Hat (GPIO)
+
+```rust
+use bacnet_transport::mstp::MstpTransport;
+use bacnet_transport::mstp_serial::{GpioDirectionPort, TokioSerialPort, SerialConfig};
+
+let serial = TokioSerialPort::open(&SerialConfig {
+    port_name: "/dev/ttyS0".into(),
+    baud_rate: 76800,
+})?;
+
+// Seeed Studio RS-485 Shield: GPIO18 for DE/RE, active-high
+let port = GpioDirectionPort::new(serial, "/dev/gpiochip0", 18, true)?;
+
+let client = BACnetClient::generic_builder()
+    .transport(MstpTransport::new(port, 1, 127))
+    .build()
+    .await?;
+```