Project 14: TinyUSB Composite Device Studio (CDC + HID)

Build and debug a reliable USB composite device on Cardputer with clean descriptors, cross-OS enumeration stability, and power-safe behavior.

Quick Reference

Attribute Value
Difficulty Expert
Time Estimate 2 weeks
Main Programming Language C
Alternative Programming Languages C++, Rust
Coolness Level Level 4
Business Potential Level 3
Prerequisites USB basics, descriptor structure
Key Topics TinyUSB stack, report descriptors, enumeration debug, power constraints

1. Learning Objectives

  1. Design USB descriptor trees deliberately.
  2. Build a CDC+HID composite profile that enumerates consistently.
  3. Debug host-side enumeration failures with protocol evidence.
  4. Validate USB current/power declarations against behavior.

2. Theory

2.1 Descriptor Engineering

USB descriptors are protocol contracts. Length, ordering, and class semantics must be exact.

2.2 Composite Device Failure Patterns

Most failures come from descriptor mismatches, endpoint collisions, or non-portable HID report definitions.

3. Specification

  • One USB configuration with CDC and HID functions.
  • Host validation on Linux/macOS/Windows.
  • Structured failure log taxonomy for enumeration issues.

Output:

$ lsusb -v | rg "bNumInterfaces|HID|CDC"
bNumInterfaces 3
bInterfaceClass Communications
bInterfaceClass Human Interface Device

4. Architecture

[TinyUSB Core] -> [Descriptor Tables] -> [CDC Function]
                                     -> [HID Function]
                                     -> [Power Policy]

5. Implementation Guide

Core question:

“How do I design USB descriptors that are portable and debuggable?”

Design questions:

  1. Which interfaces and endpoints are strictly required?
  2. How will you version report descriptors?
  3. Which host logs are mandatory in bug reports?

6. Testing

  • Descriptor parser validation.
  • Cross-OS plug/unplug cycles.
  • Rapid reconnect and suspend/resume tests.

7. Pitfalls

  • Incorrect total descriptor length.
  • Non-standard HID usages causing host parser rejection.
  • Ignoring declared vs observed USB current.

8. Extensions

  • Add MSC or vendor-specific interface.
  • Add host-side descriptor lint automation.

9. Completion

  • Composite mode enumerates on at least two host OSes.
  • Descriptor docs and validation script are included.
  • Enumeration failures produce actionable diagnostics.