Monitoring VBus, ID-pin, OTG state and bus activity

Purpose

There are four publish-and-subscribe keys associated with the USB Manager. These enable you to monitor the following OTG variables on a Symbian platform phone:

• The status of the ID-pin

• VBus power

• The OTG state

• The bus connection status

The category for all of these properties is: KUidUsbManCategory. It is defined in the file ... epoc32\include\usbotgdefs.h.

Note: The USB Manager must be running for the publish-and-subscribe values described in this document to get published. In other words, to start publication of these values, you need to have a session open from an RUsb object to the USB Manager server (see Starting the USB Manager server).

Intended Audience

This document is for Symbian licensees who are implementing USB services, including host and On-The-Go services, on a Symbian device.

Required Background

For details of, and links to, the USB and OTG specifications on the USB Implementers Forum website, see The USB Manager library.

For information about Symbian's publish-and-subscribe facility, see Publish and Subscribe.

Setup and Configuration Requirements

The device you are developing code for needs to have Symbian's USB client stack included in the ROM.

Using the USB Manager's publish-and-subscribe keys

Basic Procedure

The high-level steps for monitoring USB services using the USB Manager publish-and-subscribe keys are shown here:

1. Start the USB Manager server

2. Monitor whether ID-pin is present

3. Monitor whether VBus is powered

4. Monitor the Symbian platform phone's USB host/OTG state

5. Monitor whether the phone's bus connection is idle or busy

Starting the USB Manager server

To make the USB Manager start publishing its publish-and-subscribe values, you must first start the USB Manager server. The way to do this is simply to set up a session to it:

RUsb usb;        //Create a USB Manager client instance
usb.Connect()    //Start the USB Manager server by setting up a connection to it from the client 

Monitoring whether ID-pin is present

The USB Manager library's publish-and-subscribe category is: KUidUsbManCategory. It is defined in the file ... epoc32\include\usbotgdefs.h.

The ID-pin is an extra pin in a micro-USB connector that allows the micro-AB port to identify whether an A-plug is present or not; note, however, that the micro-AB port does not infer from the absence of the ID-pin that a B-plug is present. The absence of an ID-pin could mean that a B-plug is connected or that no plug is connected.

The ID-pin property key is KUsbOtgIdPinPresentProperty. When the value of this property key is ETrue, an A-plug is connected to the phone; when the value is EFalse, no A-plug is connected to the phone.

When the appearance of an ID-pin is detected, it means that a user has attached the A end of a USB cable to the phone's USB connector, presumably in order to use USB. Therefore, your USB control application must start USB services (if they are not already running) by calling the RUsb::TryStart() function (see The conditions for starting USB services and Starting USB services). The control application can then call the RUsb::BusRequest() function to attempt to make the phone become the USB host (see Controlling when the phone is the USB host).

To monitor whether ID-pin is present:

1. Create an RProperty object for the USB Manager's ID-pin property and attach to it.

   RProperty idPinProp;    //Create an ID-pin property object
   User::LeaveIfError(idPinProp.Attach(KUidUsbManCategory, KUsbOtgIdPinPresentProperty));  //Attach to it

   The above example creates an RProperty object called idPinProp.

2. To receive a notification message next time the status of the ID-pin changes, subscribe to the new object's KUsbOtgIdPinPresentProperty key. For example:

   TRequestStatus status;
   idPinProp.Subscribe(status);             //Subscribe for notification next time the status changes
   User::WaitForRequest(status);

   Note: The RProperty::Subscribe() function is an asynchronous function; you can only have one call to it pending at a time. To ensure that you do not miss a status change, you must renew the function call every time the function returns, and then immediately call the RProperty::Get() function (see next step).

3. To retrieve the current state of ID-pin, after receiving a notification that its status has changed, call the RProperty::Get() function for your ID-pin publish and subscribe object. For example:

   TInt val;
   idPinProp.Get(val);

   Note: The value returned by the RProperty::Get() function is of type TInt but that it needs to be treated as a Boolean (ETrue, EFalse).

   Note:

Monitoring whether VBus is powered

The USB Manager library's publish-and-subscribe category is: KUidUsbManCategory. It is defined in the file ... epoc32\include\usbotgdefs.h.

VBus is the wire in a USB connector through which an A-device indicates its presence to a B-device. The A-device does this by putting a voltage on to the wire. If the A-device has a sufficiently powerful power supply, it can also permit the B-device to draw up to 500mA of power from it across VBus (although in practice it is unlikely that an OTG device would or could supply this much current).

Your USB control application needs to monitor the VBus property key so that, whenever the phone is a B-device and it detects that VBus is powered, it can start USB services. If the phone is a B-device and an A-device applies power to VBus, this means that an application on the A-device wants to communicate with the B-device and that the A-device is prepared to enumerate the B-device. That's why in this condition, it is necessary to start USB services if they are not already running; see The conditions for starting USB services. Similarly, if the phone is a B-device and you detect that VBus is down, then you need to stop USB services (see Stopping USB services).

The VBus property key is KUsbOtgVBusPoweredProperty. When the value of this property key is 1, VBus is powered; when the value is 0, VBus is not powered.

To monitor whether VBus is powered:

