Struct usbd_hid::hid_class::HIDClass

pub struct HIDClass<'a, B: UsbBus> { /* private fields */ }

HIDClass provides an interface to declare, read & write HID reports.

Users are expected to provide the report descriptor, as well as pack and unpack reports which are read or staged for transmission.

Implementations

impl<B: UsbBus> HIDClass<'_, B>

pub fn new<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8
) -> HIDClass<'a, B>

Creates a new HIDClass with the provided UsbBus & HID report descriptor.

poll_ms configures how frequently the host should poll for reading/writing HID reports. A lower value means better throughput & latency, at the expense of CPU on the device & bandwidth on the bus. A value of 10 is reasonable for high performance uses, and a value of 255 is good for best-effort usecases.

This allocates two endpoints (IN and OUT). See new_ep_in (IN endpoint only) and new_ep_out (OUT endpoint only) to only create a single endpoint.

See new_with_settings() if you need to define protocol or locale settings for a IN/OUT HID interface.

pub fn new_with_settings<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8,
    settings: HidClassSettings
) -> HIDClass<'a, B>

Same as new() but includes a settings field. The settings field is used to define both locale and protocol settings of the HID device (needed for HID keyboard and Mice).

pub fn new_ep_in<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8
) -> HIDClass<'a, B>

Creates a new HIDClass with the provided UsbBus & HID report descriptor. See new() for more details. Please use new_ep_in_with_settings() if you are creating a keyboard or mouse.

pub fn new_ep_in_with_settings<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8,
    settings: HidClassSettings
) -> HIDClass<'a, B>

Same as new_ep_in() but includes a settings field. The settings field is used to define both locale and protocol settings of the HID device (needed for HID keyboard and Mice).

pub fn new_ep_out<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8
) -> HIDClass<'a, B>

Creates a new HIDClass with the provided UsbBus & HID report descriptor. See new() for more details. Please use new_ep_out_with_settings if you need the settings field.

pub fn new_ep_out_with_settings<'a>(
    alloc: &'a UsbBusAllocator<B>,
    report_descriptor: &'static [u8],
    poll_ms: u8,
    settings: HidClassSettings
) -> HIDClass<'a, B>

Same as new_ep_out() but includes a settings field. This should be uncommon (non-standard), but is included for completeness as there may be cases where setting the locale is useful.

pub fn push_input<IR: AsInputReport>(&self, r: &IR) -> Result<usize>

Tries to write an input report by serializing the given report structure. A BufferOverflow error is returned if the serialized report is greater than 64 bytes in size.

pub fn push_raw_input(&self, data: &[u8]) -> Result<usize>

Tries to write an input (device-to-host) report from the given raw bytes. Data is expected to be a valid HID report for INPUT items. If report ID’s were used in the descriptor, the report ID corresponding to this report must be be present before the contents of the report.

pub fn pull_raw_output(&self, data: &mut [u8]) -> Result<usize>

Tries to read an output (host-to-device) report as raw bytes. Data is expected to be sized appropriately to contain any valid HID report for OUTPUT items, including the report ID prefix if report IDs are used.

pub fn pull_raw_report(&mut self, data: &mut [u8]) -> Result<ReportInfo>

Tries to read an incoming SET_REPORT report as raw bytes. Unlike OUT endpoints, report IDs are not prefixed in the buffer. Use the returned tuple instead to determine the buffer’s usage.

The most common usage of pull_raw_report is for keyboard lock LED status if an OUT endpoint is not defined. It is not necessary to call this function if you’re not going to be using SET_REPORT functionality.

pub fn get_protocol_mode(&self) -> Result<HidProtocolMode>

Retrieves the currently set device protocol This is equivalent to the USB HID GET_PROTOCOL request See (7.2.5): https://www.usb.org/sites/default/files/hid1_11.pdf

pub fn set_protocol_mode(
    &mut self,
    mode: HidProtocolMode,
    config: ProtocolModeConfig
) -> Result<()>

Forcibly sets the device protocol This is equivalent to the USB HID SET_PROTOCOL request. NOTE: If the OS does not support the new mode, the device may no longer work correctly. See (7.2.6): https://www.usb.org/sites/default/files/hid1_11.pdf

If either, ForceBoot or ForceReport are set in config, the mode argument is ignored. In addition, if ForceBoot or ForceReport are set, then any SET_PROTOCOL requests are also ignored.

Trait Implementations

impl<B: UsbBus> UsbClass<B> for HIDClass<'_, B>

fn get_configuration_descriptors(
    &self,
    writer: &mut DescriptorWriter<'_>
) -> Result<()>

Called when a GET_DESCRIPTOR request is received for a configuration descriptor. When called, the implementation should write its interface, endpoint and any extra class descriptors into writer. The configuration descriptor itself will be written by UsbDevice and shouldn’t be written by classes.

fn control_in(&mut self, xfer: ControlIn<'_, '_, '_, B>)

Called when a control request is received with direction DeviceToHost.

fn control_out(&mut self, xfer: ControlOut<'_, '_, '_, B>)

Called when a control request is received with direction HostToDevice.

fn get_bos_descriptors(
    &self,
    writer: &mut BosWriter<'_, '_>
) -> Result<(), UsbError>

Called when a GET_DESCRIPTOR request is received for a BOS descriptor. When called, the implementation should write its blobs such as capability descriptors into writer. The BOS descriptor itself will be written by UsbDevice and shouldn’t be written by classes.

fn get_string(&self, index: StringIndex, lang_id: u16) -> Option<&str>

Gets a class-specific string descriptor.

fn reset(&mut self)

Called after a USB reset after the bus reset sequence is complete.

fn poll(&mut self)

Called whenever the UsbDevice is polled.

fn endpoint_setup(&mut self, addr: EndpointAddress)

Called when endpoint with address addr has received a SETUP packet. Implementing this shouldn’t be necessary in most cases, but is provided for completeness’ sake.

fn endpoint_out(&mut self, addr: EndpointAddress)

Called when endpoint with address addr has received data (OUT packet).

fn endpoint_in_complete(&mut self, addr: EndpointAddress)

Called when endpoint with address addr has completed transmitting data (IN packet).