Hid_mouse_device_class_api

Collaboration diagram for Hid_mouse_device_class_api:

Data Structures
struct	tHIDMouseInstance
struct	tUSBDHIDMouseDevice
struct	PACKED
	USB_CDC_GET/SET_LINE_CODING request-specific data. More...

Macros
#define	NUM_HID_SECTIONS
#define	HID_REPORT_BUTTONS   0
#define	HID_REPORT_X   1
#define	HID_REPORT_Y   2
#define	MOUSE_REPORT_SIZE   3
#define	MOUSE_SUCCESS   0
	This return code from USBDHIDMouseStateChange() indicates success. More...
#define	MOUSE_ERR_TX_ERROR   2
#define	MOUSE_ERR_NOT_CONFIGURED   4
#define	MOUSE_REPORT_BUTTON_1   0x01
#define	MOUSE_REPORT_BUTTON_2   0x02
#define	MOUSE_REPORT_BUTTON_3   0x04

Enumerations
enum	tMouseState { eHIDMouseStateUnconfigured, eHIDMouseStateIdle, eHIDMouseStateWaitData, eHIDMouseStateSend }

Functions
void *	USBDHIDMouseInit (uint32_t ui32Index, tUSBDHIDMouseDevice *psMouseDevice)
void *	USBDHIDMouseCompositeInit (uint32_t ui32Index, tUSBDHIDMouseDevice *psMouseDevice, tCompositeEntry *psCompEntry)
void	USBDHIDMouseTerm (void *pvMouseDevice)
void *	USBDHIDMouseSetCBData (void *pvMouseDevice, void *pvCBData)
uint32_t	USBDHIDMouseStateChange (void *pvMouseDevice, int8_t i8DeltaX, int8_t i8DeltaY, uint8_t ui8Buttons)
void	USBDHIDMousePowerStatusSet (void *pvMouseDevice, uint8_t ui8Power)
bool	USBDHIDMouseRemoteWakeupRequest (void *pvMouseDevice)

Variables
uint8_t	g_pui8MouseDescriptor []
uint8_t	g_pui8HIDInterface [HIDINTERFACE_SIZE]
const uint8_t	g_pui8HIDInEndpoint [HIDINENDPOINT_SIZE]
const tConfigSection	g_sHIDConfigSection
const tConfigSection	g_sHIDInterfaceSection
const tConfigSection	g_sHIDInEndpointSection
tConfigSection	g_sHIDDescriptorSection
const tConfigSection *	g_psHIDSections []
tConfigHeader	g_sHIDConfigHeader
const tConfigHeader *const	g_ppsHIDConfigDescriptors []

Detailed Description

Macro Definition Documentation

NUM_HID_SECTIONS

#define NUM_HID_SECTIONS

Value:

(sizeof(g_psHIDSections) /                    \
                                 sizeof(g_psHIDSections[0]))

HID_REPORT_BUTTONS

#define HID_REPORT_BUTTONS   0

Referenced by USBDHIDMouseStateChange().

HID_REPORT_X

#define HID_REPORT_X   1

Referenced by USBDHIDMouseStateChange().

HID_REPORT_Y

#define HID_REPORT_Y   2

Referenced by USBDHIDMouseStateChange().

MOUSE_REPORT_SIZE

#define MOUSE_REPORT_SIZE   3

Referenced by USBDHIDMouseStateChange().

MOUSE_SUCCESS

#define MOUSE_SUCCESS   0

This return code from USBDHIDMouseStateChange() indicates success.

Referenced by USBDHIDMouseStateChange().

MOUSE_ERR_TX_ERROR

#define MOUSE_ERR_TX_ERROR   2

This return code from USBDHIDMouseStateChange() indicates that an error was reported while attempting to send a report to the host. A client should assume that the host has disconnected if this return code is seen.

Referenced by USBDHIDMouseStateChange().

MOUSE_ERR_NOT_CONFIGURED

#define MOUSE_ERR_NOT_CONFIGURED   4

USBDHIDMouseStateChange() returns this value if it is called before the USB host has connected and configured the device. All mouse state information passed on the call is been ignored.

Referenced by USBDHIDMouseStateChange().

MOUSE_REPORT_BUTTON_1

