This document tells you how to create, build and use a .rss resource file to configure the USB subsystem in Symbian platform.
This .rss file will determine how the Symbian phone that you are designing will present itself to USB hosts.
The purpose of this tutorial is to enable you to make sure the device you are designing presents itself correctly to USB hosts for the type or types of USB communication you intend the device to perform.
This tutorial is for Symbian developers who need to build particular types of USB connectivity into a mobile phone they are developing.
To follow this tutorial, you will find it helpful to have a general understanding of the USB 2.0 specification and a particular understanding of Chapter 9 of that specification (which concerns the USB protocol stack).
The USB 2.0 specification is available from the following location on the website of the USB Implementers Forum:
http://www.usb.org/developers/docs/
Information about USB classes is available from the following location on the same website:
http://www.usb.org/developers/devclass_docs#approved
You will also find it helpful to know how to use the Symbian USB subsystem (particularly the component called USB Manager).
A Symbian platform phone must present itself to a USB host as a device that implements classes of information transfer. (The possible classes are listed in the document at the following location on the USB Implementers Forum website: http://www.usb.org/developers/defined_class.) Note, however, that in this tutorial the USB host is assumed to be running on a Windows PC, and currently Windows does not permit devices to present its USB host with a menu of different USB classes of device for it to choose from. Therefore, you can design into the phone whatever classes you want it to support, but you must provide for the execution of some code or some end-user action (for example, by means of user-interface menus) to determine which class the device presents itself to the USB host as in a given instance.
This tutorial tells you how to specify the class or classes that your device supports by editing the fields of a resource struct called PERSONALITY. Many of the values that you specify for the fields of this struct will form the values that the device sends to the USB host in its Device Descriptor before enumeration.
The PERSONALITY struct is defined in a file called usbman.rh. This file is located on your development drive in the \epoc32\include directory. Instances of the PERSONALITY struct, however, are declared (in other words, you need to declare them yourself) in a .rss resource file. This is a file that you must create yourself, but Symbian provide a reference version of it for you to use as a template, and this tutorial tells you how to create, edit, and build it, and also how to include it in a ROM image to load on to your development hardware. The reference file is located in the following directory in your development environment: ...\src\common\generic\ser-comms\usb\usbman\SRC.
When you have completed the tutorial, you will still need to develop an application that monitors for USB cable-insertion and removal events (and requests USB services - or requests their suspension - in response to such events). You will still also need to implement class controller components for whichever classes of device you have specified in the .rss resource file (unless you are using class controllers for which Symbian reference code is provided).
At the time of writing, tutorials covering these subjects are not yet available.
Note that the term "personality" is a Symbian-specific concept. It is not a generally understood USB term, but it is broadly analogous to the Bluetooth term "profile"; in other words, a "personality" is a collection of configuration data that defines the capabilities of one device (in this case, a Symbian platform phone acting as a USB peripheral device) in relation to another (in this case, a USB host device).
Setup and configuration requirements
To follow the instructions in this tutorial you will need:
The following tasks will be covered in this tutorial:
Creating the personalities resource (.rss) file
Specifying the fields of the PERSONALITY struct
Building the personalities resource (.rss) file
Editing the usbman.iby file that specifies the target locations of files in the ROM
Building the ROM image and connecting the device to the USB host
Creating the personalities resource file
To specify one or more USB device personalities, do the following:
In the root of your development drive, create a directory called, for example, \usbconfig.
In this directory, create an empty text file called, for example, usbconfig.rss.
Paste into this file the contents of the reference file called usbman.rss that is located in the directory sf/os/shortlinksrv/usbmgmt/usbmgr/usbman/server/SRC. The file looks like this:
/** @file * * Resource file for usbman configuration. * * Copyright (c) 2005-2007 Symbian Software Ltd. All rights reserved. */ //NAME USBM #include <badef.rh> #include "usbman.rh" RESOURCE BA_RSS_SIGNATURE { signature = 1; } //RESOURCE usb_configuration usb_config // { // } RESOURCE PERSONALITY_ARRAY device_personalities { personalities = { PERSONALITY { bDeviceClass = 02; bDeviceSubClass = 0; protocol = 0; numConfigurations = 1; vendorId = 0x0e22; productId = 0x000b; bcdDevice = 0x0200; manufacturer = "ACME"; product = "Widget"; id = 1; class_uids = "101FBF22"; description = "Modem personality"; } }; }
Proceed to the next sub-section which tells you how to specify the fields of one or more PERSONALITY structs.
Specifying the fields of the PERSONALITY struct
Many of the fields of the PERSONALITY struct correspond to fields of the Device Descriptor that your USB peripheral device will send to the USB host to enable enumeration to take place. For more detailed information about each one, refer to the usbman.rh file in the \epoc32\include directory on your development drive.
For more information about the Device Descriptor, refer to the USB 2.0 specification.
Edit the usbconfig.rss file so that each field of the first (and so far only) personality defined contains the correct value for your device and for the type or types of USB communication the device needs to support.
bDeviceClass |
If the personality you are configuring supports only a single class, then you can specify the value for that class in this field. The value you specify will then determine the content of the bDeviceClass field in the Device Descriptor that the device sends to the USB host. However, if the personality supports multiple classes, you need to specify zero for this field and then specify the class (and sub-class) codes individually when you implement the device's USB interface definitions. For information about the classes you need to specify for different types of USB communication, refer to the class specification documents on the USB Implementers Forum website: http://www.usb.org/developers/devclass_docs#approved. Examples of classes you might be concerned with are CDC (which stands for Communication Device Class, and sub-classes of which include ACM, WCM and OBEX), Mass Storage, and the Imaging Class (for Media Transfer Protocol communication). |
bDeviceSubClass |
If the personality you are configuring supports only a single sub-class, then you can specify that sub-class in this field. (Note as mentioned above that ACM, WMC and OBEX are all sub-classes of the USB device class CDC.) The value you specify will then determine the content of the bDeviceSubClass field in the Device Descriptor that the device sends to the USB host. However, if the personality supports multiple sub-classes, then you need to specify zero for this field and then specify the sub-classes individually when you implement the device's USB interface definitions. For information about the sub-classes for different types of USB communication, refer to the class specification documents on the USB Implementers Forum website: http://www.usb.org/developers/devclass_docs#approved. |
protocol |
The value you specify for this field determines the content of the bDeviceProtocol field in the Device Descriptor that the device will send to the USB host. For information about the protocol to specify for a particular class, refer to the class specification documents on the USB Implementers Forum website: http://www.usb.org/developers/devclass_docs#approved. |
numConfigurations |
The value you specify for this field determines the content of the bNumConfigurations field in the Device Descriptor that the device will send to the USB host. Specify 1. Symbian platfprm devices should not offer the USB host a list to choose from to determine the type of USB peripheral that the device will then present itself as. Instead, the device should just present itself to the host and announce itself as whatever it is (in other words, as whatever its bDeviceClass field says it is). |
vendorId |
The value you specify for this field determines the content of the idVendor field in the Device Descriptor that the device will send to the USB host. You need to request a vendor ID on behalf of your company from the USB Implementers' Forum. |
productId |
The value you specify for this field determines the content of the idProduct field in the Device Descriptor that the device will send to the USB host. (Symbian's vendorId is 0x0E22.) Make sure you use a productId that does not duplicate that of another model of device within your company. Your company is responsible for managing its own productIds. |
bcdDevice |
The value you specify for this field determines the content of the bcdDevice field in the Device Descriptor that the device will send to the USB host. Specify 2 (0x0200). This field states the version of the USB specification that your device conforms to. |
manufacturer |
The value you specify for this field determines the content of the string referenced by the iManufacturer field in the Device Descriptor that the device will send to the USB host. This is a text string that identifies your company. It needs to be human-readable, because the USB host might display it on the PC screen. |
product |
The value you specify for this field determines the content of the string referenced by the iProduct field in the Device Descriptor that the device will send to the USB host. This is a text string that identifies your product. It needs to be human-readable, because the USB host might display it on the PC screen. |
id |
The value you specify for this field does not form part of the Device Descriptor that the device will send to the USB host. It specifies a number for the personality you are defining. The value is not seen by the USB host but the application you write to start USB services in response to a cable-insertion event will pass the value to the USB Manager when it requests USB services. The value tells USB Manager which personality to use when it starts USB services. The value you specify eneds to be an unsigned integer. |
class_uids |
The value or values you specify for this field do not form part of the Device Descriptor that the device will send to the USB host. The class_uids you specify tell the USB Manager (inside the Symbian device) which Symbian class controllers to start for the personality it has invoked. Although a Symbian device should only offer one configuration at a time to the remote USB host, you can configure the device to perform different types of USB communication at the same time (for example, WCM and ACM). In this case, you need specify more than one class_uid in a comma-separated list. You can combine class_uids in a single personality for any types of USB communication that share the same bDeviceClass value (see above in this table). It is worth noting that the term "class_uids" is Symbian-specific and that class-uids do not always correspond to USB classes. For example, some values that you can specify in this field designate Symbian "class controllers" that correspond to USB sub-classes (ACM, WCM or OBEX) and not to full USB classes; others do correspond to full USB classes (for example, Mass Storage). Some of the available class_uids are: ACM (101fbf22), WCM or Obex (101fbf24), Mass Storage (10204bbc), Media Transfer Protocol (102827b3). When the USB Manager has started a class controller in the device, the class controller sets up the USB interfaces and endpoints required for the device classes specified in the class_uids field. Do not specify a class_uid for which you do not intend (later on when you build the ROM image) to include a corresponding class controller. When you start USB services on the device, the USB Manager component of Symbian platform performs a cross-check between the class_uids specified in the compiled version of the resource file and the class controllers actually loaded; if there is a discrepancy, the USB Manager will return an error. |
description |
The value you specify for this field does not form part of the Device Descriptor that the device will send to the USB host. This field needs to describe what the personality is for in human-readable form, so that the Symbian device you are designing can (if necessary) present it to the user. For example, you might want the device to present the description to confirm a menu choice (such as "Modem" or "File Transfer") that the end user has made. |
When you have specified the values you require for one personality, you can add another. The example below shows how to add a personality for the Mass Storage class of device (enabling the phone to transmit or receive file transfers over USB):
RESOURCE PERSONALITY_ARRAY device_personalities { personalities = { PERSONALITY { bDeviceClass = 02; bDeviceSubClass = 0; protocol = 0; numConfigurations = 1; vendorId = 0x0e22; productId = 0x000b; bcdDevice = 0x0200; manufacturer = "ACME"; product = "Widget"; id = 1; class_uids = "101FBF22, 101fbf24"; \\ACM and WCM class_uids description = "Modem"; } PERSONALITY { bDeviceClass = 0; bDeviceSubClass = 0; protocol = 0; numConfigurations = 1; vendorId = 0x0e22; productId = 0x000b; bcdDevice = 0x0200; manufacturer = "ACME"; product = "Widget2"; id = 2; class_uids = "10204bbc"; \\Mass Storage class_uid description = "File Transfer"; } }; }
Proceed to the next section which tells you how to build .rss file.
Building the personalities resource (.rss) file
Resource files are built by the inclusion of a start resource statement in a .mmp file. (For more information about this, click on start resource.) However, .mmp files must always produce an executable. Therefore, you will need to include the logic for building your personalities resource file inside an .mmp file that you are using to produce an executable that does something else to do with USB.
The most likely scenario is that you will include it in the .mmp file that produces the executable for a USB monitor application. You need a USB monitor application to monitor for USB cable insertion and removal events and to request the USB Manager component of the USB subsystem to start and stop USB services in response to such events.
For this reason and for purposes of illustration, the instructions in this tutorial use a sample .mmp file called usbmonitor.mmp that does not contain any logic beyond what is explicitly required to build the necessary resource file (plus a minimum of auxiliary code required to execute that logic). The code you need to re-use or adapt in your monitor (or other USB-related) application is the start resource statement.
To build the resource (.rss) file that you created in the previous section, do the following:
In the \usbconfig directory, create a file called bld.inf that contains at least the following information:
PRJ_PLATFORMS ARMV5 PRJ_MMPFILES usbmonitor.mmp
Note that, by specifying the ARMV5 platform, you are limiting the build process to this target platform. We recommend you do this for USB-specific builds, because it makes no sense to run USB code on, for example, the Symbian emulator for Windows (no physical USB connection being possible from the emulator to a USB host on the same Windows PC as the emulator).
In the same directory, create another file called usbmonitor.mmp that contains at least the following information:
// usbmonitor.mmp // // Copyright (c) 2005-2007 Symbian Ltd. All rights reserved. // TARGET usbmonitor.exe TARGETTYPE exe UID 0x0 0x10285838 VENDORID 0x70000001 //Replace this value with your own vendor ID SOURCEPATH src //This tells the resource compiler where to look for the .rss file when you run abld SOURCE usbmonitor.cpp SYSTEMINCLUDE \epoc32\include // The C++ pre-processor needs this value to find // the header files included in the // cpp source file. // The three following lines are the ones that build the resource file START RESOURCE usbconfig.rss TARGETPATH \private\101fe1db END CAPABILITY NetworkControl LIBRARY euser.lib
In the same directory, create a sub-directory called, for example, \src.
In the new sub-directory, create a source file called, for example, usbmonitor.cpp, containing at least the following information:
#include <e32std.h> TInt E32Main() { return KErrNone; }
Build the executable and resource files by typing the following commands at the command prompt in the \usbconfig directory:
bldmake bldfiles
abld build
For information about the syntax of, and command-line options associated with, the abld command, click here.
To see a list of the files that will have been generated if the build has been successful, type:
abld -w build
Sample output is provided below:
I:\usbconfig>abld -w build \epoc32\data\z\private\101fe1db\usbconfig.rsc \epoc32\localisation\group\usbconfig.info \epoc32\localisation\usbconfig\rsc\usbconfig.rpp \epoc32\release\armv5\udeb\usbmonitor.exe \epoc32\release\armv5\udeb\usbmonitor.exe.map \epoc32\release\armv5\urel\usbmonitor.exe \epoc32\release\armv5\urel\usbmonitor.exe.map
The most important file to notice in this list is the .rsc file (usbconfig.rsc). This is the compiled version of the resource file (it is generated by the build process from the .rss file that you created earlier in this tutorial).
To check exactly which files, if any, have failed to build, type the following:
abld -c build
(The -c option returns a list of the files that failed to build. If all built successfully the list will be empty, so no results will be displayed.)
Proceed to the next section and follow the instructions on editing the usbman.iby file.
Editing the usbman.iby file that specifies the target locations of files in the ROM
Before you build a ROM image containing the USB personalities you have specified in the .rss resource file, you need to edit a file called usbman.iby. (.iby files contain information supplementary to the .oby files; they, in combination with the .oby files, tell the ROM build process which files to include in the ROM image and where to put them.)
To edit the usbman.iby file correctly for the device you are designing, do the following:
On the development drive, locate the usbman.iby file in the following location: \epoc32\rom\include.
Save a copy of this file somewhere else on the development drive. (You are going to edit the current version, but you may need to revert to the original in future.)
In the current version of the usbman.iby file (not the version you have saved to another location), delete the entire block of text from (and including) the following two lines:
DEFINE __USBMAN_RSC_ZPATH__ ZPRIVATE\101fe1db DEFINE __USBMAN_RSC_PATH__ PRIVATE\101fe1db
to (and including) the following line:
#endif //__OBEX_OVER_USB__
Replace the text block you have just deleted with the following line:
data=ZPRIVATE\101fe1db\usbconfig.rsc PRIVATE\101fe1db\usbman.rsc
The text you deleted in the previous step contained internal Symbian macros telling the build tools how to decide which of many possible .RSC files to use; the line you have replaced the deleted text with simply tells the build tools to use the .rsc file (usbconfig.rsc) you generated in the previous section of this tutorial. The path on the left (in the line you have added) specifies the location of the usbconfig .rsc file on your development drive; the path on the right specifies its location in the ROM image.
Delete the following lines (these relate to a dummy class controller that is used for internal Symbian testing):
// *** 'buildrom -D__USBMAN_DUMMYCC__' will use the dummy Class Controller // *** build of USBSVR for testing purposes. #ifdef __USBMAN_DUMMYCC__ #include <dummyccinifiles.iby> file=ABI_DIR\USB_DIR\t_usbman_dummycc.exe System\Programs\usbsvr.exe #else
Retain the next line (see below) but delete the #endif keyword on the line immediately after it:
file=ABI_DIR\USB_DIR\usbsvr.exe System\Programs\usbsvr.exe
If you have one or more personalities that include the ACM (Abstract Control Model) class_uid, then make sure you retain the the following text:
// *** Abstract Control Model (serial emulation) Class Controller. #ifdef __ACM_REGPORT__ USB_PLUGIN(t_regport_acmclasscontroller.dll,101fbf20.rsc) #else USB_PLUGIN(acmclasscontroller.dll,101fbf20.rsc) #endif
If you are not using the Symbian reference plug-in for USB charging, then delete the text below. If you are intending to use the Symbian reference plug-in for USB charging, retain this text. If you are intending to support USB charging but not to use the Symbian reference plug-in to support it, you must include an equivalent of this text (appropriate to your implementation) in the usbman.iby file.
#ifdef WITH_REFERENCE_USB_CHARGING_PLUGIN // *** Reference battery charging plug-in and its cenrep file USB_PLUGIN(usbbatterychargingplugin.dll,10208DD7.rsc) data=EPOCROOT##epoc32\data\z\private\10202be9\10208DD7.txt private\10202be9\10208DD7.txt #endif
If you have one or more personalities that include the ACM (Abstract Control Model) class_uids, retain the following line:
file=ABI_DIR\USB_DIR\acmserver.dll acmserver.dll
If you have included WHCM (Wireless Handset Control Model, otherwise known as WMC or Wireless Mobile Communications) support in any peronalities for the device, retain the following text:
// *** WHCM Class Controller - used for OBEX over USB. USB_PLUGIN(whcmclasscontroller.dll,101fbf23.rsc)
If you have included Mass Storage support in any personalities for the device, retain the following text :
// *** Mass Storage Class Controller. USB_PLUGIN(msclasscontroller.dll,10204bbb.rsc) data=ZPRIVATE\10204bbb\usbms.rsc PRIVATE\101fe1db\usbms.rsc #ifdef WITH_MASS_STORAGE_EXAMPLE_APP file=ABI_DIR\USB_DIR\usbmsexampleapp.exe usbmsexampleapp.exe #endif
Delete (or leave commented out) the lines below concerning Obex. Symbian do not provide a generic Obex class controller; this is software that Licensees must develop themselves, tailoring it to the particular Obex service required.
// *** OBEX Class Controller. This is test code, used for descriptor checking // *** only. // USB_PLUGIN(Obexclasscontroller.dll,101fbf27.rsc)
Finally, by default, the Symbian ACM class controller registers a single ACM instance with the USB device driver on the phone. If you are using ACM in any of your personalities and you want the ACM class controller to register more than one ACM instance with the driver (for example, you might want one instance to provide a modem function and another to provide debugging information) you must uncomment the last one of the following lines and then edit the NumberOfAcmFunctions.ini file.
// *** Uncomment the following file and modify if the number or type of ACM // *** Functions required is different from the default // data=ZPRIVATE\101fe1db\NumberOfAcmFunctions.ini private\101fe1db\NumberOfAcmFunctions.ini
The location of the NumberOfACMFunctions.ini file on your development drive is indicated by the path on the left (in the line you have just uncommented); its target location on the ROM is indicated by the path on the right (in the same line). If you require two instances (in other words, if you require two logical serial port channels over USB), then you must specify two as the value for NumberOfAcmFunctions (as in the example below).
[ACM_CONF] NumberOfAcmFunctions= 2 [ACM 1] ProtocolNum= 1 //0x01 - code taken from USBCDC 1.1 Table 17- Hayes compatible modem //[AMC 2] //ProtocolNum= 255 //0xFF - Vendor-specific
Note that altering the number of ACM functions in this way does not give you two ACM class controllers, but it does give you two logical serial port channels.
Proceed to the next section and follow the instructions for building the ROM image.
Building the ROM image and connecting the device to the USB host
When you have configured the usbman.iby file correctly for the type of USB device your phone will present itself as to the USB host, you are ready to build the ROM image, load it onto your target hardware, and connect to the USB host.
To do these things, follow the instructions below:
On the development drive, change to the directory \epoc32\rom.
In this directory, type the following command (note that, unless you are using the h4 hardware reference platform, you must replace "h4hrp" with the correct parameter for your target hardware):
buildrom h4hrp techview
Most of the output that you see on the screen when you run this command reports on the conversion of individual files to their compiled version. However, the end of the screen output is given below and contains a list of the files generated as a result of running the buildrom command:
I:\epoc32\rom>buildrom h4hrp techview I:\epoc32\rom>rem @echo off I:\epoc32\rom>setlocal I:\epoc32\rom>perl -S buildrom.pl h4hrp techview Defaulting to ARMV5 //... omitted output ... ROMBUILD - Rom builder V2.08 (Build 582) Copyright (c) 1996-2007 Symbian Software Ltd. Writing uncompressedRom image with repro header to file h4hrp_001.techview.IMG * Writing h4hrp_001.techview.symbol - ROM symbol file Volume in drive I is NEW PGPDISK Volume Serial Number is 3431-1FFC Directory of I:\epoc32\rom 23/08/2007 10:38 138,272 h4hrp_001.techview.oby 23/08/2007 10:38 131,971 h4hrp_001.techview.dir 23/08/2007 10:38 21,475,584 h4hrp_001.techview.IMG 23/08/2007 10:38 1,547,621 h4hrp_001.techview.log 23/08/2007 10:39 32,720,563 h4hrp_001.techview.symbol 5 File(s) 56,014,011 bytes 0 Dir(s) 1,049,788,416 bytes free
Before copying the ROM image onto the target hardware, you may want to inspect the .dir file that is amongst the five files output by the buildrom command. The .dir file lists all the files included in the ROM image and specifies their locations both on the development drive (in the lefthand column) and in the ROM image (in the righthand column).
Rename the .IMG file to sys$rom.bin.
Transfer the sys$rom.bin file on to your target hardware. (If you are using a hardware reference platform, copy it onto a memory card and insert the memory card into the correct slot on the board.)
Install the USB host drivers on to the Windows PC you intend to connect the device to. To do this for ACM transfers, copy the .INF files from sf/os/shortlinksrv/usbmgmt/usbmgr/device/inf-files into the following directory on your target Windows PC: C:\WINNT\INF.
(Note that the Symbian driver for both Windows 2000 and Windows XP is called Symusb2k-XP.inf; it invokes Microsoft's USBSER.SYS driver.) At the time of writing, information about the drivers required to support other USB classes and Symbian class controllers is not available.
Use a USB cable to connect the board physically to the Windows PC.
Boot the hardware you have transferred the ROM image to.
Once the ROM image has finished loading on the board (or phone) you are booting, start its Control Panel and select the USB icon.
Switch on USB by pressing the "On" radio button.
When Windows detects your hardware as a new USB device, it will start a "New Device Driver" wizard. Tell it to search for a suitable driver, then on the next screen select "Specify a location" and specify the correct device driver for the device you are using.
If the "New Device Driver" wizard does not start on Windows, then the driver may already be installed on your PC. You can check that the drivers are correctly installed by clicking on "System" in the Control Panel, then selecting the Hardware tab and bringing up the Device Manager.
When you switch USB services on from the Control Panel on the developer board or phone, the modem driver will appear (in the Windows Device Manager on your PC) as "Lubbock" under the Modems section if the driver is correctly installed. (If you have included Obex in your ROM build, the Obex driver will appear as "TUSBOBEX device" under the "Universal Serial Bus Controllers" section.)
When you can direct Windows to a driver in response to its prompt, then your installation and configuration are complete. Note that, when you open up a session to USB Manager (which is what happens when you turn USB services on using the Control Panel on your development board or phone) USB Manager cross-checks the class_uids in the .RSC file against the class controllers that are actually present in the ROM. Therefore, if any personalities in your .RSC file require a class controller that is not present in the ROM, you will receive an error when you start USB services.