mirror of https://github.com/qmk/qmk_firmware
149 lines
6.5 KiB
Markdown
149 lines
6.5 KiB
Markdown
# group `udc_group` {#group__udc__group}
|
|
|
|
The UDC provides a high-level abstraction of the usb device. You can use these functions to control the main device state (start/attach/wakeup).
|
|
|
|
USB Device Custom configurationThe following USB Device configuration must be included in the [conf_usb.h](.build/docs/internals_undefined.md#conf__usb_8h) file of the application.
|
|
|
|
USB_DEVICE_VENDOR_ID (Word)
|
|
Vendor ID provided by USB org (ATMEL 0x03EB).
|
|
|
|
USB_DEVICE_PRODUCT_ID (Word)
|
|
Product ID (Referenced in [usb_atmel.h](.build/docs/internals_undefined.md#usb__atmel_8h)).
|
|
|
|
USB_DEVICE_MAJOR_VERSION (Byte)
|
|
Major version of the device
|
|
|
|
USB_DEVICE_MINOR_VERSION (Byte)
|
|
Minor version of the device
|
|
|
|
USB_DEVICE_MANUFACTURE_NAME (string)
|
|
ASCII name for the manufacture
|
|
|
|
USB_DEVICE_PRODUCT_NAME (string)
|
|
ASCII name for the product
|
|
|
|
USB_DEVICE_SERIAL_NAME (string)
|
|
ASCII name to enable and set a serial number
|
|
|
|
USB_DEVICE_POWER (Numeric)
|
|
(unit mA) Maximum device power
|
|
|
|
USB_DEVICE_ATTR (Byte)
|
|
USB attributes available:
|
|
|
|
* USB_CONFIG_ATTR_SELF_POWERED
|
|
|
|
* USB_CONFIG_ATTR_REMOTE_WAKEUP Note: if remote wake enabled then defines remotewakeup callbacks, see Table 5-2. External API from UDC - Callback
|
|
|
|
USB_DEVICE_LOW_SPEED (Only defined)
|
|
Force the USB Device to run in low speed
|
|
|
|
USB_DEVICE_HS_SUPPORT (Only defined)
|
|
Authorize the USB Device to run in high speed
|
|
|
|
USB_DEVICE_MAX_EP (Byte)
|
|
Define the maximum endpoint number used by the USB Device.
|
|
This one is already defined in UDI default configuration. Ex:
|
|
|
|
* When endpoint control 0x00, endpoint 0x01 and endpoint 0x82 is used then USB_DEVICE_MAX_EP=2
|
|
|
|
* When only endpoint control 0x00 is used then USB_DEVICE_MAX_EP=0
|
|
|
|
* When endpoint 0x01 and endpoint 0x81 is used then USB_DEVICE_MAX_EP=1
|
|
(configuration not possible on USBB interface)
|
|
|
|
## Summary
|
|
|
|
Members | Descriptions
|
|
--------------------------------|---------------------------------------------
|
|
`public inline static bool `[`udc_include_vbus_monitoring`](#group__udc__group_1ga70d88509bac27ef9c25f693dd21d91ca)`(void)` | Authorizes the VBUS event.
|
|
`public void `[`udc_start`](#group__udc__group_1gadf4e193509cd03ab6333d62629ea51e7)`(void)` | Start the USB Device stack.
|
|
`public void `[`udc_stop`](#group__udc__group_1gae2264dd91b24db9d4bb23fb1a2014972)`(void)` | Stop the USB Device stack.
|
|
`public inline static void `[`udc_attach`](#group__udc__group_1ga2e71c4c6090543bc3bab06e710e2ee6b)`(void)` | Attach device to the bus when possible.
|
|
`public inline static void `[`udc_detach`](#group__udc__group_1ga702d387f5ebfc2e0ab41667eb7644dda)`(void)` | Detaches the device from the bus.
|
|
`public inline void `[`udc_remotewakeup`](#group__udc__group_1ga52c0439e5f6e471a9570471f00476260)`(void)` | The USB driver sends a resume signal called *"Upstream Resume"* This is authorized only when the remote wakeup feature is enabled by host.
|
|
`public `[`usb_iface_desc_t](.build/docs/internals_usb_protocol_group.md#structusb__iface__desc__t)[UDC_DESC_STORAGE`](.build/docs/internals_undefined.md#group__udc__desc__group_1gae086959cec07a2e71ab069e25a51764f)` * `[`udc_get_interface_desc`](#group__udc__group_1gadb2a0f5ad1e834d4d7e7777f901d64d2)`(void)` | Returns a pointer on the current interface descriptor.
|
|
|
|
## Members
|
|
|
|
#### `public inline static bool `[`udc_include_vbus_monitoring`](#group__udc__group_1ga70d88509bac27ef9c25f693dd21d91ca)`(void)` {#group__udc__group_1ga70d88509bac27ef9c25f693dd21d91ca}
|
|
|
|
Authorizes the VBUS event.
|
|
|
|
#### Returns
|
|
true, if the VBUS monitoring is possible.
|
|
|
|
VBus monitoring used casesThe VBus monitoring is used only for USB SELF Power application.
|
|
|
|
* By default the USB device is automatically attached when Vbus is high or when USB is start for devices without internal Vbus monitoring. [conf_usb.h](.build/docs/internals_undefined.md#conf__usb_8h) file does not contains define USB_DEVICE_ATTACH_AUTO_DISABLE.
|
|
```cpp
|
|
//#define USB_DEVICE_ATTACH_AUTO_DISABLE
|
|
```
|
|
|
|
* Add custom VBUS monitoring. [conf_usb.h](.build/docs/internals_undefined.md#conf__usb_8h) file contains define USB_DEVICE_ATTACH_AUTO_DISABLE:
|
|
```cpp
|
|
#define USB_DEVICE_ATTACH_AUTO_DISABLE
|
|
```
|
|
User C file contains:
|
|
```cpp
|
|
// Authorize VBUS monitoring
|
|
if (!udc_include_vbus_monitoring()) {
|
|
// Implement custom VBUS monitoring via GPIO or other
|
|
}
|
|
Event_VBUS_present() // VBUS interrupt or GPIO interrupt or other
|
|
{
|
|
// Attach USB Device
|
|
udc_attach();
|
|
}
|
|
```
|
|
|
|
* Case of battery charging. [conf_usb.h](.build/docs/internals_undefined.md#conf__usb_8h) file contains define USB_DEVICE_ATTACH_AUTO_DISABLE:
|
|
```cpp
|
|
#define USB_DEVICE_ATTACH_AUTO_DISABLE
|
|
```
|
|
User C file contains:
|
|
```cpp
|
|
Event VBUS present() // VBUS interrupt or GPIO interrupt or ..
|
|
{
|
|
// Authorize battery charging, but wait key press to start USB.
|
|
}
|
|
Event Key press()
|
|
{
|
|
// Stop batteries charging
|
|
// Start USB
|
|
udc_attach();
|
|
}
|
|
```
|
|
|
|
#### `public void `[`udc_start`](#group__udc__group_1gadf4e193509cd03ab6333d62629ea51e7)`(void)` {#group__udc__group_1gadf4e193509cd03ab6333d62629ea51e7}
|
|
|
|
Start the USB Device stack.
|
|
|
|
#### `public void `[`udc_stop`](#group__udc__group_1gae2264dd91b24db9d4bb23fb1a2014972)`(void)` {#group__udc__group_1gae2264dd91b24db9d4bb23fb1a2014972}
|
|
|
|
Stop the USB Device stack.
|
|
|
|
#### `public inline static void `[`udc_attach`](#group__udc__group_1ga2e71c4c6090543bc3bab06e710e2ee6b)`(void)` {#group__udc__group_1ga2e71c4c6090543bc3bab06e710e2ee6b}
|
|
|
|
Attach device to the bus when possible.
|
|
|
|
If a VBus control is included in driver, then it will attach device when an acceptable Vbus level from the host is detected.
|
|
|
|
#### `public inline static void `[`udc_detach`](#group__udc__group_1ga702d387f5ebfc2e0ab41667eb7644dda)`(void)` {#group__udc__group_1ga702d387f5ebfc2e0ab41667eb7644dda}
|
|
|
|
Detaches the device from the bus.
|
|
|
|
The driver must remove pull-up on USB line D- or D+.
|
|
|
|
#### `public inline void `[`udc_remotewakeup`](#group__udc__group_1ga52c0439e5f6e471a9570471f00476260)`(void)` {#group__udc__group_1ga52c0439e5f6e471a9570471f00476260}
|
|
|
|
The USB driver sends a resume signal called *"Upstream Resume"* This is authorized only when the remote wakeup feature is enabled by host.
|
|
|
|
#### `public `[`usb_iface_desc_t](.build/docs/internals_usb_protocol_group.md#structusb__iface__desc__t)[UDC_DESC_STORAGE`](.build/docs/internals_undefined.md#group__udc__desc__group_1gae086959cec07a2e71ab069e25a51764f)` * `[`udc_get_interface_desc`](#group__udc__group_1gadb2a0f5ad1e834d4d7e7777f901d64d2)`(void)` {#group__udc__group_1gadb2a0f5ad1e834d4d7e7777f901d64d2}
|
|
|
|
Returns a pointer on the current interface descriptor.
|
|
|
|
#### Returns
|
|
pointer on the current interface descriptor.
|
|
|