#define MOUSE_REPORT_BUTTON_1   0x01

Setting this bit in the ui8Buttons parameter to USBDHIDMouseStateChange() indicates to the USB host that button 1 on the mouse is pressed.

MOUSE_REPORT_BUTTON_2

#define MOUSE_REPORT_BUTTON_2   0x02

Setting this bit in the ui8Buttons parameter to USBDHIDMouseStateChange() indicates to the USB host that button 2 on the mouse is pressed.

MOUSE_REPORT_BUTTON_3

#define MOUSE_REPORT_BUTTON_3   0x04

Setting this bit in the ui8Buttons parameter to USBDHIDMouseStateChange() indicates to the USB host that button 3 on the mouse is pressed.

Enumeration Type Documentation

tMouseState

enum tMouseState

Enumerator
eHIDMouseStateUnconfigured
eHIDMouseStateIdle
eHIDMouseStateWaitData
eHIDMouseStateSend

Function Documentation

USBDHIDMouseInit()

void * USBDHIDMouseInit	(	uint32_t	ui32Index,
		tUSBDHIDMouseDevice *	psMouseDevice
	)

Initializes HID mouse device operation for a given USB controller.

Parameters

ui32Index	is the index of the USB controller which is to be initialized for HID mouse device operation.
psMouseDevice	points to a structure containing parameters customizing the operation of the HID mouse device.

An application wishing to offer a USB HID mouse interface to a USB host must call this function to initialize the USB controller and attach the mouse device to the USB bus. This function performs all required USB initialization.

On successful completion, this function returns the psMouseDevice pointer passed to it. This must be passed on all future calls to the HID mouse device driver.

When a host connects and configures the device, the application callback receives USB_EVENT_CONNECTED after which calls can be made to USBDHIDMouseStateChange() to report pointer movement and button presses to the host.

Note

The application must not make any calls to the lower level USB device interfaces if interacting with USB via the USB HID mouse device API. Doing so causes unpredictable (though almost certainly unpleasant) behavior.

Returns

Returns NULL on failure or the psMouseDevice pointer on success.

References g_pui8MouseDescriptor, tUSBDHIDMouseDevice::pfnCallback, tUSBDHIDMouseDevice::ppui8StringDescriptors, tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, tUSBDHIDMouseDevice::ui16MaxPowermA, tUSBDHIDMouseDevice::ui8PwrAttributes, USBDHIDInit(), and USBDHIDMouseCompositeInit().

USBDHIDMouseCompositeInit()

void * USBDHIDMouseCompositeInit	(	uint32_t	ui32Index,
		tUSBDHIDMouseDevice *	psMouseDevice,
		tCompositeEntry *	psCompEntry
	)

Initializes HID mouse device operation for a given USB controller.

Parameters

ui32Index	is the index of the USB controller which is to be initialized for HID mouse device operation.
psMouseDevice	points to a structure containing parameters customizing the operation of the HID mouse device.
psCompEntry	is the composite device entry to initialize when creating a composite device.

This call is very similar to USBDHIDMouseInit() except that it is used for initializing an instance of the HID mouse device for use in a composite device. If this HID mouse is part of a composite device, then the psCompEntry should point to the composite device entry to initialize. This is part of the array that is passed to the USBDCompositeInit() function.

Returns

Returns zero on failure or a non-zero instance value that should be used with the remaining USB HID Mouse APIs.

References eHIDMouseStateUnconfigured, tHIDMouseInstance::iMouseState, tUSBDHIDMouseDevice::pfnCallback, tUSBDHIDDevice::pfnRxCallback, tUSBDHIDMouseDevice::ppui8StringDescriptors, tUSBDHIDDevice::psReportIdle, tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, tHIDMouseInstance::sReportIdle, tUSBDHIDMouseDevice::ui16MaxPowermA, tUSBDHIDDevice::ui16MaxPowermA, tUSBDHIDMouseDevice::ui16PID, tUSBDHIDDevice::ui16PID, tHIDReportIdle::ui16TimeTillNextmS, tUSBDHIDMouseDevice::ui16VID, tUSBDHIDDevice::ui16VID, tHIDReportIdle::ui32TimeSinceReportmS, tHIDReportIdle::ui8Duration4mS, tUSBDHIDDevice::ui8NumInputReports, tHIDMouseInstance::ui8Protocol, tUSBDHIDDevice::ui8Protocol, tUSBDHIDMouseDevice::ui8PwrAttributes, tUSBDHIDDevice::ui8PwrAttributes, tHIDReportIdle::ui8ReportID, tUSBDHIDDevice::ui8Subclass, tHIDMouseInstance::ui8USBConfigured, USB_HID_PROTOCOL_MOUSE, USB_HID_PROTOCOL_REPORT, and USB_HID_SCLASS_BOOT.

