USB2GPIO Protocol Specification

Overview

This document describes the binary serial protocol used between a host system (Python on Linux) and a microcontroller (Arduino Mega 2560) acting as a GPIO interface.

The protocol is designed to be:

• Low latency
• Deterministic
• Event-driven (no polling required on host)
• Simple to implement on constrained microcontrollers

Communication occurs over USB CDC serial (e.g. /dev/ttyACM0).

---

Transport Layer

• Medium: USB CDC (virtual serial port)
• Baud rate: 115200
• Data format: 8N1
• Flow control: none

---

Message Framing

Two types of messages exist:

Direction	Type	Sync Byte
MCU → Host	Event	0xAA
Host → MCU	Command	0x55

The sync byte allows resynchronization in case of byte loss or misalignment.

---

MCU → Host: Event Message

Format (5 bytes)

[0xAA][pin][value][timestamp_lo][timestamp_hi]

Fields

Field	Size	Description
Sync	1	0xAA
Pin	1	GPIO pin number (0–69)
Value	1	Logic level (0 or 1)
Timestamp	2	millis() timestamp (uint16, little endian)

Notes

• Timestamp wraps every ~65 seconds.
• Events are generated on debounced state changes only.
• No duplicate events for stable signals.

---

Host → MCU: Command Message

Format (4 bytes)

[0x55][cmd][pin][value]

Commands

Cmd	Name	Description
1	SET_OUTPUT	Set digital output value
2	SET_MODE	Configure pin mode

Command Details

SET_OUTPUT (cmd = 1)

[0x55][1][pin][value]

• value: 0 = LOW, 1 = HIGH
• Pin must be configured as output

SET_MODE (cmd = 2)

[0x55][2][pin][value]

• value = 0 → INPUT (with pull-up enabled)
• value = 1 → OUTPUT

---

GPIO Behavior

Inputs

• Configured as INPUT_PULLUP
• Active low (button press → 0)
• Debounced in firmware

Debouncing

• Default debounce time: 10 ms

• Per-pin state tracking

• Event generated only if:

  • State changes
  • Debounce interval has elapsed

Interrupts

• Uses hardware interrupts for supported pins

• ISR performs:

  • State read
  • Debounce check
  • Event enqueue

---

Event Queue

Characteristics

• Ring buffer (FIFO)
• Fixed size (e.g. 32 entries)
• Shared between ISR and main loop

Behavior

• ISR enqueues events

• Main loop dequeues and transmits

• If queue is full:

  • New events are dropped (current implementation)

Considerations

• Queue overflow should be monitored in future revisions
• Optional: add overflow counter or special event

---

Synchronization Strategy

Host Side

• Read arbitrary byte stream
• Scan for sync byte (0xAA)
• Parse fixed-length frames

Resynchronization

If invalid data is encountered:

• Discard bytes until sync byte is found

---

Timing Characteristics

• Event latency: typically 1–3 ms
• Timestamp resolution: 1 ms
• Timestamp range: 0–65535 ms (wraps)

---

Error Handling

Current protocol has minimal error handling:

• No checksums
• No acknowledgements
• No retransmission

Implications

• Suitable for short USB links
• Not suitable for noisy or long-distance links

---

Limitations

• Limited number of interrupt-capable pins
• Timestamp wraparound
• No guaranteed delivery under overflow
• No command acknowledgment

---

Future Extensions

Possible improvements:

1. Checksums

Add 1-byte CRC:

[SYNC][...][CRC]

2. Extended Commands

• Bulk GPIO operations
• PWM control
• Analog reads

3. Event Types

Extend event format:

[SYNC][type][pin][value][timestamp...]

4. Queue Overflow Reporting

Special event:

[0xAA][0xFF][overflow_count][...]

5. Larger Timestamp

Upgrade to 32-bit timestamp

---

Design Rationale

Key decisions:

• Binary protocol → minimal overhead
• Fixed-size frames → simple parsing
• MCU-side debounce → deterministic behavior
• Event-driven → no host polling

---

Example Event

Button press on pin 2:

AA 02 00 34 12

• Pin: 2
• Value: 0 (pressed)
• Timestamp: 0x1234

---

Example Command

Set pin 13 HIGH:

55 01 0D 01

---

Summary

This protocol turns the microcontroller into a deterministic GPIO front-end:

• Hardware handles timing and debouncing
• Host handles logic and orchestration

The result is a robust and low-latency interface suitable for measurement and control systems.