Functions

Static Callbacks
[Public API]

Optional static callback macros to be defined in the application's usb_config.h. More...

Functions

void SET_CONFIGURATION_CALLBACK (uint8_t configuration)
 Callback for SET_CONFIGURATION requests.
uint16_t GET_DEVICE_STATUS_CALLBACK ()
 Callback for GET_STATUS requests.
void ENDPOINT_HALT_CALLBACK (uint8_t endpoint, bool halted)
 Callback for SET_FEATURE or CLEAR_FEATURE with ENDPOINT_HALT.
int8_t SET_INTERFACE_CALLBACK (uint8_t interface, uint8_t alt_setting)
 Callback for the SET_INTERFACE request.
int8_t GET_INTERFACE_CALLBACK (uint8_t interface)
 Callback for the GET_INTERFACE request.
void OUT_TRANSACTION_CALLBACK (uint8_t endpoint)
 Callback for an OUT transaction.
void IN_TRANSACTION_COMPLETE_CALLBACK (uint8_t endpoint)
 Callback for an IN transaction.
int8_t UNKNOWN_SETUP_REQUEST_CALLBACK (const struct setup_packet *pkt)
 Callback for an unrecognized SETUP request.
int16_t UNKNOWN_GET_DESCRIPTOR_CALLBACK (const struct setup_packet *pkt, const void **descriptor)
 Callback for a GET_DESCRIPTOR request for an unknown descriptor.
void START_OF_FRAME_CALLBACK (void)
 Callback for USB Start of Frame event.
void USB_RESET_CALLBACK (void)
 USB Reset Callback.

Detailed Description

Optional static callback macros to be defined in the application's usb_config.h.

If desired, define these callback functions in your application's usb_config.h to receive notification about specific events which happen during enumeration and otherwise. While these are not strictly required for all devices, they may be required depending on your device configuration.


Function Documentation

void ENDPOINT_HALT_CALLBACK ( uint8_t  endpoint,
bool  halted 
)

Callback for SET_FEATURE or CLEAR_FEATURE with ENDPOINT_HALT.

ENDPOINT_HALT_CALLBACK() is called when a SET_FEATURE or CLEAR_FEATURE is received from the host changing the endpoint halt value. This is a notification only. There is no way to reject this request.

endpoint The endpoint identifier of the affected endpoint (direction and number, e.g.: 0x81 means EP 1 IN). halted 1=endpoint_halted (set), 0=endpoint_not_halted (clear)

uint16_t GET_DEVICE_STATUS_CALLBACK (  )

Callback for GET_STATUS requests.

GET_DEVICE_STATUS_CALLBACK() is called when a GET_STATUS request is received from the host for the device (not the interface or the endpoint). The callback is to return the status of the device as a 16-bit unsigned integer per section 9.4.5 of the USB 2.0 specification. Bit 0 (LSB) - 0=bus_powered, 1=self_powered Bit 1 - 0=no_remote_wakeup, 1=remote_wakeup Bits 2-15 - reserved, set to zero.

int8_t GET_INTERFACE_CALLBACK ( uint8_t  interface )

Callback for the GET_INTERFACE request.

GET_INTERFACE_CALLBACK() is called when a GET_INTERFACE request is received from the host. GET_INTERFACE is a request for the current alternate setting selected for a given interface. The application should return the interface's current alternate setting from this callback function. If this callback is not present, zero will be returned as the current alternate setting for all interfaces.

Parameters:
interfaceThe interface queried for current altertate setting
Returns:
Return the current alternate setting for the interface requested or -1 if the interface does not exist.
void IN_TRANSACTION_COMPLETE_CALLBACK ( uint8_t  endpoint )

Callback for an IN transaction.

IN_TRANSACTION_COMPLETE_CALLBACK() is called when an IN transaction has completed on an endpoint numbered 1 through 15, meaning the transaction has successfully been delivered to the host. The application may send another transaction to the host using usb_get_in_buffer() and usb_send_in_buffer() from this callback if desired.

This function is called from interrupt context and should not block.

Parameters:
endpointThe endpoint on which the transfer completed
void OUT_TRANSACTION_CALLBACK ( uint8_t  endpoint )

Callback for an OUT transaction.

OUT_TRANSACTION_CALLBACK() is called when a transaction has completed on an endpoint numbered 1 through 15, that is when data has been received from the host. The application may then get the data received by calling usb_get_out_buffer(), and can then re-arm the endpoint by calling usb_arm_out_endpoint(). The application may choose to not re-arm the endpoint if the application intends to do it at a later time.

This function is called from interrupt context and should not block.

Parameters:
endpointThe endpoint on which the transfer completed
void SET_CONFIGURATION_CALLBACK ( uint8_t  configuration )