1. Create an RProperty object for the USB Manager's VBus property and attach to it.

   RProperty vBusProp;                           //Create a VBus state property object
   User::LeaveIfError(vBusProp.Attach(KUidUsbManCategory, KUsbOtgVBusPoweredProperty)); //Attach to it

   The above example creates an RProperty object called vBusProp.

2. To receive a notification message next time the status of the VBus property changes, subscribe to the new object's KUsbOtgVBusPoweredProperty key. For example:

   TRequestStatus status;
   vBusProp.Subscribe(status);      //Subscribe for notification next time the VBus status changes
   User::WaitForRequest(status);

   Note: The RProperty::Subscribe() function is an asynchronous function; you can only have one call to it pending at a time. To ensure that you do not miss a status change, you must renew the function call every time the function returns, and then immediately call the RProperty::Get() function (see next step).

3. To retrieve the current state of the VBus, call the RProperty::Get() function for your VBus publish-and-subscribe object. For example:

   TInt val;
   vBusProp.Get(val);

   Note: The value returned by the RProperty::Get() function is of type TInt but that it needs to be treated as a Boolean (ETrue, EFalse).

   Note: to make sure you do not miss a change in the status of the property key, we recommend you re-susbscribe

Monitoring the phone's USB host/OTG state

The USB Manager library's publish-and-subscribe category is: KUidUsbManCategory. It is defined in the file ... epoc32\include\usbotgdefs.h.

The USB Manager property key for monitoring OTG state is KUsbOtgStateProperty. The following table lists its possible values and their meanings:

These values are defined in an Enum called TUsbOtgState. (The Enum is defined in the file ... epoc32\include\usbotgdefs.h.)

For more information about the OTG states and their significance for the USB control application, see OTG state transitions on a Symbian platform phone.

To monitor the Symbian platform phone's OTG state machine:

1. Create an RProperty object for the USB Manager's OTG state machine property and attach to it.

   RProperty otgStateProp;                           //Create an OTG state property object
   User::LeaveIfError(otgStateProp.Attach(KUidUsbManCategory, KUsbOtgStateProperty)); //Attach to it

   The above example creates an RProperty object called otgStateProp and attaches to it.

2. To receive a notification message next time the phone's OTG state changes, subscribe to the new object's KUsbOtgStateProperty key. For example:

   TRequestStatus status;
   otgStateProp.Subscribe(status);      //Subscribe for notification next time the OTG state changes
   User::WaitForRequest(status);

   Note: The RProperty::Subscribe() function is an asynchronous function; you can only have one call to it pending at a time. You must renew the function call every time the function returns.

3. To retrieve the current state of the phone's OTG state machine, after receiving a notification that its status has changed, call the RProperty::Get() function for your OTG state publish-and-subscribe object. For example:

   TInt val;
   otgStateProp.Get(val);

   Note: The value returned by the RProperty::Get() function is of type TInt but that this value is an ordinal indicating a member of an Enum. For a list of the possible TInt values, the OTG states they each correspond to, and the meaning of these states, see the table above.

Monitoring whether the phone's bus connection is idle or busy

The USB Manager library's publish-and-subscribe category is: KUidUsbManCategory. It is defined in the file ... epoc32\include\usbotgdefs.h.

The USB Manager property key for monitoring whether the phone's bus connection is idle or busy is KUsbOtgConnectionIdleProperty. The purpose of this property key is to enable a USB control application to decide whether to drop VBus or not. Your control application must only drop VBus when the value of this property key is ETrue. (Except in exceptional circumstances, it must never drop VBus when the value is EFalse.)

To monitor the Symbian platform phone's bus connection to decide when to drop VBus:

1. Create an RProperty object for the USB Manager's bus connection property and attach to it.

   RProperty otgConnectionIdleProp;              //Create a bus connection property object
                                                 //Attach to it
   User::LeaveIfError(otgConnectionIdleProp.Attach(KUidUsbManCategory, KUsbOtgConnectionIdleProperty));
   ... 

   The above example creates an RProperty object called otgConnectionIdleProp and attaches to it.

2. To receive a notification message next time the phone's bus connection state changes, subscribe to the new object's KUsbOtgConnectionIdleProperty key. For example:

   TRequestStatus status;
   otgConnectionIdleProp.Subscribe(status); //Subscribe for notification next time the bus connection status changes
   User::WaitForRequest(status);

   Note: The RProperty::Subscribe() function is an asynchronous function; you can only have one call to it pending at a time. To ensure that you do not miss a status change, you must renew the function call every time the function returns, and then immediately call the RProperty::Get() function (see next step).

3. To retrieve the current state of the phone's bus connection (after receiving a notification that its status has changed, and then re-queuing for the next notification) call the RProperty::Get() function for your bus connection object. For example:

   TInt val;
   otgConnectionIdleProp.Get(val);

   Note: The value returned by the RProperty::Get() function is of type TInt. but that it needs to be treated as a Boolean (ETrue, EFalse). When the value returned is ETrue, the bus connection is idle and the control application can drop VBus. When the value returned is EFalse, the bus connection is active and the control application must not drop VBus.

   For information about dropping VBus, see Dropping VBus.