NAME

USB Embedded Device Server – usbd

SYNOPSIS

#include <sys.h>

#include <usb/usb.h>

USB Device general API functions definition

int usbd_start(tUSB_core_conf * core_config);

function that called from usb server for initialization USB device core

void usbd_add_serial_driver(void);

register serial device class driver for USB device core.

void usbd_add_msc_driver(void);

register mass storage class device driver for USB device core

void usbd_add_mouse_driver(void);

register HID mouse device driver for USB device core

void usbd_add_keyboard_driver(void);

register HID keyboard device driver for USB device core

void usbd_add_extended_keyboard_driver(void);

register HID extension keyboard device driver for USB device core

void usbd_add_audio_driver(void);

register Audio device driver for USB device core

void usbd_add_audio_control_driver(void);

register Audio device driver for USB device core

int usbd_get_connect_state(uchar port);

return 1 – USB device connected to USB host and ready to work

return 0 – USB device disconnected or not ready to work.

USB HID Device API functions definition

int usbd_hid_keyboard_send_keys(char port, unsigned char key, unsigned char press);

Description

Send standard keyboard key code and state to USB Host.

Parameters

port – physical number of USB device controller at target

key – key code according to USB HID coding, see “usbd_hid_keyboard.h” for details.

press – specify is key pressed or released. Could be HID_KEY_SET/HID_KEY_CLEAR, see “usbd_hid_keyboard.h” for details.

Return

0 – success

-1 – error

int usbd_hid_keyboard_send_keys_extended(char port, unsigned char key, unsigned char press);

Description

Send Extended keyboard key (Volume_Up, Volume_Dn, Stop/Eject, Play/Pause, Mute, ….) code and state to USB Host.

Parameters

port – physical number of USB device controller at target

key – extended key code according to USB HID coding (“Consumer Page”), see “usbd_hid_keyboard.h” for details.

press – specify is key pressed or released. Could be HID_KEY_SET/HID_KEY_CLEAR, see “usbd_hid_keyboard.h” for details.

Return

0 – success

-1 – error

int usbd_hid_mouse_send_state(char port, signed char x, signed char y, unsigned char button);

Description

Send mouse state.

Parameters

port – physical number of USB device controller at target

x – change (increment/decrement) for X coordinate. Min val ±1, Max val ±127

y – change (increment/decrement) for Y coordinate. Min val ±1, Max val ±127

button – buttons state. Could be combination of buttons: HID_MOUSE_BUTTON1 | HID_MOUSE_BUTTON2 | HID_MOUSE_BUTTON3

Return

0 – success

-1 – error

Additional headers for HID devices.

#include <usb/usbd_hid_mouse.h>

define Mouse button codes for HID class

#include <usb/usbd_hid_keyboard.h>

define Keyboard key codes for HID class

USB Audio Device API functions definition

void usbd_audio_on(void);

Description

This function is called from the stack in response to a request from USB HOST to enable audio output

void usbd_audio_off(void);

Description

This function is called from the stack in response to a request from USB HOST to disable audio output

void usbd_audio_data(void);

Description

This function is called from the stack when USB device have available part of audio data stream for playback.

Return

pointer to audio data stream buffer.

void usbd_audio_data_size(void);

Description

This function is called from the USB device stack to inform stack with playback buffer size.

Return

buffer size.

Additional headers for Audio devices.

#include <usb/usbd_audio.h>

DESCRIPTION

The USB device stack designed for embedded systems equipped with a USB device controller.

The USB device stack is a modular architecture with three software elements providing functionality between the application and the hardware.

USB Device server structure

USB Server – run and manage usb device and usb host stack.

USB Device core – controls the reception and transmission of packets to and from the user application. It is a general framework providing a standardized interface between the application and the specific USB hardware.

USB Device function driver – implements the required USB device functionality (i.e. serial communications, mass storage, human interface …). The function driver provides the selected class implementation.

USB Device hardware port – provides the low-level interface between USB device controller hardware and USB device software stack.

The Unison USB Device solution consists of sets of libraries, which implement the stack (as shown in the figure, above). These libraries are organized as follows:

• USB Server

– usb_server

• USB Device core

– usbd_core

• USB Device function drivers

– usbd_cdc_serial_driver

– usbd_msc_driver

– usbd_hid_keyboard_driver

– usbd_hid_mouse_driver

– usbd_audio_driver

and so on, for any device class which is supported by The Unison USB Device solution

• USB Device hardware porting layer

usbd_xxxxxxx_port, where xxxxxxx is chip type.

Initialization usb device

Additional parametrs for start USB Device describing below.

To start a USB device need to fill the following structures:

1. Firs – general usb device port info configurations:

typedef struct
{
        unsigned short       idVendor;            // Vendor ID for the USB product
        unsigned short       idProduct;           // Product ID for the USB product
        unsigned short       bcdDevice;           // Device release number in BCD format
        const char          *pManufacturer;       // Manufacturer string descriptor
        const char          *pProduct;            // Product string descriptor
        const char          *pSerialNumber;       // Serial number string descriptor
        tUSBD_configuration *pConfigurations;      
        unsigned char        NumConfigurations;   // Number of possible configurations for current port
} tUSBD_port_info;

the user needs to describe the general data about the device

idVendor – the vendor ID is assigned by the USB Implementers forum (www.usb.org).

For test, the default number above can be used.

However, you may not bring a product on the market without having been assigned your own vendor ID.

idProduct – the product ID build in combination with the vendor ID a worldwide unique identifier.

For test, the default number above can be used.

bcdDevice – the device release number

pManufacturer – the pointer on string describing manufacturer.

pProduct – the pointer on string describing product.

pSerialNumber – the pointer on string describing device’s serial number

NumConfigurations – the number of possible configurations for usb device

pConfigurations – the pointer on structure describing configurations for this usb device

Example:

        tUSBD_port_info     usbd_port;
        usbd_port.idVendor          = 0x0123;                     // Vendor ID for the USB product
        usbd_port.idProduct         = 0x4567;                     // Product ID for the USB product
        usbd_port.bcdDevice         = 0x0001;                     // Device release number in BCD format
        usbd_port.pManufacturer     = "RoweBots";                 // Manufacturer string descriptor
        usbd_port.pProduct          = "Unison RTOS USB Serial";   // Product string descriptor
        usbd_port.pSerialNumber     = "111004";                   // Serial number string descriptor
        usbd_port.pConfigurations   = &usbd_config;                
        usbd_port.NumConfigurations = 1;                          // Number of configurations for current port

2. Second description of possible configurations and electrical parameters:

typedef struct
{
        tUSBD_interface     *pInterfaces;
        unsigned char        NumInterfaces;       // Number of interfaces for current port
        const char          *pStrConfiguration;   // String Configuration Name
        char                 MaxPower;
        char                 Attributes;
} tUSBD_configuration;

pInterfaces – pointer in struct that description interface for this configuration

NumInterfaces – Number of interfaces supported by this configuration

pStrConfiguration – pointer on string that description this configuration

MaxPower – maximum power consumpion of the USB device from the bus in this specific configuration when the device

is fully operational. Expressed in 2 mA units (i.e. 50 = 100 mA).

Attributes – Configuration chracteristics

#define _DEFAULT          (0x01<<7)       // Default Value Bit 7 is set
#define _SELF_POWER       (0x01<<6)       // Self-powered  - Supports if set
#define _REMOTE_WAKEUP    (0x01<<5)       // Remote Wakeup - Supports if set

2.Third description of possible interases

typedef struct
{
        void                *param;
        char                 type;       // type of interfases
} tUSBD_interface;

type – variable that describe wthat usd device class will used on current interfaces.

#define USBD_CDC_SERIAL_DEVICE          0x01
#define USBD_CDC_ETHERNET_DEVICE        0x02
#define USBD_MSC_DEVICE                 0x03
#define USBD_HID_MOUSE_DEVICE           0x04
#define USBD_HID_KEYBOARD_DEVICE        0x05
#define USBD_HID_EXT_KEYBOARD_DEVICE    0x06
#define USBD_AUDIO_DEVICE               0x07
#define USBD_AUDIO_CONTROL_DEVICE       0x08

param – pointer on specific interface parameters

The following example demonstrates how to use Unison’s USB device solution with a USB CDC serial device class. All other device classes use a similar initialization method and usage.

EXAMPLE

Instantiating a USB CDC Serial device server:

THREAD Main(void *arg)
{
        pthread_t pid;
        pthread_attr_t attr;
        struct sched_param myNewPriority;

        /* USB server structs */
        tUSB_config    usb_config;
        tUSB_core_conf usb_cores[2];
  
        /* USB device general structs */
        tUSBD_port_info     usbd_port;
        tUSBD_configuration usbd_config;

          /* USB device CDC interface structs */
        tUSBD_interface     usbd_interface;
        tUSBD_cdc_serial    usbd_cdc_serial;

        #if RTOS_DEBUG
                dir_register("Main thread", pthread_self(), TYPE_THREAD);
        #endif


        usbd_port.idVendor          = 0x0123;                     // Vendor ID for the USB product
        usbd_port.idProduct         = 0x4567;                     // Product ID for the USB product
        usbd_port.bcdDevice         = 0x0001;                     // Device release number in BCD format
        usbd_port.pManufacturer     = "RoweBots";                 // Manufacturer string descriptor
        usbd_port.pProduct          = "Unison RTOS USB Serial";   // Product string descriptor
        usbd_port.pSerialNumber     = "111004";                   // Serial number string descriptor
        usbd_port.pConfigurations   = &usbd_config;                
        usbd_port.NumConfigurations = 1;                          // Number of configurations for current port

        
        usbd_config.NumInterfaces     = 1;
        usbd_config.pInterfaces       = &usbd_interface;
        usbd_config.pStrConfiguration = "CDC Configuration";
        usbd_config.MaxPower          = 0x0;
        usbd_config.Attributes        = _DEFAULT | _SELF_POWER;

        /* Setup serial device specific parameters*/
        usbd_cdc_serial.vport_num      = 1;  // ttyUSB1 
        usbd_cdc_serial.rx_buf_size    = 512;
        usbd_cdc_serial.tx_buf_size    = 512;


        usbd_interface.type   =  USBD_CDC_SERIAL_DEVICE;
        usbd_interface.param  = &usbd_cdc_serial;

        /* Register serial device driver in USB device server*/
        usbd_add_serial_driver();

        /********************
        Start USB server
        ********************/
        usb_config.core_conf = usb_cores;
        usb_config.host      = NULL;
        usb_config.dev       = (void*)usbd_start;

        usb_cores[0].usb_callback = USB_event;
        usb_cores[0].CoreID = 0;                //physical USB controller number
        usb_cores[0].mode   = _USB_DEV;
        usb_cores[0].param.dev_param = &usbd_port;

        usb_cores[1].CoreID = -1;

        if (usb_server(&usb_config))
        {
                xprintf("pthread_create = %d\n", errno);
                pthread_exit(0);
        }

}

NOTES

In the above example, the user application uses the following USB libraries to implement the serial device:

• usb_server
• ubd_core
• ubd_cdc_serial_driver
• usbd_xxxxxxx_port

SEE ALSO

ttyserver usb