USB Device high level library

True if SOF timestamping is really provided.

SOF timestamping is really provided if it was requested and if the logger is enabled.

SOF event handling modes.

Push SOF events into event queue.

Get information whether there is an active connection.

Function to check if the communication with the bus is possible.

Return values

true	The bus is active.
false	There is no connection or bus is suspended.

Auxiliary function that process event by every instance in the list.

This function ignores the result of called handler.

Parameters

p_event

Event to pass to every instance.

Deselect all interfaces.

Auxiliary function to disable all interfaces.

Select alternate configuration 0 for all interfaces.

Auxiliary function that clears settings for all interfaces leaving them enabled.

Call interface event handlers and stop when served.

Call event handlers from instances as long as we get result different than NRF_ERROR_NOT_SUPPORTED

Parameters

[in]

p_event

Event structure to send.

Returns

Operation status or NRF_ERROR_NOT_SUPPORTED if none of instances in the list can support given event.

Add class instance.

This function connects given instance into internal class instance chain and into all required endpoints. The instance event handler would be connected into endpoint by default, but this can be overwritten by app_usbd_ep_handler_set .

After successful attachment APP_USBD_EVT_INST_APPEND would be passed to class instance.

Note

This function can only be called after USBD library is initialized but still disabled. Assertion would be generated otherwise.

Parameters

[in,out]

p_cinst

Instance to connect. Chain data would be written into writable instance data.

Return values

NRF_SUCCESS	Instance successfully added.
NRF_ERROR_BUSY	Endpoint(s) not available.

Find a specified descriptor.

Parameters

[in]	p_cinst	Class instance.
[in]	desc_type	Descriptor type app_usbd_descriptor_t
[in]	desc_index	Descriptor index.
[out]	p_desc	Pointer to escriptor.
[out]	p_desc_len	Length of descriptor.

Returns

Standard error code ret_code_t

Return values

NRF_SUCCESS	Descriptor successfully found.
NRF_ERROR_NOT_FOUND	Descriptor not found.

Get first class instance in the list.

Get first instance from the list of active class instances. That instance may be used then in app_usbd_class_next_get function.

Returns

First instance in the list or NULL if there are no instances available.

Get next instance in the list.

Get the next instance from the list of active instances. Used to iterate through all instances.

Parameters

[in]

p_cinst

The current instance from with next one is required.

Returns

Next instance to the given one or NULL if there is no more instances in the list.

Remove class instance.

Instance is removed from instance chain. Instance and event handlers are removed also from endpoints. Endpoints used by by the class instance are left disabled.

Note

This function can only be called after USBD library is initialized but still disabled. Assertion would be generated otherwise.

Parameters

p_cinst

Instance pointer to remove.

Return values

NRF_SUCCESS	Instance successfully removed.
NRF_ERROR_NOT_FOUND	Instance not found in the instance chain.

Remove all class instances.

This function basically calls app_usbd_class_remove on instances chain as long as there is any element left.

Note

This function can only be called after USBD library is initialized but still disabled. Assertion would be generated otherwise.

See Also

app_usbd_class_remove

Returns

Is should always return NRF_SUCCESS . Any error value returned would mean there is an error inside the library.

Check if there is any class with remote wakeup.

The function checks internal registered class with remote wakeup counter.

See Also

app_usbd_class_rwu_register , app_usbd_class_rwu_unregister

Return values

true	The remote wakeup functionality is required by some class instance.
false	There is no class instance that requires wakeup functionality.

Register class on remote wake-up feature.

Parameters

[in]

p_inst

Instance of the class.

Return values

NRF_SUCCESS

Instance that requires remote wake-up registered.

Unregister class from remote wake-up feature.

Parameters

[in]

p_inst

Instance of the class.

Return values

NRF_SUCCESS

Instance that requires remote wake-up removed.

Get first instance in SOF list.

Start iteration through the list of instances that require SOF event processing.

Returns

First instance in the list or NULL if the list is empty.

See Also

app_usbd_class_first_get

Get first instance in SOF interrupt list.

Start iteration through the list of instances that require SOF processing in interrupt.

Returns

First instance in the list or NULL if the list is empty.

See Also

app_usbd_class_first_get

Get next instance in the SOF interrupt list.

Get the next instance from the list of instances requiring SOF processing in interrupt. Used to iterate through all SOF instances that have SOF handlers.

Parameters

p_cinst

The current instance from with next one is required.

Returns

Next instance to the given one or NULL if there is no more instances in the list.

Register class instance as the one that requires SOF events in interrupt.

This function should be called in reaction on APP_USBD_EVT_INST_APPEND event. Connect the class instance to the list of instances that requires SOF processing. If none of the appended instances requires SOF event - it is disabled.

Parameters

p_cinst	Instance that requires SOF event.
handler	Handler to SOF event

Return values

NRF_SUCCESS

Instance linked into SOF processing list.

See Also

app_usbd_class_sof_interrupt_unregister

Unregister class instance from SOF processing in interrupt instances list.

Every class that calls app_usbd_class_sof_interrupt_register have to call also unregistering function in reaction to APP_USBD_EVT_INST_REMOVE event.

Parameters

p_cinst

Instance to be unregistered from SOF processing in interrupt list.

Return values

NRF_SUCCESS	Instance linked into SOF processing in interrupt list.
NRF_ERROR_NOT_FOUND	Instance not found in the SOF processing in interrupt list.

See Also

app_usbd_class_sof_interrupt_register

Get next instance in the SOF list.

Get the next instance from the list of instances requiring SOF event processing. Used to iterate through all SOF instances.

Parameters

p_cinst

The current instance from with next one is required.

Returns

Next instance to the given one or NULL if there is no more instances in the list.

Register class instance as the one that requires SOF events.

This function should be called in reaction on APP_USBD_EVT_INST_APPEND event. Connect the class instance to the list of instances that requires SOF processing. If none of the appended instances requires SOF event - it is disabled.

Parameters

p_cinst

Instance that requires SOF event.

Return values

NRF_SUCCESS

Instance linked into SOF processing list.

See Also

app_usbd_class_sof_unregister

Unregister class instance from SOF processing instances list.

Every class that calls app_usbd_class_sof_register have to call also unregistering function in reaction to APP_USBD_EVT_INST_REMOVE event.

Parameters

p_cinst

Instance to be unregistered from SOF event processing list.

Return values

NRF_SUCCESS	Instance linked into SOF processing list.
NRF_ERROR_NOT_FOUND	Instance not found in the SOF processing list.

See Also

app_usbd_class_sof_register

Disable USBD.

Disabled USDB peripheral cannot be accessed but also stops requesting High Frequency clock and releases power regulator.

Note

This function cannot be called when USB is started. Stop it first.

Enable USBD.

USBD is enabled. Since now the high frequency clock may be requested when USB RESET would be detected.

Call endpoint event handler.

Call event handler for the selected endpoint.

Parameters

[in]	ep	Endpoint number.
[in]	p_event	Event structure to send.

Returns

Operation status.

Disable selected endpoint.

Parameters

ep	Endpoint number.

Enable selected endpoint.

Selected endpoint is enabled and cleared.

Parameters

ep	Endpoint number.

Set up an endpoint handled transfer.

Configures a transfer handled by the feedback function.

Parameters

ep	Endpoint number.
p_handler	Function called when the next chunk of data is requested.

Return values

NRF_ERROR_INVALID_STATE

The state of the USB device does not allow data transfer on the endpoint.

Returns

Values returned by nrf_drv_usbd_ep_handled_transfer .

Change endpoint handler.

This function may be called for the endpoint only if the class instance is already properly attached by the app_usbd_class_append function.

The endpoint event handler function can be only overwritten by the class instance that was connected into the endpoint.

Note

This function can only be called after USBD library is initialized but still disabled. Assertion would be generated otherwise.

Parameters

[in]	p_cinst	Instance of a class that wish to set new event handler. It has to match currently configured instance for the selected endpoint. In other situation error would be returned.
[in]	ep	Endpoint address to configure.
[in]	handler	Event handler function to set.

Return values

NRF_SUCCESS	New handler successfully set
NRF_ERROR_INVALID_PARAM	p_cinst is not the same as currently set for the endpoint

Endpoint transfer.

Parameters

ep	Endpoint number.
p_transfer	Description of the transfer to be performed. The direction of the transfer is determined by the endpoint number.

Return values

NRF_ERROR_INVALID_STATE

The state of the USB device does not allow data transfer on the endpoint.

Returns

Values returned by nrf_drv_usbd_ep_transfer .

See Also

app_usbd_ep_handled_transfer

USBD event processor.

Function to be called on each event to be processed by the library.

Function that process events from the queue.

Note

This function calls app_usbd_event_execute internally.

Return values

true	Event was processed.
false	The event queue is empty.

Call interface event handler.

