Synergy Software Package User's Manual
Communications Framework on sf_el_ux_comms_v2

Table of Contents

Communications Framework on USBX v2 Module Introduction

The Communications Framework on USBX™ (sf_el_ux_comms_v2) implements a high-level API for communications applications that provides an easy-to-use connection over the USB port. The high-level API functions in the framework are compatible with other connection implementations (such as UART and Ethernet), so it is easy to switch from one implementation to another without changing application code. The Communications Framework on USBX uses the USB peripheral on the Synergy MCU device.

Communications Framework on USBX v2 Module Features

  • High-level connectivity is supported on USB but is easily changed to UART and Ethernet connectivity without API modification
  • Supports channel locking for exclusive access
  • Supports USB high speed (HS) or full speed (FS) operation
  • Supports data-transfer (DMAC or DTC) peripherals on a Synergy MCU
  • ThreadX®-aware implementation uses mutex

 

Note
Currently, DTC is not supported by both the host and device side driver (only DMAC is supported).
sf_el_ux_comms_v2_BD.png
Communications Framework on USBX Module Block Diagram

Communications Framework on USBX v2 Module APIs Overview

The Communications Framework on USBX defines API functions for opening, closing, reading and writing over the USB connection. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Communications Framework on USBX Module API Summary

Function Name Example API Call and Description
open g_sf_comms0.p_api->open(g_sf_comms0.p_ctrl, g_sf_comms0.p_cfg);
Initialize communications driver.
close g_sf_comms0.p_api->close(g_sf_comms0.p_ctrl);
Clean up communications driver.
read g_sf_comms0.p_api->read(g_sf_comms0.p_ctrl, &destination, bytes, timeout);
Read data from communications driver. This call returns after the number of bytes requested is read or if a timeout occurs while waiting for access to the driver or read operation times out.
write g_sf_comms0.p_api->write(g_sf_comms0.p_ctrl, &source, bytes, timeout);
Write data to communications driver. This call returns after all bytes are written or if a timeout occurs while waiting for access to the driver or write operation times out.
lock g_sf_comms0.p_api->lock(g_sf_comms0.p_ctrl, lock_type, timeout);
Lock the communications driver. Reserve exclusive access to the communications driver.
unlock g_sf_comms0.p_api->unlock(g_sf_comms0.p_ctrl, lock_type);
Unlock the communications driver. Release exclusive access to the communications driver.
versionGet g_sf_comms0.p_api->versionGet(&version);
Retrieve the API version in the version pointer.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS Channel opened successfully.
SSP_ERR_IN_USE Channel already in use.
SSP_ERR_ASSERTION Pointer to UART control block or configuration structure is NULL.
SSP_ERR_INTERNAL Internal error occurs.
SSP_ERR_TIMEOUT Timeout error.
SSP_ERR_NOT_OPEN Module is not opened.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

Communications Framework on USBX v2 Module Operational Overview

The Communications Framework on USBX provides an easy-to-use connection over the USB port. The high-level API functions in the framework are compatible with other connection implementations (such as UART and Ethernet), so it is easy to switch from one implementation to another without changing applications code. The module uses ThreadX objects like mutex for synchronization for the completion of a transaction. The USBX communication Framework module supports the locking functionality, meaning that the user can lock the communication framework to a thread so that multiple thread can use the same USBX port safely. The locking allows the application to reserve a USB port for a given period of time available between call made to sf_comms_api_t::lock API and sf_comms_api_t::unlock API. The high-level APIs are used to sf_comms_api_t::read API, sf_comms_api_t::write API to support receive or send data to host over USBX CDC-ACM communication interface.

Communications Framework on USBX v2 Module Important Operational Notes and Limitations

Communications Framework on USBX v2 Module Operational Notes

The USBX driver can be implemented on either the HS or FS USB peripherals, depending on the version supported by the target MCU.

A pre-defined weak callback function is available for the USBX CDC-ACM instance activate and another for the USBX CDC-ACM instance deactivate. The user can override these two callback functions if required, by defining a user function using the callback function name given in the Synergy configurator.

Communications Framework on USBX v2 Module Limitations

Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Communications Framework on USBX v2 Module in an Application

This section describes how to include the Communications Framework on USBX Module in an application using the SSP configurator.

Note
It is assumed you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Communications Framework on USBX Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

Communications Framework on USBX Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_comms0 Communications Framework on sf_el_ux_comms_v2 Threads New Stack> Framework> Connectivity> Communications Framework on sf_el_ux_comms_v2

When the Communications Framework on USBX Module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

 

sf_el_ux_comms_v2_MS.png
Communications Framework on USBX Module Stack

Configuring the Communications Framework v2 on USBX Module

The Communications Framework on USBX Module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table values. This helps to orient you and can be a useful hands-on approach to learning the ins and outs of developing with SSP.

Configuration Settings for the Communications Framework on USBX Module

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Read Input Buffer Size (Bytes) 128 Maximum number of bytes that can be received at a time in the read() API.
Timeout in ticks 1000 Timeout value to suspend a USBX CDC instance creation in the open() API.
Name g_sf_comms0 Module name.
Name of the generated initialization function sf_comms_init0 Name of helper function to initialize Communications Framework. The function will be presented in the auto-generated code in the <xxx_thread>.c, where <xxx_thread> is the name of your thread symbol given to the Thread property. The function is to be called in the auto-generated code if Auto sf_comms Initialization property is Enabled. If Disabled, the function can be called in the user application.
Auto Initialization Enable, Disable

Default: Enable 		Auto Initialization support of Communications Framework. The helper function above will be called in the auto-generated code if this configuration is enabled. Else, the function will not be called automatically and user can call it sometime later.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.
Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.

Configuration Settings for the Communications Framework on USBX v2 Lower-Level Modules

Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module.

Configuration Settings for the USBX Device Class CDC-ACM Module

ISDE Property Value Description
Name g_ux_device_class_cdc_acm0 Specify the name of the USBX Device CDC-ACM Class module instance. It must be a valid C symbol.
USBX CDC-ACM instance_activate Function Callback ux_cdc_device0_instance_activate Specify the name of the instance_activate user callback function for the USBX Device CDC-ACM Class module. Name must be a valid C symbol. See the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device CDC-ACM Class" for more information about the instance_activate callback function.
USBX CDC-ACM instance_deactivate Function Callback ux-cdc_device0_instance_deactivate Specify the name of the instance_deactivate user callback function for the USBX Device CDC-ACM Class module. Name must be a valid C symbol. Refer to the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device CDC-ACM Class" for more information about the instance_activate callback function.
Name of generated initialization function ux_device_class_cdc_acm_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the USBX Device Configuration Instance

ISDE Property Value Description
Vendor ID 0x045B Specify Vendor ID assigned by USB-IF. This configuration is a part of the USB Device Descriptor (idVendor).
Product ID 0x0000 Specify Product ID assigned by manufacturer. This configuration is a part of the Device Descriptor (idProduct).
Device Release Number 0x0000 Specify Device Release Number in binary-coded decimal. This configuration is a part of the USB Device Descriptor (bcdDevice).
Index of Manufacturing String Descriptor 0x00 Specify the Index of Manufacturer String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iManufacturer). Set zero if String Descriptor is not used. See section USBX-String-Framework-Configuration for more information.
Index of Product String Descriptor 0x00 Specify the Index of Product String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iProduct). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information.
Index of Serial Number String Descriptor 0x00 Specify the Index of Serial Number String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iSerialNumber). Set zero if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information.
Class Code Communications(CDC), HID, Mass Storage, Miscellaneous, Vendor specific

Default: Communications(CDC) 		Select the USB Device Class Code. This configuration is a part of the USB Configuration Descriptor (bDeviceClass).
Index of String Descriptor describing this configuration 0x00 Specify the Index of String Descriptor describing this configuration. This configuration is a part of the USB Configuration Descriptor (iConfiguration). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information.
Size of USB Descriptor in bytes for this configuration (Modify this value only for Vendor-specific Class, otherwise set zero) 0x00 Specify the size of USB Descriptor in bytes. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the size automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (wTotalLength).
Number of Interfaces (Modify this value only for Vendor-specific Class, otherwise set zero) 0x00 Specify the Number of interfaces supported by this configuration. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the value automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (bNumInterfaces).
Self-Powered Enable, Disable

