USBX Host Class Printer Module Introduction
- USBX Host Class Printer Module Features
USBX Host Class Printer Module APIs Overview
USBX Host Class Printer Module Operational Overview
- USBX Host Class Printer Module Important Operational Notes and Limitations
  - USBX Host Class Printer Module Operational Notes
  - USBX Host Class Printer Module Limitations
Including the USBX Host Class Printer Module in an Application
Configuring the USBX Host Class Printer Module
Using the USBX Host Class Printer Module in an Application

USBX Host Class Printer Module Introduction

The USBX™ Host Class Printer module provides a high-level API for USBX Host Class Printer module applications and uses the USB and data-transfer peripherals on the Synergy MCU. A user defined callback can be created to determine when the stack activates or deactivates the USB Printer class.

Unsupported Features

USBX host class PIMA is not supported in this version of SSP.

USBX Pictbridge is not supported in this version of SSP.

USBX Host Class Printer Module Features

The USB Host Class Printer module allows for a USB host-system to communicate with the Printer. This class is based on the USB standard. The USBX Host Class Printer module includes the following key features:

Support for USB Full Speed (USBFS) or USB High Speed (USBHS)
Receive and transmit data-transfer drivers for improved performance
High-level APIs for reading and writing

USBX Host Class Printer Module Block Diagram

USBX Host Class Printer Module APIs Overview

The USBX Host Class Printer Module defines APIs, which are used to interact with the Printer interface. 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.

USBX Host Class PRINTER Module Summary

Function Name	Example API Call and Description
ux_host_class_printer_read	`UINT ux_host_class_printer_read (UX_HOST_CLASS_PRINTER printer, UCHAR data_pointer, ULONG requested_length, ULONG *actual_length)` This function reads from the printer interface. The call is blocking and only returns when there is either an error or when the transfer is complete. A read is allowed only on bi-directional printers.
ux_host_class_printer_write	`UINT ux_host_class_printer_write (UX_HOST_CLASS_PRINTER printer,UCHAR data_pointer, ULONG requested_length,ULONG *actual_length)` This function writes to the printer interface. The call is blocking and only returns when there is either an error or when the transfer is complete.
ux_host_class_printer_soft_reset	`UINT ux_host_class_printer_soft_reset (UX_HOST_CLASS_PRINTER *printer)` This function performs a soft reset to the printer
ux_host_class_printer_status_get	`UINT ux_host_class_printer_status_get (UX_HOST_CLASS_PRINTER printer,ULONG printer_status)` This function obtains the printer status. The printer status is similar to the LPT status (1284 standard).
_ux_host_class_printer_name_get	`UINT _ux_host_class_printer_name_get(UX_HOST_CLASS_PRINTER *printer)` This function obtains the Device ID string.

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.

Return Values

Name	Description
UX_SUCCESS	This operation was successful.
UX_FUNCTION_NOT_SUPPORTED	Function not supported because the printer is not bi-directional.
UX_TRANSFER_TIMEOUT	Transfer timeout, reading or writing is incomplete, or reset not completed.
UX_MEMORY_INSUFFICIENT	Not enough memory to perform the operation.

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.

USBX Host Class Printer Module Operational Overview

The initialization of the Printer class expects some specific parameters as illustrated in the application project associated with this module guide.

Printers have two different types of commands: those that transfer data and those that control the USB interface or Printer interface. The host prints something on a printer by delivering data on the Bulk OUT endpoint. This data is in the form of PostScript, HP PCL or any other PDL. This data may also be encapsulated in a PCP, such as IEEE 1284.1, or something that is vendor-specific. In addition, the data may also be simple text, or it may be a proprietary PDL. User application should take care of converting data into printer supported formats. The printer can respond periodically on the Bulk IN endpoint with status regarding the data it is receiving, or because of an asynchronous event. A typical printed page takes the following sequence:

Printing a page