Call event handler for selected interface.

Parameters

[in,out]	p_class_inst	Class instance that holds selected interface.
[in]	iface_idx	Index of the interface in class structure.
[in]	p_event	Event structure to be processed.

Returns

Operation status.

Deselect interface.

Disable the given interface. This function calls class interface deselection function or default interface selection function.

After calling this function all the endpoints from the interface have to be disabled.

Parameters

[in,out]	p_inst	Instance of the class.
[in]	iface_idx	Index of the interface inside class structure.

Search for selected interface.

Function searches for the given interface number and returns the class that contains it. Optionally it can return interface index inside class instance.

Parameters

[in]	iface	Interface number.
[out]	p_iface_idx	Pointer to a variable that would hold interface index inside returned class instance.

Returns

Pointer to the class structure that cointain given interface or NULL if not found.

Select interface.

Select the given interface. This function calls class interface selection function or default interface selection function.

After calling this function interface should be functional.

Parameters

[in,out]	p_inst	Instance of the class.
[in]	iface_idx	Index of the interface inside class structure.
[in]	alternate	Alternate setting that should be selected.

Returns

Standard error code.

Get selected interface.

Function retieves currently selected interface. If the class contains app_usbd_class_methods_t::iface_selection_get it is called. It it does not contain this function this function would return default, 0 value.

Parameters

[in]	p_inst	Instance of the class.
[in]	iface_idx	Index of the interface inside class structure.

Returns

Selected alternate interface setting.

USB library initialization.

Call this function before any configuration or class attachment. USBD peripheral would be ready to accept commands, and library would be ready, but it would not be connected to the bus. Call app_usbd_enable to enable USBD communication with the host.

Parameters

p_config

Configuration. NULL pointer might be passed here and default configuration will be applied then.

Standard set interface request handle.

This function should be called when processing SET_INTERFACE request.

Parameters

[in]	p_cinst	Instance of a class.
[in]	iface	Interface number.

Returns

Standard error code.

Note

Selected interface to reset has to be part of given class.

Function to start USB related power events processing.

This function should be called after app_usbd_init and after all the required classes were appended ( app_usbd_class_append ).

Return values

NRF_SUCCESS	Power events successfully initialized.
NRF_ERROR_INVALID_STATE	The state of the driver does not allow to enable the power events processing.

Timestamp function for the logger.

Returns

Current frame number taken directly from the last processed SOF.

Request USBD to start.

The function sends start request to the event queue. If the queue is enabled ( APP_USBD_CONFIG_EVENT_QUEUE_ENABLE ) it would be processed when the queue is processed. If queue is disabled it would be processed immediately inside this function. It means that if queue is disabled this function cannot be called from interrupt with priority higher than USB interrupt.

When start is processed it would:

1. Start library.
2. Enable interrupts.
3. Enable USB pull-ups.

Note

In some specific circumstances the library can be left not started and this function would silently exit. This may happen if some glitches appears on USB power line or if the plug was disconnected before whole starting process finishes. User would get the event from POWER peripheral then. Also no APP_USBD_EVT_STARTED event would be generated to the classes and user event handler. For the safe code it is recommended to wait for APP_USBD_EVT_STARTED event if anything has to be initialized after USB driver is started (just before enabling the interrupts). If library is properly started the APP_USBD_EVT_STARTED event passed to the user handler from this function body.

Stop USB.

The function sends stop request to the event queue. If the queue is enabled ( APP_USBD_CONFIG_EVENT_QUEUE_ENABLE ) it would be processed when the queue is processed. If queue is disabled it would be processed immediately inside this function. It means that if queue is disabled this function cannot be called from interrupt with priority higher than USB interrupt.

When the event is processed interrupts and USB pull-ups are disabled. The peripheral itself is left enabled so it can be programmed, but a HOST sees it as a peripheral disconnection.

Note

If the library is not started when this function is called it exits silently - also no APP_USBD_EVT_STOPPED is generated.

Request library to suspend.

This function send suspend request to the event queue.

Note

This function should only be called after APP_USBD_EVT_DRV_SUSPEND os received. Internal suspend request processing would give no effect if the bus is not in suspend state.

USB library un-initialization.

Note

Currently not supported.

Request library to wake-up.

This function send wakeup request to the event queue.

Note

Calling this function does not mean that peripheral is active - the wakeup request is sent into message queue and needs to be processed.

Return values

true	Wakeup generation has been started.
false	No wakeup would be generated becouse it is disabled by the host.