# Test Hardware

> Use when testing serial communication with real hardware (Arduino, ESP32, USB-UART adapter). Guides loopback test, port discovery verification, signal line testing. Triggers on hardware test, serial test, loopback, Arduino, ESP32.

- Skill: `eminboydak/test-hardware` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eminboydak/test-hardware`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eminboydak/test-hardware/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: eminboydak (https://skillmd.com/u/eminboydak)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/eminboydak/test-hardware

---


# 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](#no-hardware-path-mock--virtual-ports) 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)

```bash
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.

```bash
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.

```bash
# 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

1. Connect a USB-UART adapter or use the board's built-in serial (e.g. Arduino, ESP32 devkit).
2. Physically connect the TX pin to the RX pin (loopback).
3. Open a serial terminal, select the port, set baud rate (try 9600 first).

### Test Steps

1. Send any ASCII text.
2. Verify the same text appears in the receive window.
3. Send hex bytes: `0x48 0x65 0x6C 0x6C 0x6F` (should display "Hello").
4. Test different baud rates: 9600, 19200, 38400, 57600, 115200.
5. 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.

1. Connect a USB-UART adapter.
2. Open the serial terminal.
3. Check that the port appears in the port list.
4. Disconnect — port should disappear.
5. Reconnect — port should reappear.

## Signal Line Test

Test RTS/DTR control and CTS/DSR/RI/CD reading.

1. Open a connection.
2. Toggle RTS — measure voltage on the RTS pin (should go high/low).
3. Toggle DTR — measure voltage on the DTR pin.
4. 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 |