Modules | Typedefs | Functions

Public API

Modules

 Descriptor Items
 

Items defined by the application which are involved in the enumeration of the device.


 Static Callbacks
 

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


 USB CDC Class Enumerations and Descriptors
 

Packet structs, constants, and callback functions implementing the "Universal Serial Bus Class Definitions for Communication Devices" (commonly the USB CDC Specification), version 1.1.


 USB Chapter 9 Enumerations and Descriptors
 

Packet structs from Chapter 9 of the USB spec which deals with device enumeration.


 USB HID Class Enumerations and Descriptors
 

Packet structs from the Device Class Definition for Human Interface Devices (commonly the USB HID Specification), version 1.11, chapter 6.


 Microsoft-Specific Descriptors
 

Packet structs from Microsoft's documentation which deal with the Microsoft OS String Descriptor and the Extended Compat Descriptors.


 USB MSC Class Enumerations and Descriptors
 

Packet structs, constants, and callback functions implementing the "Universal Serial Bus Mass Storage Class", revision 1.4, and the "Universal Serial Bus Mass Storage Class Bulk-Only Transport", revision 1.0.


Typedefs

typedef int8_t(* usb_ep0_data_stage_callback )(bool data_ok, void *context)
 Endpoint 0 data stage callback definition.

Functions

void usb_init (void)
 Initialize the USB library and hardware.
void usb_service (void)
 Update the USB library and hardware.
uint8_t usb_get_configuration (void)
 Get the device configuration.
unsigned char * usb_get_in_buffer (uint8_t endpoint)
 Get a pointer to an endpoint's input buffer.
void usb_send_in_buffer (uint8_t endpoint, size_t len)
 Send an endpoint's IN buffer to the host.
bool usb_in_endpoint_busy (uint8_t endpoint)
 Check whether an IN endpoint is busy.
uint8_t usb_halt_ep_in (uint8_t ep)
 Halt an IN endpoint.
bool usb_in_endpoint_halted (uint8_t endpoint)
 Check whether an endpoint is halted.
bool usb_out_endpoint_has_data (uint8_t endpoint)
 Check whether an OUT endpoint has received data.
void usb_arm_out_endpoint (uint8_t endpoint)
 Re-enable reception on an OUT endpoint.
uint8_t usb_halt_ep_out (uint8_t ep)
 Halt an OUT endpoint.
bool usb_out_endpoint_halted (uint8_t endpoint)
 Check whether an OUT endpoint is halted.
uint8_t usb_get_out_buffer (uint8_t endpoint, const unsigned char **buffer)
 Get a pointer to an endpoint's OUT buffer.
void usb_start_receive_ep0_data_stage (char *buffer, size_t len, usb_ep0_data_stage_callback callback, void *context)
 Start the data stage of an OUT control transfer.
void usb_send_data_stage (char *buffer, size_t len, usb_ep0_data_stage_callback callback, void *context)
 Start the data stage of an IN control transfer.

Typedef Documentation

typedef int8_t(* usb_ep0_data_stage_callback)(bool data_ok, void *context)

Endpoint 0 data stage callback definition.

This is the callback function type expected to be passed to usb_start_receive_ep0_data_stage() and usb_send_data_stage().

For OUT transfers with data, the callback function will be called by the stack when the data stage of the transfer completes. For this type of transfer, the callback can return -1 or 0: -1: The application has rejected the data. This will cause the stack to send a STALL to the host. 0: The application has accepted and processed the data. This will cause the stack to send a zero-length packet (indicating success) to be sent as the status stage.

For OUT transfers without data (which do not have a data stage), the callback function will be called when the status stage of the transfer completes; the return value is ignored.

For IN transfers, the callback function will be called by the stack when the status stage of the transfer completes; the return value is ignored.

Note that the functionality is different for different types of transfers. The callback gets called at the place which which has the most meaning for each type of transfer.