Referenced by USBDHIDMouseInit().

USBDHIDMouseTerm()

void USBDHIDMouseTerm

(

void *

pvMouseDevice

)

Shuts down the HID mouse device.

Parameters

pvMouseDevice

is the pointer to the device instance structure.

This function terminates HID mouse operation for the instance supplied and removes the device from the USB bus. Following this call, the pvMouseDevice instance may not me used in any other call to the HID mouse device other than USBDHIDMouseInit().

Returns

None.

References tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, tHIDMouseInstance::ui8USBConfigured, and USBDHIDTerm().

USBDHIDMouseSetCBData()

void * USBDHIDMouseSetCBData	(	void *	pvMouseDevice,
		void *	pvCBData
	)

Sets the client-specific pointer parameter for the mouse callback.

Parameters

pvMouseDevice	is the pointer to the mouse device instance structure.
pvCBData	is the pointer that client wishes to be provided on each event sent to the mouse callback function.

The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnCallback function passed on USBDHIDMouseInit().

If a client wants to make runtime changes in the callback pointer, it must ensure that the pvMouseDevice structure passed to USBDHIDMouseInit() resides in RAM. If this structure is in flash, callback data changes are not possible.

Returns

Returns the previous callback pointer that was set for this instance.

References tUSBDHIDMouseDevice::pvCBData.

USBDHIDMouseStateChange()

uint32_t USBDHIDMouseStateChange	(	void *	pvMouseDevice,
		int8_t	i8DeltaX,
		int8_t	i8DeltaY,
		uint8_t	ui8Buttons
	)

Reports a mouse state change, pointer movement or button press, to the USB host.

Parameters

pvMouseDevice	is the pointer to the mouse device instance structure.
i8DeltaX	is the relative horizontal pointer movement that the application wishes to report. Valid values are in the range [-127, 127] with positive values indicating movement to the right.
i8DeltaY	is the relative vertical pointer movement that the application wishes to report. Valid values are in the range [-127, 127] with positive values indicating downward movement.
ui8Buttons	is a bit mask indicating which (if any) of the three mouse buttons is pressed. Valid values are logical OR combinations of MOUSE_REPORT_BUTTON_1, MOUSE_REPORT_BUTTON_2 and MOUSE_REPORT_BUTTON_3.

This function is called to report changes in the mouse state to the USB host. These changes can be movement of the pointer, reported relative to its previous position, or changes in the states of up to 3 buttons that the mouse may support. The return code indicates whether or not the mouse report could be sent to the host. In cases where a previous report is still being transmitted, MOUSE_ERR_TX_ERROR is returned and the state change is ignored.

Returns

Returns MOUSE_SUCCESS on success, MOUSE_ERR_TX_ERROR if an error occurred while attempting to schedule transmission of the mouse report to the host (typically due to a previous report which has not yet completed transmission or due to disconnection of the host) or MOUSE_ERR_NOT_CONFIGURED if called before a host has connected to and configured the device.

References eHIDMouseStateSend, HID_REPORT_BUTTONS, HID_REPORT_X, HID_REPORT_Y, tHIDMouseInstance::iMouseState, MOUSE_ERR_NOT_CONFIGURED, MOUSE_ERR_TX_ERROR, MOUSE_REPORT_SIZE, MOUSE_SUCCESS, tHIDMouseInstance::pui8Report, tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, tHIDMouseInstance::ui8USBConfigured, USBDHIDReportWrite(), and USBDHIDTxPacketAvailable().

USBDHIDMousePowerStatusSet()

