USB Libraries Help > USB Device Libraries > USB Device Layer Library > Library Interface > g) Data Types and Constants > USB_DEVICE_EVENT Enumeration
MPLAB Harmony USB Stack
USB_DEVICE_EVENT Enumeration

USB Device Layer Events. 

This enumeration lists the possible events that the device layer can generate. The client should register an event handler of the type USB_DEVICE_EVENT_HANDLER to receive device layer events. The contents of pData in the event handler depends on the generated event. Refer to the description of the event for details on data provided along with that event. The events generated are device layer instance specific. 

The client will receive control transfers for handling from the device layer, where the recipient field of the Control Transfer Setup packet is set to Other. The client can use the control transfer events and the Device Layer control transfer functions to complete such control transfers. 

It is not mandatory for the client application to handle the control transfer event within the event handler. Indeed, it may be possible that the data stage of the control transfer requires extended processing. Because the event handler executes in an interrupt context, it is recommended to keep the processing in the event handler to a minimum. The client application can call the USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive and USB_DEVICE_ControlStatus functions after returning from the event handler, thus deferring the control transfer event handling and responses. 

Note that a USB host will typically wait for control transfer response for a finite time duration before timing out and canceling the transfer and associated transactions. Even when deferring response, the application must respond promptly if such timeouts have to be avoided. 

The client must use the USB_DEVICE_EventHandlerSet function to register the event handler call back function. The following code example shows the handling of the USB Device Layer Events. 

 

