This document introduces you to the USB Battery Charging Plug-in library usbbatterychargingplugin.dll. You need to read it in conjunction with The USB Manager Extension Plug-in Library Overview.
The USB Battery Charging Plug-in library is Symbian's reference implementation of the client for the Ecom interface called the USB Manager Extension Plug-in library.
Its purpose is to enable a Symbian device to negotiate with a USB host to draw power to charge the Symbian device's battery.
Intended Audience
This document is for Symbian licensees who are implementing support for battery charging over USB on a Symbian device.
The USB Battery Charging Plug-in Library Details
The DLL that provides the functionality and the library to which your code must link are identified below.
| DLL | LIB | Short description |
|---|---|---|
usbbatterychargingplugin.dll |
usbbatterychargingplugin.lib |
A Symbian reference implementation of the client for the Ecom interface provided by usbmanextensionplugin.dll. The client implementation, combined with its Ecom interface, extends the functionality of the USB Manager by providing support for battery charging over USB. This extension of functionality is achieved without Licensees needing to re-compile the USB Manager. |
This library is a Symbian reference implementation of the client to the Ecom interface that is provided by the USB Manager Extension Plug-in library. It contains the main state machine that controls battery charging over USB.
The battery charging plug-in works by using the transitions of USB device states (provided by the Ecom interface) to:
Start charging (when the device is in a "configured" state)
Stop charging (when the device is not in a "configured" state)
Publish different configuration descriptors (when an attempt at enumeration with one bMaxPower setting has failed to put the device into a "configured" state);
The battery charging plug-in also re-enumerates the bus each time it publishes a new configuration descriptor.
To request power from the USB host, the USB battery charging client implementation needs a set of electrical current values. It gets these from a text file called 10208DD7.txt, whose contents need to be written to the Central Repository's private data cage (see Specifying the electrical values to request). A Symbian reference version of this file is provided at the location sf/os/shortlinksrv/usbmgmt/usbmgr/usbman/chargingplugin/group/. It has the following default values:
500mA; this is the maximum that a USB device can request from a USB host
100mA: this is the minimum that an un-powered USB device requires from the USB host merely to operate
The battery charging plug-in takes the highest value first and uses that value to set the bMaxPower field in the configuration descriptor. If the host does not accept this value it tries the next highest value and so on.
The battery charging client implementation also needs to control the battery charging circuitry on your target hardware. It instantiates a class called CUsbChargingLicenseeHooks for this. But Symbian do not implement this class, because the implementation details will be hardware-specific. However, it provides stubs in the CUsbBatteryChargingLicenseeHooks.h file) for the functions you need to implement. Apart from the constructors (a NewL function for which is implemented by Symbian) you need to implement the functions for:
As well as the 10208DD7.txt file there is a 10208DD7.rss file for the USB battery charging client. This provides the client with the UID details which Ecom uses to identify it. A Symbian reference version of this file is provided at the location sf/os/shortlinksrv/usbmgmt/usbmgr/usbman/chargingplugin/src/.
The key classes belonging to the USB Battery Charging Plug-in library are listed in the table below.
| Classes | Description |
|---|---|
This class is defined in the cusbbatterychargingplugin.cpp Symbian reference file. It contains all of the main functionality by which charging is achieved (including setting the configuration descriptor, monitoring the state of the USB device, and calling the licensee-defined functions for starting and stopping charging). |
|
This class is defined in the cusbbatterycharginglicenseehooks.h Symbian reference file. Most of its constructor functionality and all of its charging circuitry control functions need to be implemented by licensees. |
|
MUsbChargingRepositoryObserver and CUsbChargingRepositoryNotifier |
This mixin class and active object combination is responsible for notifying the battery charging plug-in of changes in the Central Repository settings that specify the power values that the USB device can attempt to negotiate with the host. If these get modified by an application, the reference charging plug-in must take account of the new settings and renegotiate with the USB host. |
MUsbChargingDeviceStateTimerObserver and CUsbChargingDeviceStateTimer |
This mixin class and active object combination is a wrapper for getting a callback into the reference charging plug-in after a timeout. It is used to limit the time that the plug-in allows the USB host to put the Symbian device into a "configured" state. If the timeout elapses, the plug-in sets the next available current value as the bMaxPower value in the configuration descriptor and forces a re-enumeration of the bus. |
This is a simple active object that issues the ReEnumerate() request to the Logical Device Driver and waits for an asynchronous response. The battery charging eference plug-in uses it to force a re-enumeration of the bus. |
To use the USB battery charging client implementation, you need to:
Make sure the text file is in the Central Respository's private data area and that it is configured with an appropriate set of power values.
Implement the software that interfaces between the battery charging plug-in and the charging circuitry on your target hardware.
Specifying the electrical values to request
This section shows the contents of the Symbian reference file called 10208DD7.txt. This is the file that Symbian use to specify the electrical values for the reference client implementation to request. You can rename it for your implementation if you require.
The Symbian file is provided at the location sf/os/shortlinksrv/usbmgmt/usbmgr/usbman/chargingplugin/group. Its contents are written to the Central Repository's private data cage when you use the WITH_REFERENCE_USB_CHARGING_PLUGIN macro 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
The last two lines of this text file are where the electrical values are specified. As you can see, the first is 500 by default and the second is 100. You can specify other values instead or as well. For example, 0mA is the current that a USB device agrees to draw from a USB host that is an On-The-Go device (and therefore cannot necessarily spare any current to charge another device's batteries).
cenrep version 1 [platsec] # default capabilities for this repository cap_rd=AlwaysPass cap_wr = WriteDeviceData [main] # 0x01 int 1 0 0x02 int 2 1 0x1000 int 500 1 0x1001 int 100 1
We do not recommend you change any of the platform security details (in the section called [platsec]).
Interfacing between the battery charging client and the charging circuitry
The Symbian reference client does not implement the software that starts and stops charging on the circuitry in your hardware.
However, it provides a class called CUsbBatteryChargingLicenseeHooks which contains stubs of functions to enable you to do this yourself.
You need to implement the constructors (except for the NewL function, which is provided by Symbian) and the functions called CUsbBatteryChargingLicenseeHooks::StartCharging() and CUsbBatteryChargingLicenseeHooks::StopCharging().