void USBDHIDMousePowerStatusSet	(	void *	pvMouseDevice,
		uint8_t	ui8Power
	)

Reports the device power status (bus- or self-powered) to the USB library.

Parameters

pvMouseDevice	is the pointer to the mouse device instance structure.
ui8Power	indicates the current power status, either USB_STATUS_SELF_PWR or USB_STATUS_BUS_PWR.

Applications which support switching between bus- or self-powered operation should call this function whenever the power source changes to indicate the current power status to the USB library. This information is required by the USB library to allow correct responses to be provided when the host requests status from the device.

Returns

None.

References tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, and USBDHIDPowerStatusSet().

USBDHIDMouseRemoteWakeupRequest()

bool USBDHIDMouseRemoteWakeupRequest

(

void *

pvMouseDevice

)

Requests a remote wake up to resume communication when in suspended state.

Parameters

pvMouseDevice

is the pointer to the mouse device instance structure.

When the bus is suspended, an application which supports remote wake up (advertised to the host via the configuration descriptor) may call this function to initiate remote wake up signaling to the host. If the remote wake up feature has not been disabled by the host, this causes the bus to resume operation within 20mS. If the host has disabled remote wake up, false is returned to indicate that the wake up request was not successful.

Returns

Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function.

References tHIDMouseInstance::sHIDDevice, tUSBDHIDMouseDevice::sPrivateData, and USBDHIDRemoteWakeupRequest().

Variable Documentation

g_pui8MouseDescriptor

uint8_t g_pui8MouseDescriptor[]

Initial value:

=
{
    
    
    
    9,                          
    USB_DTYPE_CONFIGURATION,    
    USBShort(34),               
    1,                          
                                
    1,                          
    5,                          
                                
    USB_CONF_ATTR_SELF_PWR,     
    250,                        
}

Referenced by USBDHIDMouseInit().

g_pui8HIDInterface

uint8_t g_pui8HIDInterface[HIDINTERFACE_SIZE]

Initial value:

=
{
    
    
    
    9,                          
    USB_DTYPE_INTERFACE,        
    0,                          
    0,                          
    1,                          
                                
    USB_CLASS_HID,              
    USB_HID_SCLASS_BOOT,        
    USB_HID_PROTOCOL_MOUSE,     
                                
    4,                          
}

g_pui8HIDInEndpoint

const uint8_t g_pui8HIDInEndpoint[HIDINENDPOINT_SIZE]

Initial value:

=
{
    
    
    
    7,                          
    USB_DTYPE_ENDPOINT,         
    USB_EP_DESC_IN | USBEPToIndex(USB_EP_1),
    USB_EP_ATTR_INT,            
    USBShort(USBFIFOSizeToBytes(USB_FIFO_SZ_64)),
                                
    16,                         
}

g_sHIDConfigSection

const tConfigSection g_sHIDConfigSection

Initial value:

=
{
    sizeof(g_pui8MouseDescriptor),
    g_pui8MouseDescriptor
}

g_sHIDInterfaceSection

const tConfigSection g_sHIDInterfaceSection

Initial value:

=
{
    sizeof(g_pui8HIDInterface),
    g_pui8HIDInterface
}

g_sHIDInEndpointSection

const tConfigSection g_sHIDInEndpointSection

Initial value:

=
{
    sizeof(g_pui8HIDInEndpoint),
    g_pui8HIDInEndpoint
}

g_sHIDDescriptorSection

tConfigSection g_sHIDDescriptorSection

Initial value:

=
{
   sizeof(g_sMouseHIDDescriptor),
   (const uint8_t *)&g_sMouseHIDDescriptor
}

g_psHIDSections

const tConfigSection* g_psHIDSections[]

Initial value:

=
{
    &g_sHIDConfigSection,
    &g_sHIDInterfaceSection,
    &g_sHIDDescriptorSection,
    &g_sHIDInEndpointSection,
}

g_sHIDConfigHeader

tConfigHeader g_sHIDConfigHeader

Initial value:

=
{
    NUM_HID_SECTIONS,
    g_psHIDSections
}

g_ppsHIDConfigDescriptors

const tConfigHeader* const g_ppsHIDConfigDescriptors[]

Initial value:

=
{
    &g_sHIDConfigHeader
}