USB_DEVICE_EVENT_RESPONSE APP_USBDeviceEventHandler
(
    USB_DEVICE_EVENT event,
    void * pData, 
    uintptr_t context
)
{
    uint8_t     activeConfiguration;
    uint16_t    frameNumber;
    USB_SPEED   attachSpeed;
    USB_SETUP_PACKET * setupEventData;

    // Handling of each event
    switch(event)
    {
        case USB_DEVICE_EVENT_POWER_DETECTED:
            
            // This means the device detected a valid VBUS voltage and is
            // attached to the USB. The application can now call
            // USB_DEVICE_Attach() function to enable D+/D- pull up
            // resistors. 
            break;

        case USB_DEVICE_EVENT_POWER_REMOVED:
            
            // This means the device is not attached to the USB.
            // The application should now call the USB_DEVICE_Detach()
            // function.
            break;

        case USB_DEVICE_EVENT_SUSPENDED:
            
            // The bus is idle. There was no activity detected.
            // The application can switch to a low power mode after
            // exiting the event handler.
            break;

        case USB_DEVICE_EVENT_SOF:

            // A start of frame was received. This is a periodic event and
            // can be used by the application for timing related activities.
            // pData will point to a USB_DEVICE_EVENT_DATA_SOF type data
            // containing the frame number. In USB Device Stack, this
            // event is generated if USB_DEVICE_SOF_EVENT_ENABLE is
            // defined in System Configuration.

            frameNumber = ((USB_DEVICE_EVENT_DATA_SOF *)pData)->frameNumber;
            break;

        case USB_DEVICE_EVENT_RESET :

            // Reset signaling was detected on the bus. The 
            // application can find out the attach speed.
            
            attachSpeed = USB_DEVICE_ActiveSpeedGet(usbDeviceHandle);
            break;

        case USB_DEVICE_EVENT_DECONFIGURED :
            
            // This indicates that host has deconfigured the device i.e., it
            // has set the configuration as 0. All function driver instances
            // would have been deinitialized.
            
            break;

        case USB_DEVICE_EVENT_ERROR :

            // This means an unknown error has occurred on the bus.
            // The application can try detaching and attaching the
            // device again.
            break;

        case USB_DEVICE_EVENT_CONFIGURED :

            // This means that device is configured and the application can
            // start using the device functionality. The application must
            // register function driver event handlersI have one device
            // level event.  The pData parameter will be a pointer to a
            // USB_DEVICE_EVENT_DATA_CONFIGURED data type that contains the
            // active configuration number.

            activeConfiguration = ((USB_DEVICE_EVENT_DATA_CONFIGURED *)pData)->configurationValue;
            break;
            
        case USB_DEVICE_EVENT_RESUMED:

            // This means that the resume signaling was detected on the
            // bus. The application can bring the device out of power
            // saving mode.

            break;
        
        case USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST:

            // This means that the setup stage of the control transfer is in
            // progress and a setup packet has been received. The pData
            // parameter will point to a USB_SETUP_PACKET data type The
            // application can process the command and update its control
            // transfer state machine. The application for example could call
            // the USB_DEVICE_ControlReceive function (as shown here) to
            // submit the buffer that would receive data in case of a
            // control read transfer.

            setupEventData = (USB_SETUP_PACKET *)pData;

            // Submit a buffer to receive 32 bytes in the  control write transfer.
            USB_DEVICE_ControlReceive(usbDeviceHandle, data, 32); 
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // This means that data in the data stage of the control write
            // transfer has been received. The application can either accept
            // the received data by calling the USB_DEVICE_ControlStatus
            // function with USB_DEVICE_CONTROL_STATUS_OK flag (as shown in
            // this example) or it can reject it by calling the
            // USB_DEVICE_ControlStatus function with
            // USB_DEVICE_CONTROL_STATUS_ERROR flag. 

            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT:
            
            // This means that data in the data stage of the control
            // read transfer has been sent. 

            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED:

            // This means the host has aborted the control transfer. The
            // application can reset its control transfer state machine.
            
            break;

        case USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE:

            // This means schedule endpoint read operation has completed.
            // The application should interpret pData as a pointer to 
            // a USB_DEVICE_EVENT_DATA_ENDPOINT_READ_COMPLETE type.
            
            break;
        
        case USB_DEVICE_EVENT_ENDPOINT_WRITE_COMPLETE:

            // This means schedule endpoint write operation has completed.
            // The application should interpret pData as a pointer to 
            // a USB_DEVICE_EVENT_DATA_ENDPOINT_WRITE_COMPLETE type.
            
            break;

        case USB_DEVICE_EVENT_SET_DESCRIPTOR:
            
            // This means the Host has sent a Set Descriptor request. The
            // application should interpret pData as a
            // USB_DEVICE_EVENT_DATA_SET_DESCRIPTOR pointer type containing the
            // details of the Set Descriptor request. In USB Device
            // Stack, this event is generated if 
            // USB_DEVICE_SET_DESCRIPTOR_EVENT_ENABLE is defined in the
            // system configuration. The application can use
            // USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive and/or
            // the USB_DEVICE_ControlStatus functions to complete the
            // control transfer.

            break;

        case USB_DEVICE_EVENT_SYNCH_FRAME:

            // This means the host has sent a Sync Frame Request. The
            // application should interpret pData as a
            // USB_DEVICE_EVENT_DATA_SYNCH_FRAME pointer type. In USB Device
            // Stack, this event is generated if 
            // USB_DEVICE_SYNCH_FRAME_EVENT_ENABLE is defined in the
            // system configuration. The application should respond be
            // sending the 2 byte frame number using the
            // USB_DEVICE_ControlSend function. 

            USB_DEVICE_ControlSend(usbDeviceHandle, &frameNumber, 2);
            break;

        default:
            break;
    }

    return USB_DEVICE_EVENT_RESPONSE_NONE;
}
C
typedef enum {
  USB_DEVICE_EVENT_RESET,
  USB_DEVICE_EVENT_SUSPENDED,
  USB_DEVICE_EVENT_RESUMED,
  USB_DEVICE_EVENT_ERROR,
  USB_DEVICE_EVENT_SOF,
  USB_DEVICE_EVENT_CONFIGURED,
  USB_DEVICE_EVENT_DECONFIGURED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST,
  USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT,
  USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE,
  USB_DEVICE_EVENT_ENDPOINT_WRITE_COMPLETE,
  USB_DEVICE_EVENT_SET_DESCRIPTOR,
  USB_DEVICE_EVENT_SYNCH_FRAME
} USB_DEVICE_EVENT;
Members
Members 
Description 
USB_DEVICE_EVENT_RESET 
USB bus reset occurred. This event is an indication to the application client that device layer has deinitialized all function drivers. The application should not use the function drivers in this state. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_SUSPENDED 
This event is an indication to the application client that device is suspended and it can put the device to sleep mode if required. Power saving routines should not be called in the event handler. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_RESUMED 
This event indicates that device has resumed from suspended state. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_ERROR 
This event is an indication to the application client that an error occurred on the USB bus. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_SOF 
This event is generated at every start of frame detected on the bus. Application client can use this SOF event for general time based house keeping activities. The pData parameter in the event handler function will point to a USB_DEVICE_EVENT_DATA_SOF type that contains the frame number. 
USB_DEVICE_EVENT_CONFIGURED 
This event is an indication to the application client that device layer has initialized all function drivers and application can set the event handlers for the function drivers. The pData parameter will point to a USB_DEVICE_EVENT_DATA_CONFIGURED data type that contains configuration set by the host. 
USB_DEVICE_EVENT_DECONFIGURED 
The host has deconfigured the device. This happens when the host sends a Set Configuration request with configuration number 0. The device layer will deinitialize all function drivers and then generate this event. 
USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED 
An on-going control transfer was aborted. The application can use this event to reset its control transfer state machine. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED 
The data stage of a Control write transfer has completed. This event occurs after the application has used the USB_DEVICE_ControlReceive function to receive data in the control transfer. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST 
A setup packet of a control transfer has been received. The recipient field of the received setup packet is Other. The application can initiate the data stage using the USB_DEVICE_ControlReceive and USB_DEVICE_ControlSend function. It can end the control transfer by calling the USB_DEVICE_ControlStatus function. The pData parameter in the event handler will point to USB_SETUP_PACKET data type. 
USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT 
The data stage of a Control read transfer has completed. This event occurs after the application has used the USB_DEVICE_ControlSend function to send data in the control transfer. The pData parameter in the event handler function will be NULL. 
USB_DEVICE_EVENT_ENDPOINT_READ_COMPLETE 
This event occurs when a endpoint read transfer scheduled using the USB_DEVICE_EndpointRead function has completed. The pData parameter in the event handler function will be a pointer to a USB_DEVICE_EVENT_DATA_ENDPOINT_READ_COMPLETE data type. 
USB_DEVICE_EVENT_ENDPOINT_WRITE_COMPLETE 
This event occurs when a endpoint write transfer scheduled using the USB_DEVICE_EndpointWrite function has completed. The pData parameter in the event handler function will be a pointer to a USB_DEVICE_EVENT_DATA_ENDPOINT_WRITE_COMPLETE data type. 
USB_DEVICE_EVENT_SET_DESCRIPTOR 
A SET_DESCRIPTOR request is received. This event occurs when Host sends a SET_DESCRIPTOR request. The pData parameter in the event handler function will be a pointer to a USB_DEVICE_EVENT_DATA_SET_DESCRIPTOR data type. The application should initiate the data stage using the USB_DEVICE_ControlReceive function. In the USB Device Stack, this event is generated if USB_DEVICE_EVENT_ENABLE_SET_DESCRIPTOR is defined in the system configuration. 
USB_DEVICE_EVENT_SYNCH_FRAME 
A SYNCH_FRAME request is received. This event occurs when Host sends a SYNCH_FRAME request. The pData parameter in the event handler function will be a pointer to a USB_DEVICE_EVENT_DATA_SYNCH_FRAME data type. The application should initiate the data stage using the USB_DEVICE_ControlSend function. In the USB Device Stack, this event is generated if USB_DEVICE_EVENT_ENABLE_SYNCH_FRAME is defined in the system configuration. 
Remarks

Generation of some events required the definition of configuration macros. Refer to the event specific description for more details.