Parameters:
data_okTrue if transaction(s) completed successfully, or false if there was an error
contextA pointer to application-provided context data
Returns:
For OUT transfers with data, -1 or 0 can be returned as described.

For IN transfers and for OUT transfers without data, the return value is ignored.


Function Documentation

void usb_arm_out_endpoint ( uint8_t  endpoint )

Re-enable reception on an OUT endpoint.

Re-enable reception on the specified endpoint. Call this function after usb_out_endpoint_has_data() indicated that there was data available, and after the application has dealt with the data. Calling this function gives the specified OUT endpoint's buffer back to the USB stack to receive the next transaction.

Parameters:
endpointThe endpoint requested
uint8_t usb_get_configuration ( void   )

Get the device configuration.

Get the device configuration as set by the host. If the device is not in the CONFIGURED state, 0 will be returned.

See also:
usb_is_configured()
Returns:
Return the device configuration or 0 if the device is not configured.
unsigned char* usb_get_in_buffer ( uint8_t  endpoint )

Get a pointer to an endpoint's input buffer.

This function returns a pointer to an endpoint's input buffer. Call this to get a location to copy IN data to in order to send it to the host. Remember that IN data is data which goes from the device to the host. The maximum length of this buffer is defined by the application in usb_config.h (eg: EP_1_IN_LEN). It is wise to call usb_in_endpoint_busy() before calling this function.

Parameters:
endpointThe endpoint requested
Returns:
Return a pointer to the endpoint's buffer.
uint8_t usb_get_out_buffer ( uint8_t  endpoint,
const unsigned char **  buffer 
)

Get a pointer to an endpoint's OUT buffer.

Call this function to get a pointer to an endpoint's OUT buffer after usb_out_endpoint_has_data() returns true (indicating that an OUT transaction has been received). Do not call this function if usb_out_endpoint_has_data() does not return true.

Parameters:
endpointThe endpoint requested
bufferA pointer to a pointer which will be set to the endpoint's OUT buffer.
Returns:
Return the number of bytes received.
uint8_t usb_halt_ep_in ( uint8_t  ep )

Halt an IN endpoint.

Set the ENDPOINT_HALT condition on an IN endpoint. Do not call this on endpoint zero.

Parameters:
endpointThe endpoint requested
Returns:
Return 0 if the endpoint can be halted, or -1 if the endpoint number is invalid.
uint8_t usb_halt_ep_out ( uint8_t  ep )

Halt an OUT endpoint.

Set the ENDPOINT_HALT condition on an OUT endpoint. Do not call this on endpoint zero.

Parameters:
endpointThe endpoint requested
Returns:
Return 0 if the endpoint can be halted, or -1 if the endpoint number is invalid.
bool usb_in_endpoint_busy ( uint8_t  endpoint )

Check whether an IN endpoint is busy.

An IN endpoint is said to be busy if there is data in its buffer and it is waiting for an IN token from the host in order to send it (or if it is in the process of sending the data).

Parameters:
endpointThe endpoint requested
Returns:
Return true if the endpoint is busy, or false if it is not.
bool usb_in_endpoint_halted ( uint8_t  endpoint )

Check whether an endpoint is halted.

Check if an endpoint has been halted by the host. If an endpoint is halted, don't call usb_send_in_buffer().

See also:
ENDPOINT_HALT_CALLBACK.
Parameters:
endpointThe endpoint requested
Returns:
Return true if the endpointed is halted, or false if it is not.
void usb_init ( void   )

Initialize the USB library and hardware.

Call this function at the beginning of execution. This function initializes the USB peripheral hardware and software library. After calling this funciton, the library will handle enumeration automatically when attached to a host.

bool usb_out_endpoint_halted ( uint8_t  endpoint )

Check whether an OUT endpoint is halted.

Check if an endpoint has been halted by the host. If an OUT endpoint is halted, the USB stack will automatically return STALL in response to any OUT tokens.