Callback for SET_CONFIGURATION requests.

SET_CONFIGURATION_CALLBACK() is called whenever a SET_CONFIGURATION request is received from the host. The configuration parameter is the new configuration the host requests. If configuration is zero, then the device is to enter the ADDRESS state. If it is non-zero then the device is to enter the CONFIGURED state.

There's no way to reject this request. The host commands a configuration be set, and it shall be done.

int8_t SET_INTERFACE_CALLBACK ( uint8_t  interface,
uint8_t  alt_setting 
)

Callback for the SET_INTERFACE request.

SET_INTERFACE_CALLBACK() is called when a SET_INTERFACE request is received from the host. SET_INTERFACE is used to set the alternate setting for the specified interface. The parameters interface and alt_setting come directly from the device request (from the host). The callback should return 0 if the new alternate setting can be set or -1 if it cannot. This callback is completely unnecessary if you only have one alternate setting (alternate setting zero) for each interface.

Parameters:
interfaceThe interface on which to set the alternate setting
alt_settingThe alternate setting
Returns:
Return 0 for success and -1 for error (will send a STALL to the host)
void START_OF_FRAME_CALLBACK ( void   )

Callback for USB Start of Frame event.

START_OF_FRAME_CALLBACK() is called when a USB Start-of-Frame packet is received from the host. For full-speed devices, this happens every 1 millisecond. For high-speed devices, this happens every 125 microseconds. Low-speed devices do not receive a Start-of-Frame packet.

int16_t UNKNOWN_GET_DESCRIPTOR_CALLBACK ( const struct setup_packet pkt,
const void **  descriptor 
)

Callback for a GET_DESCRIPTOR request for an unknown descriptor.

UNKNOWN_GET_DESCRIPTOR_CALLBACK() is called when a GET_DESCRIPTOR request is received from the host for a descriptor which is unrecognized by the USB stack. This could be because it is a vendor-defined descriptor or because it is some other descriptor which is not supported, for example if you were implementing a device class in your application. The callback function should set the descriptor pointer and return the number of bytes in the descriptor. If the descriptor is not supported, the callback should return -1, which will cause a STALL to be sent to the host.

Make sure to include usb_ch9.h in order to use the setup_packet structure.

Parameters:
pktThe SETUP packet with the request in it.
descriptora pointer to a pointer which should be set to the descriptor data.
Returns:
Return the length of the descriptor pointed to by *descriptor, or -1 if the descriptor does not exist.
int8_t UNKNOWN_SETUP_REQUEST_CALLBACK ( const struct setup_packet pkt )

Callback for an unrecognized SETUP request.

UNKNOWN_SETUP_REQUEST_CALLBACK() is called when a SETUP packet is received with a request (bmRequestType,bRequest) which is unknown to the the USB stack. This could be because it is a vendor-defined request or because it is some other request which is not supported, for example if you were implementing a device class in your application. There are four ways to handle this:

0. For unknown requests, return -1. This will send a STALL to the host. 1. For requests which have no data stage, the callback should call usb_send_data_stage() with a length of zero to send a zero-length packet back to the host. 2. For requests which expect an IN data stage, the callback should call usb_send_data_stage() with the data to be sent, and a callback which will get called when the data stage is complete. The callback is required, and the data buffer passed to usb_send_data_stage() must remain valid until the callback is called. 3. For requests which will come with an OUT data stage, the callback should call usb_start_receive_ep0_data_stage() and provide a buffer and a callback which will get called when the data stage has completed. The callback is required, and the data in the buffer passed to usb_start_receive_ep0_data_stage() is not valid until the callback is called.

It is worth noting that only one control transfer can be active at any given time. Once UNKNOWN_SETUP_REQUEST_CALLBACK() has been called, it will not be called again until the next transfer, meaning that if the application-provided UNKNOWN_SETUP_REQUEST_CALLBACK() function performs one of options 1-3 above, the callback function passed to usb_send_data_stage() or usb_start_receive_ep0_data_stage() will be called before UNKNOWN_SETUP_REQUEST_CALLBACK() can be called again. Thus, it is safe to use the same buffer for all control transfers if desired.

Make sure to include usb_ch9.h in order to use the setup_packet structure.

Parameters:
pktThe SETUP packet
Returns:
Return 0 if the SETUP can be handled or -1 if it cannot. Returning -1 will cause STALL to be returned to the host.
void USB_RESET_CALLBACK ( void   )

USB Reset Callback.

USB_RESET_CALLBACK() is called when a reset event is detected on the bus. Two bus resets are part of the normal enumeration sequence. This function is called before the USB stack does any re-initialization.

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator