Struct HIDClass
pub struct HIDClass<'a, B>where
B: UsbBus,{ /* private fields */ }
Expand description
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> HIDClass<'_, B>where
B: UsbBus,
impl<B> HIDClass<'_, B>where
B: UsbBus,
pub fn new<'a>(
alloc: &'a UsbBusAllocator<B>,
report_descriptor: &'static [u8],
poll_ms: u8,
) -> HIDClass<'a, 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>
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>
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>
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>
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>
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>(&self, r: &IR) -> Result<usize, UsbError>where
IR: AsInputReport,
pub fn push_input<IR>(&self, r: &IR) -> Result<usize, UsbError>where
IR: AsInputReport,
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, UsbError>
pub fn push_raw_input(&self, data: &[u8]) -> Result<usize, UsbError>
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, UsbError>
pub fn pull_raw_output(&self, data: &mut [u8]) -> Result<usize, UsbError>
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, UsbError>
pub fn pull_raw_report( &mut self, data: &mut [u8], ) -> Result<ReportInfo, UsbError>
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, UsbError>
pub fn get_protocol_mode(&self) -> Result<HidProtocolMode, UsbError>
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<(), UsbError>
pub fn set_protocol_mode( &mut self, mode: HidProtocolMode, config: ProtocolModeConfig, ) -> Result<(), UsbError>
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> UsbClass<B> for HIDClass<'_, B>where
B: UsbBus,
impl<B> UsbClass<B> for HIDClass<'_, B>where
B: UsbBus,
§fn get_configuration_descriptors(
&self,
writer: &mut DescriptorWriter<'_>,
) -> Result<(), UsbError>
fn get_configuration_descriptors( &self, writer: &mut DescriptorWriter<'_>, ) -> Result<(), UsbError>
writer
. The configuration descriptor itself will be written by
UsbDevice and shouldn’t be written by classes. Read more§fn control_in(&mut self, xfer: ControlIn<'_, '_, '_, B>)
fn control_in(&mut self, xfer: ControlIn<'_, '_, '_, B>)
§fn control_out(&mut self, xfer: ControlOut<'_, '_, '_, B>)
fn control_out(&mut self, xfer: ControlOut<'_, '_, '_, B>)
§fn get_bos_descriptors(
&self,
writer: &mut BosWriter<'_, '_>,
) -> Result<(), UsbError>
fn get_bos_descriptors( &self, writer: &mut BosWriter<'_, '_>, ) -> Result<(), UsbError>
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: LangID) -> Option<&str>
fn get_string(&self, index: StringIndex, lang_id: LangID) -> Option<&str>
§fn endpoint_setup(&mut self, addr: EndpointAddress)
fn endpoint_setup(&mut self, addr: EndpointAddress)
addr
has received a SETUP packet. Implementing this
shouldn’t be necessary in most cases, but is provided for completeness’ sake. Read more§fn endpoint_out(&mut self, addr: EndpointAddress)
fn endpoint_out(&mut self, addr: EndpointAddress)
addr
has received data (OUT packet). Read more§fn endpoint_in_complete(&mut self, addr: EndpointAddress)
fn endpoint_in_complete(&mut self, addr: EndpointAddress)
addr
has completed transmitting data (IN packet). Read more