See also:
ENDPOINT_HALT_CALLBACK.
Parameters:
endpointThe endpoint requested
Returns:
Return true if the endpointed is halted, or false if it is not.
bool usb_out_endpoint_has_data ( uint8_t  endpoint )

Check whether an OUT endpoint has received data.

Check if an OUT endpoint has completed a transaction and has received data from the host. If it has, the application should call usb_get_out_buffer() to get the data and then call usb_arm_out_endpoint() to enable reception of the next transaction.

Parameters:
endpointThe endpoint requested
Returns:
Return true if the endpoint has received data, false if it has not.
void usb_send_data_stage ( char *  buffer,
size_t  len,
usb_ep0_data_stage_callback  callback,
void *  context 
)

Start the data stage of an IN control transfer.

Start the data stage of a control transfer for a transfer which has an IN data stage. Call this from UNKNOWN_SETUP_REQUEST_CALLBACK for IN control transfers which are being handled by the application. Once the transfer has completed, callback will be called with the context pointer provided. The buffer should be considered to be owned by the USB stack until the callback is called and should not be modified by the application until this time. Do not pass in a buffer which is on the stack. The data will automatically be split into as many transactions as necessary to complete the transfer.

See also:
UNKNOWN_SETUP_REQUEST_CALLBACK
Parameters:
bufferA buffer containing the data to send. This should be a buffer capable of having an arbitrary lifetime. Do not use a stack variable for this buffer, and do not free this buffer until the callback has been called.
lenThe number of bytes to send
callbackA callback function to call when the transfer completes. This parameter is mandatory. Once the callback is called, the transfer is over, and the buffer can be considered to be owned by the application again. A pointer to be passed to the callback. The USB stack does not dereference this pointer.
void usb_send_in_buffer ( uint8_t  endpoint,
size_t  len 
)

Send an endpoint's IN buffer to the host.

Send the data in the IN buffer for the specified endpoint to the host. Since USB is a polled bus, this only queues the data for sending. It will actually be sent when the device receives an IN token for the specified endpoint. To check later whether the data has been sent, call usb_in_endpoint_busy(). If the endpoint is busy, a transmission is pending, but has not been actually transmitted yet.

Parameters:
endpointThe endpoint on which to send data
lenThe amount of data to send
void usb_service ( void   )

Update the USB library and hardware.

This function services the USB peripheral's interrupts and handles all tasks related to enumeration and transfers. It is non-blocking. Whether an application should call this function depends on the USB_USE_INTERRUPTS define. If USB_USE_INTERRUPTS is not defined, this function should be called periodically from the main application. If USB_USE_INTERRUPTS is defined, it should be called from interrupt context. On PIC24, this will happen automatically, as the interrupt handler is embedded in usb.c. On 8-bit PIC since the interrupt handlers are shared, this function will need to be called from the application's interrupt handler.

void usb_start_receive_ep0_data_stage ( char *  buffer,
size_t  len,
usb_ep0_data_stage_callback  callback,
void *  context 
)

Start the data stage of an OUT control transfer.

Start the data stage of a control transfer for a transfer which has an OUT data stage. Call this from UNKNOWN_SETUP_REQUEST_CALLBACK for OUT control transfers which being handled by the application. Once the transfer has completed, callback will be called with the context pointer provided. The buffer should be considered to be owned by the USB stack until the callback is called and should not be modified by the application until this time.

See also:
UNKNOWN_SETUP_REQUEST_CALLBACK
Parameters:
bufferA buffer in which to place the data
lenThe number of bytes to expect. This must be less than or equal to the number of bytes in the buffer, and for proper setup packets will be the wLength parameter.
callbackA callback function to call when the transfer completes. This parameter is mandatory. Once the callback is called, the transfer is over, and the buffer can be considered to be owned by the application again.
contextA pointer to be passed to the callback. The USB stack does not dereference this pointer
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator