NAME

USB Embedded Host and Device server

SYNOPSIS

#include <sys.h>
#include <stdio.h>
#include <usb.h>
#include <device.h>

int usb_server(tUSB_config * config);

DESCRIPTION

The Unison USB server is complex USB OTG, Device and HOST solution. Depending of requirements it can provide USB HOST or USB Device or both Host+Device functionality. USB server can manage and switching USB roles.

USB server can be started as USB_DEVICE, USB_HOST or USB_OTG server.

Key Features:

· Automatic start usbh or usbd servers depending of start configuration
· Automatic detection and switching USB role by UBD_ID pin
· Manual switching between HOST and DEVICE roles

USB server structure

The usb server is instantiated with the command:
usb_server(&usb_config);

int usb_server(tUSB_config * config);

The main configuration is sended to usb server in tUSB_config config variable

typedef struct
{
	tUSB_core_conf *core_conf;
	pthread_t (* host)(void *);
	pthread_t (* dev) (void *);
} tUSB_config;

core_conf – configuration of USB ports (one or more). Each USB port can be configured to work in different mode.

pthread_t (* host)(void *), pthread_t (* dev) (void *) – are pointers to start functions for USB HOST and DEVICE. It must be a usbh_start and usbd_start.

If your want to use only USB HOST or only USB DEVICE on all available USB ports you must fill only host or dev field.

Example:

tUSB_config usb_config;
tUSB_core_conf usb_cores[2];

	usb_config.core_conf = usb_cores;
	usb_config.host = (void*)usbh_start;
	usb_config.dev  = (void*)usbd_start;

tUSB_core_conf – main configuration data for USB ports. It must be array of configuration for each port. In last array element field CoreID must be “-1” value.

typedef struct
{
	void(* usb_callback)(tUSB_event evt, void * param);
	signed char CoreID;
	int mode;
	usb_list_param param;
} tUSB_core_conf;

usb_callback – refers to the callback function for current port of USB server. This function is evoked by service events such as:

	_USBH_CON_EVT 			//USB HOST detect connected device to its port
	_USBH_DISCON_EVT  		//USB HOST detect disconnect device from its port
	_USBH_PWR_EVT     		//USB HOST detect power failure
	_USBH_VBUS_EVT    		//USB HOST detect vbus error event (overcurrent)
	_USBD_CON_EVT  			//USB DEVICE was connected to host
	_USBD_DISCON_EVT  		//USB DEVICE has been disconnected from host
	_USB_ROLE_HOST_EVT		//role changed to host
	_USB_ROLE_DEV_EVT 		//role changed to dev

CoreID – Core (port) number from message hsa received
mode – Work mode for current core. Mode can have another options:

1. USB role:
_USB_HOST - USB HOST only 
_USB_DEV  - USB DEVICE only 
_USB_OTG_A - USB OTG mode with HOST starting first
_USB_OTG_B - USB OTG mode with DEVICE starting first

USB_LS – Low speed USB_FS – Full speed USB_HS – High speed USB_SS – SuperSpeed speed

3. additional options

_USB_OTG_ID_PIN_DISABLE - If mode OTG is selected this option was disabling ID pin detection. 
In this case User can change USB roles manually 

Example

/*Select USB OTG mode with default Host started, Switch USB role by user. 
High speed FULL limitation*/

usb_cores[0].mode = _USB_OTG_A | _USB_OTG_ID_PIN_DISABLE | USB_FS;

2. USB HOST speed limitation(if controller is support this future)

usb_list_param param – additional parameters for usb host and device modes.

typedef struct
{
	void *host_param;
	void *dev_param;
} usb_list_param;

host_param and dev_param described in USB HOST and USB DEVICE manuals

EXAMPLE

Starting and configuring USB servers

/* USB server structs */
	tUSB_config usb_config;
	tUSB_core_conf usb_cores[2];	//USB have 1 core (last element should be empty with -1 core_ID)
	
/* USB device structures */
	tUSBD_port_info     usbd_port;
	tUSBD_configuration usbd_config;

	tUSBD_interface     usbd_interface;
	tUSBD_cdc_serial    usbd_cdc_serial;

/* configure USB DEVICE parameters*/
	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      = 3;  // ttyUSB3 
	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;

	usb_cores[0].param.dev_param = &usbd_port;

/* configure USB HOST parameters*/
	usb_cores[0].param.host_param = NULL;	// USB HOST doesn't have additional options

/* configure USB port */
	usb_cores[0].usb_callback = USBH_event;
	usb_cores[0].CoreID       = 0;			//physical USB controller number 
	usb_cores[0].mode         = _USB_OTG_A;	//USB mode OTG wih default HOST MODE 
	usb_cores[1].CoreID = -1;	//end of ports list
    
/* configure USB server */
	usb_config.core_conf = usb_cores;
	usb_config.host = (void*)usbh_start;
	usb_config.dev  = (void*)usbd_start;

/* add USB drivers */
	usbd_add_serial_driver();	//adding CDC driver for USB DEVICE role
	usbh_add_msc_driver();		//adding USB MSC driver for support Mass storage drives in USB HOST role


/* Start USB server */
	usb_server(&usb_config);

USB server control functions:

int usb_set_role(uint_8 core, uint_8 role);

Set role (_USB_HOST or _USB_DEV) for the specified core number;

Return 0 if role can be changed, -1 if error has accured. Role change i long process in time. When Role is changed _USB_ROLE_HOST_EVT or _USB_ROLE_DEV_EVT must be recived.

This function can be executed when _USB_OTG_ID_PIN_DISABLE option is set in mode field.

int usb_get_role(uint_8 core);

Get current role of USB. If command was succesfull then return current role: _USB_HOST or _USB_DEV. Return -1 if error.

Note

In project options in demo user must set predefined symbol _USB_OTG_ or _USB_HOST_ or _USB_DEVICE_ (see manual to your compiller)

SEE ALSO

usbh usbd