Default: Enable 		Enable this configuration if your USB Device is a self- powered device. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit6).
Remote Wakeup Enable, Disable

Default: Disable 		Enable this configuration if your USB Device supports remote wakeup. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit5).
Maximum Power Consumption (in 2mA units) 50 Set the maximum power consumption of your device to indicate the amount of bus power required. This configuration is 2 mA units, thus, the maximum 500 mA can be specified. This configuration is a part of the USB Configuration Descriptor (bMaxPower).
Supported Language Code 0x0409 Specify the Language ID Code.  For example, 0x0409 English - United States. This configuration is used for Language ID Framework code generation. See section "USBX Language Framework Configuration" for more information.
Name of USBX String Framework NULL Specify the name of user defined USBX String Framework. This must be a valid C symbol. Set NULL if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information.
Total index number of USB String Descriptors in USB String Framework 0 Specify the total number of index for String Descriptor. See section "USBX String Framework Configuration" for more information.
Name of USBX Language Framework NULL Specify the name of user defined USBX Language Framework. This must be a valid C symbol. If '0' is set to the property "Total Number of Language Support", this configuration is ignored. See section "USBX Language Framework Configuration" for more information.
Number of Languages to support (US English is applied if zero is set) 0 Specify the total number of languages to support. See section "USBX String Framework Configuration" for more information. If '0' is set here, US English (0x0409) is applied as the default language.
Name of generated initialization function ux_device_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the USBX Interface Configuration CDC-ACM Instance

ISDE Property Value Description
Name g_usb_interface_desc_cdcacm_0 Specify the name of USBX Interface Descriptor for CDC-ACM. It must be a valid C symbol.
Interface Number of Communications Class interface 0x00 Specify the index number of Communications Class interface. This configuration is a part of the USB Interface Descriptor (bInterface). The number must not be duplicated with the Interface Number of Data Class interface. Also must not be duplicated with any Interface Numbers if your USB device consists of a USB composite device.
Interrupt Transfer endpoint to use for Communications Class Endpoint 1-9

Default: Endpoint 3 		Specify the Endpoint Number of Interrupt Endpoint. It must not be duplicated with ones for the other Endpoints.
Polling period for Interrupt Endpoint (in mS/125us units for FS/HS) 0x0F Specify the Interval for polling Endpoint transfers. This configuration is valid for Interrupt Endpoint and ignored for Bulk Endpoints. Value is in frame counts (1 ms units for FS mode and 125 us units for HS mode).
Interface Number of Data Class interface 0x01 Specify the index number of Data Class interface. This configuration is a part of the USB Interface Descriptor (bInterface). The number must not be duplicated with the Interface Number of Communications Class interface. Also must not be duplicated with any Interface Numbers if your USB device consists of a USB composite device.
Bulk In Transfer endpoint to use for Data Class Endpoint 1-9

Default: Endpoint 1 		Specify the Endpoint Number of Bulk In Endpoint. It must not be duplicated with ones for the other Endpoints.
Bulk Out Transfer endpoint to use for Data Class Endpoint 1-9

Default: Endpoint 2 		Specify the Endpoint Number of Bulk Out Endpoint. It must not be duplicated with ones for the other Endpoints.
Index of String Descriptor Describing Communications Class interface (Interface Descriptor: Interface) 0x00 Specify the index number of String Descriptor Describing Communications Class interface. This configuration is a part of the USB Interface Descriptor (iInterface). Set '0' if do not have String information for the interface.
Index of String Descriptor Describing Data Class interface (Interface Descriptor: Interface) 0x00 Specify the index number of String Descriptor Describing Data Class interface. This configuration is a part of the USB Interface Descriptor (iInterface). Set '0' if do not have String information for the interface.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the USBX Port DCD on sf_el_ux for USBFS

ISDE Property Value Description
Full Speed Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled

Default: Disabled 		Select the interrupt priority for full-speed USB.
LDO Regulator (Only for S3 and S1 part MCUs) Enable, Disable

Default: Disable 		Select the LDO regulator will be enabled.
Name g_sf_el_ux_dcd_fs_0 Module name.
USB Controller Selection USBFS Select the USB controller.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the USBX Port DCD on USBHS

