Skip to content

USB API improvements and documentation - #1130

Open
piotrfila wants to merge 27 commits into
ZigEmbeddedGroup:mainfrom
piotrfila:usb-api
Open

piotrfila wants to merge 27 commits into
ZigEmbeddedGroup:mainfrom
piotrfila:usb-api

Conversation

@piotrfila

@piotrfila piotrfila commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Based on talks on discord with @vesim987

This should make some drivers (such as HID and MIDI) more ergonomic.

Major changes:

  • usb.DeviceController options and configuration data are now separate
  • usb.DeviceController configuration data now includes driver options
  • Some functionality of usb.DeviceController moved to usb.Configuration (which brings us closer to supporting multiple configurations per device)
  • Added an example for usb.driver.EchoExample, so that the driver does not bitrot.
  • Hopefully made some of the comptime magic more comprehensible
  • Added documentation of the usb driver interface
  • Add some checks that the comptime driver interface is implemented correctly in drivers
  • USB HID report structs are generated automatically

@piotrfila
piotrfila marked this pull request as draft November 10, 2026 19:08

@Grazfather Grazfather left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly looks good, will want to take another look, but: If we are assigning This() to a name, let's use that name

Comment thread core/src/core/usb/drivers/CDC.zig Resolved
Comment thread core/src/core/usb/drivers/CDC.zig Resolved
Comment thread port/wch/ch32v/src/hals/usbhs.zig Resolved
Comment thread port/wch/ch32v/src/hals/usbfs.zig Resolved
@piotrfila
piotrfila marked this pull request as ready for review November 12, 2026 01:04
@piotrfila

Copy link
Copy Markdown
Contributor Author

I tested these changes on pico 2, but not on nrf5x or ch32v, testing those platforms would be appreciated!

@vesim987 vesim987 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mattnite

Copy link
Copy Markdown
Contributor

@piotrfila I have an nrf5, and a ch32v, I'm on a trip right now, but I'll give those a test by Tuesday!

@Grazfather Grazfather left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, some pedantic issues. A lot of unrelated changes I'd prefer to merge separately, but nbd.


const pin_config: rp2xxx.pins.GlobalConfiguration = .{
.GPIO25 = .{ .name = "led", .direction = .out },
};

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just pull these from the board file?

Comment thread core/src/core/usb/configuration.zig Resolved
Comment thread core/src/core/usb.zig
pub const ack: []const u8 = "";
pub const nak: ?[]const u8 = null;

// What does this do? It lets you iterate through interfaces and endpoints?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lmao. This is an old comment I wrote while trying to grok our USB stuff. Never intended to be committed.

Comment thread core/src/core/usb/configuration.zig Resolved
const zenkakuhankaku: @This() = .lang5;
};

pub const Ledcode = enum(u3) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be LedCode?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keycode does not have C capitalized, having Keycode but LedCode seemed inconsistent, this was the variant I liked most out of:

  • KeyCode, LedCode
  • Keycode, LedCode
  • Keycode, Ledcode
    but first variant is also ok imo

@piotrfila

piotrfila commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

Regarding the random changes: I first found the pointless @as casting in usb code so I also remoed other occurrences, I agree it would have been better in a separate PR but I wasnt planning on making #1132 when I commited the changes

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants