eminboydak Hardware Test Procedures
Standard procedures for testing serial communication with real hardware. Run them in order; stop at the first failure and consult Common Issues.
No hardware on the bench? Use the No-Hardware Path instead.
No-Hardware Path (Mock + Virtual Ports)
When no physical adapter or board is available, verify in three rungs. Each rung exercises a deeper layer; all run on a plain laptop.
Rung 1 — Unit tests (no port at all)
cargo test # real backend, hardware-independent assertions
Rung 2 — Mock backend (fake port in-process)
The mock backend (cargo feature mock) owns exactly one fake port.
List and open must agree on its name; unknown names are rejected,
mirroring real open() failure — so negative-path tests stay meaningful.
cargo test --features mock
Convention: name the fake port explicitly (duckTerm uses mock-0) and
share the constant between list and open. Never let the mock accept
arbitrary names — that silently disables invalid-port tests.
Rung 3 — Virtual port pair (real OS serial stack, no hardware)
socat creates two linked PTYs that behave like a loopback cable
through the real OS serial stack. Verified bidirectional on macOS.
# Terminal 1 — bring up the pair (leave running)
socat PTY,link=/tmp/ttyV0,raw,echo=0 PTY,link=/tmp/ttyV1,raw,echo=0
# Terminal 2 — open /tmp/ttyV0 in the app under test,
# write to /tmp/ttyV1 from a second peer to complete the loop
Linux: same recipe (/tmp/ttyV0, /tmp/ttyV1).
Windows: use com0com to create a COM port pair instead.
Procedure mirrors the Loopback Test above: send ASCII, expect echo;
send hex 0x48 0x65 0x6C 0x6C 0x6F, expect Hello; sweep baud rates.
The only difference is the cable is software.
Rung 4 — Real hardware
The Loopback, Port Discovery, and Signal Line tests below. This is the final gate before release, not the first thing you try.
Loopback Test
The most basic serial test — connect TX to RX on the same port.
Setup
- Connect a USB-UART adapter or use the board's built-in serial (e.g. Arduino, ESP32 devkit).
- Physically connect the TX pin to the RX pin (loopback).
- Open a serial terminal, select the port, set baud rate (try 9600 first).
Test Steps
- Send any ASCII text.
- Verify the same text appears in the receive window.
- Send hex bytes:
0x48 0x65 0x6C 0x6C 0x6F(should display "Hello"). - Test different baud rates: 9600, 19200, 38400, 57600, 115200.
- Test with line endings:
\r\n,\n, none.
Expected Results
- Sent data echoes back exactly.
- No garbled characters at correct baud rate.
- Garbled characters at wrong baud rate (expected — confirms the link is live).
Port Discovery Test
Verify the terminal can find available serial ports.
- Connect a USB-UART adapter.
- Open the serial terminal.
- Check that the port appears in the port list.
- Disconnect — port should disappear.
- Reconnect — port should reappear.
Signal Line Test
Test RTS/DTR control and CTS/DSR/RI/CD reading.
- Open a connection.
- Toggle RTS — measure voltage on the RTS pin (should go high/low).
- Toggle DTR — measure voltage on the DTR pin.
- Connect CTS to RTS on the adapter — toggle RTS, verify CTS state changes.
Common Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| No data received | Wrong baud rate | Match sender/receiver rates |
| Garbled text | Baud rate mismatch | Ensure both sides use same rate |
| Port not found | Permission issue | Add user to dialout group (Linux) |
| Permission denied | Port in use | Close other terminal apps |