ISDE Property Value Description
High Speed Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled

Default: Disabled 		Select the interrupt priority for high speed USB.
Name g_sf_el_ux_dcd_hs_0 Module name.
USB Controller Selection USBHS Select the USB controller.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the USBX on ux Instance

ISDE Property Value Description
USBX Pool Memory Name g_ux_pool_memory Name must be a valid C symbol.
USBX Pool Memory Size 18432 See section "Azure RTOS USBX Memory Requirements" for the required memory size for each classes.
User Callback for Host Event Notification (Only valid for USB Host) NULL Name must be a valid C symbol. The name of User defined USBX Host event notification can be given to this property.
Name of generated initialization function ux_common_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Communications Framework on USBX v2 Module Clock Configuration

The USB peripheral module uses the UCLK as its clock source; the UCLK should be configured for 48 MHz operation. In the SSP configuration window, select the Clocks tab to view the clock-source setting.

Communications Framework on USBX v2 Module Pin Configuration

The USB peripheral module uses MCU pins to communicate with external devices. Select I/O pins and configure to the external device requirements. The following table lists the pin selection method within the SSP Configuration Window and the subsequent tables demonstrate the selection process using USB pins as an example.

Note
The selected operation mode determines what peripheral signals are available and what MCU pins are required.

USBFS and USBHS Pin Selection Sequence

Resource ISDE Tab Pin selection Sequence
USBFS Pins Select Peripherals> Connectivity: USBFS> USBFS0
USBHS Pins Select Peripherals> Connectivity: USBHS> USBHS0
Note
The selection sequence assumes USBFS0 or USBHS0 is the desired hardware target for the driver.

USBHS Pin Configuration Settings

Property Value Description
Operation Mode Disabled, Custom, Device, Host, OTG

Default: Custom 		Select device as the Operation Mode.
USBDP USBDP USBDP pin.
USBDM USBDM USBDM pin.
OVRCURB None OVRCURB pin.
OVRCURA None OVRCURA pin.
VBUSEN None VBUSEN pin.
VBUS None, P407

Default: P407 		VBUS pin.
EXICEN None EXICEN pin.
ID None ID pin.
VCCUSB VCCUSB VCCUSB pin.
VSSUSB VSSUSB VSSUSB pin.
Note
The example settings are for a project using the S7G2 Synergy MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

USBHS Pin Configuration Settings

Property Value Description
Operation Mode Disabled, Custom, Device, Host, OTG

Default: Custom 		Select Device as the Operation Mode.
USBHSDP USBHSDP USBHSDP pin.
USBHSDM USBHSDM USBHSDM pin.
OVRCURB None OVRCURB pin.
OVRCURA None OVRCURA pin.
VBUSEN PB00 VBUSEN pin.
VBUS PB01 VBUS pin.
EXICEN None EXICEN pin.
ID None ID pin.
USBHSRREF USBHSRREF USBHSRREF pin.
AVCCUSBHS AVCCUSBHS AVCCUSBHS pin.
AVSSUSBHS AVSSUSBHS AVSSUSBHS pin.
PVSSUSBHS PVSSUSBHS PVSSUSBHS pin.
VCCUSBHS VCCUSBHS VCCUSBHS pin.
VSS1USBHS VSS1USBHS VSS1USBHS pin.
VSS2USBHS VSS2USBHS VSS2USBHS pin.
Note
The example settings are for a project using the S7G2 Synergy MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

Using the Communications Framework on USBX v2 Module in an Application

The typical steps in using the Communications Framework on USBX V2 module in an application are:

1. Initialize the Communications Framework on USBX V2 using the sf_comms_api_t::open API.

2. Lock the channel for continuous communications using the sf_comms_api_t::lock API if needed.

3. Receive data using the sf_comms_api_t::read API.

4. Send data using the sf_comms_api_t::write API.

5. Unlock the channel from continuous communication using the sf_comms_api_t::unlock command if needed.

6. Close the channel using the sf_comms_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

sf_el_ux_comms_v2_TA.png
Flow Diagram of a Typical Communications Framework on USBX Module Application