The PDL data is sent to the device on the Bulk OUT pipe. If the device uses a PCP, then the PDL is encapsulated in the PCP; the Bulk IN pipe is used for any responses, such as errors and printer status as defined in the PCP. For a unidirectional interface, the status is retrieved by issuing a port status command on the default pipe, and the status is returned on the default pipe.

USBX Host Class Printer Module Important Operational Notes and Limitations

USBX Host Class Printer Module Operational Notes

The USBX Host stack or USBX Host stack consumes RAM for the control block. The Synergy Configuration tool allocates memory to the USBX memory pool statically in the auto-generate code as shown in the following table. You need to set the appropriate memory size in bytes to the USBX Pool Memory Size property of the USBX on ux component in the Synergy Configuration tool in section "USBX on ux Configuration." If multiple classes are used, set the total memory size to the property.

Memory (RAM) Requirements for the USBX Memory Pool

USBX Class	S1 Parts	Other Parts
USBX HostPrinter(ux_Host_class_printer)	N/A	27KB

Note: the information shown in the table above is valid if compiled with default USBX configurations.; the memory size of the USBX Classes in the table above are of the pre-built libraries and the following configuration was applied for the builds:

UX_THREAD_STACK_SIZE: 2048 (bytes) for the other parts

USBX Host Class Printer Module Limitations

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

Note: Currently, DTC is not supported by the host side driver (only DMAC is supported).

Including the USBX Host Class Printer Module in an Application

This section describes how to include the USBX Host Class Printer 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 USBX Host Class Printer Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

USBXHost Class Printer Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_ux_Host_class_printer0 USBX Host Class Printer	Threads	New Stack> X-Ware> USBX>Host> Classes >Printer> USBX Host Class Printer

When the USBX Host Class Printer 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 includes Add in the text. Clicking on any Pink banded modules brings up the new icon and displays possible choices.

USBX Host Class Printer Module Stack

Configuring the USBX Host Class Printer Module

The USBX Host Class Printer 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 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 USBX Host Class Printer Module

ISDE Property	Value	Description
Name	g_ux_Host_class_printer0	Specify the name of the USBX Host Printer Class module instance. It must be a valid C symbol.

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 USBX Host Class Printer 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 Host Class Printer Source

ISDE Property	Value	Description
Show linkage warning	Enabled, Disabled Default: Enabled	Notification message for users will be shown if "Enabled" option is selected. This is just to warn user's possible linkage errors by multiple symbol definitions. Select "Disabled" stops the notification message.

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

Configuration Settings for the USBX Host Configuration Instance

ISDE Property	Value	Description
Name	g_ux_host0	Specify the name of USBX Host Configuration instance. It must be a valid C symbol.
Name of generated initialization function	ux_host_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 Port HCD 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.
VBUSEN pin Signal Logic	Active Low, Active High Default: Active High	Select the VBUSEN pin signal logic.
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_hcd_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 HCD on sf_el_ux for 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.
FIFO size for Bulk/Isochronous Pipes	512, 1024, 1536, 2048 bytes Default: 512 bytes	Select the FIFO size for bulk and isochronous transfers.
Number of Isochronous Pipes Reserved	0,1,2 Default: 0	Select the number of isochronous pipes to reserve.
VBUSEN pin Signal Logic	Active Low, Active High Default: Active High	Select the VBUSEN pin signal logic.
Enable High Speed	Enable, Disable Default: Enable	Select if high speed should be enabled.
Name	g_sf_el_ux_hcd_hs_0	Module name.

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		See section "Azure RTOS USBX Memory Requirements" for the required memory size for each class.
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.

USBX Host Class Printer Module Clock Configuration

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

USBX Host Class Printer Module Pin Configuration

The USB peripheral module uses MCU pins to communicate with external Hosts. Select I/O pins and configure to the external Host 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 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, Host, Host, OTG Default: Custom	Select Host 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 and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.