塞班传感器编程

 

塞班传感器编程

 

        塞班系统于v9.3开始支持传感器，从S60第五版SDK正式公布传感器接口(sensor API)。

        传感器接口(sensor API)提供给用户侦听和接收来至传感器数据的功能，它包括两个部分：通道接口(Channel API)和定义接口(Definitions API)。Channel API定义了传感器的基本功能和作用，Definitions API描述了各种传感器数据定义上的特征。

        通道也提供有条件的侦听数据，通道的属性也可以通过API配置，如数据频率。

 

通道种类(channels)

        加速器(accelerometer)、旋转(rotation)、方向(orientation)、双击(double-tap)、距离(proximity)、环境光(ambient light)、罗盘或指北针(magnetic north)、磁力(magnetometer XYZ)。

        1> 加速器(accelerometer)

        加速器通道测量设备在三维笛卡尔坐标系下的加速度。设备沿X轴正向移动的时候，加速度为正值；沿X轴反向移动的时候，加速度为负值。

 

        图：Z轴正向与屏幕朝向一致。

 

        2> 旋转(rotation)

        探测围绕三维笛卡尔坐标轴的旋转量。(值范围0-359度)

        图如上

 

        3> 方向(orientation)

        如下图相机有六个基本方向。

 

        图

 

        4> 双击(double-tap)

        双击通道当双击发生时发出事件，发送的事件数据用掩码(bitmask)表示双击发生的方向。

 

        5> 距离(proximity)

        距离传感器通道使用二进制位表示，设备是否接近人体。当该状态无法判断时，状态值为undefined。

 

        6> 环境光(ambient light)

        环境光传感器通道返回光线强度百分比。(0-100)

 

        7> 罗盘或指北针(magnetic north)

        罗盘传感器通道返回设备跟北极的顺时针夹角。(0-359)

 

        8> 磁力(magnetometer XYZ)

        返回磁场强度。

 

用例

        通道侦听用例

                查找、打开、关闭通道

                侦听数据

                侦听变化

 

        通道属性用例

                获取通道属性

                设置通道属性

                属性数组

                缩放通道数据

                侦听通道属性的变化

 

        条件侦听

                条件侦听

 

类结构

        一个物理传感器可以提供几种类型的数据，通道(channel)则是提供来至物理传感器的某种特定类型的数据。例如，磁力传感器就提供了磁力通道和罗盘通道。

 

        图：传感器类的简图

        上图显示一种物理传感器提供着几种通道(CSensrvChannel)，通道通过MSensrvDataListener::DataReceived()回调接口提供了特定类型的数据(如 TSensrvXyzData)，每个通道都对应着一个TSensrvChannelInfo结构来描述和查找，每个通道拥有多个属性(TSensrvProperty)，每个属性可以通过ID和索引(index)来引用。

 

        CSensrvChannelFinder提供查找通道的方法。继承MSensrvChannelListener接口，可以侦听到可用通道的变换，例如新通道被安装到设备时。

        CSensrvChannel提供打开和控制通道的方法。

                1> CSensrvChannel开始和停止侦听，MSensrvDataListener接口接收数据。

                2> CSensrvChannel开始和停止有条件侦听，MSensrvChannelConditionListener接口接收数据。CSensrvChannelConditionSet 和 CSensrvChannelCondition 封装条件。

                3> get和set获取和设置通道属性，MSensrvPropertyListener接口属性的变化。

 

        图：类图

 

        客户端使用NewL创建C类的实例，继承并实现M类接口，并把M类的接口指针指派给相关函数用来接收数据。

 

使用传感器API

        要使用通道，客户端必须先查找并打开它。CSensrvChannelFinder提供了查找的方法，CSensrvChannel提供了打开的方法。

        不同的设置支持不同的通道。SDK定义了所有可能的通道，每个通道都有一个不变的唯一的ID和简述。例如下面的双击通道，它提供两种具体的通道，原数据通道(raw data channels)和事件通道(event channels)。原数据通道提供连续性数据，而事件通道提供事件提醒。

                /**

                  * - Name:          Double tapping event channel type

                  * - Type:          Event

                  * - Datatype:      TSensrvTappingData

                  * - Description:   Double tapping events 

                  */

                const TSensrvChannelTypeId KSensrvChannelTypeIdAccelerometerDoubleTappingData = 0x10205081;

        每个通道的数据类型都在各自的头文件里有定义，它描述了通道可以提供的数据的类型。如下是双击通道的。

                  class TSensrvTappingData 

                      {

                  public:

                      /**

                      * Channel data type Id number

                      */

                      static const TSensrvChannelDataTypeId KDataTypeId = 0x1020507F;

 

                      /**

                      * Channel data type enumerations

                      */

                      enum TSensrvAccelerometerAxisDataIndexes

                            {

                            iTimeStamp = 0,

                            iDirection

                            };

                          };

                  public:

                      /**

                      * - Item name:   Sampling time.

                      * - Item Index:  0

                      * - Conditions:  None

                      * - Description: Timestamp for a sample.

                      */   

                      TTime iTimeStamp;    

 

                      /**

                      * - Item name:   Tapping direction bitmask

                      * - Item Index:  1

                      * - Conditions:  Binary

                      * - Description: Direction bitmask of the tapping event.

                      *                See constant definitions above.

                      */

                      TUint32 iDirection;

                      };

        数据结构里的ID是不变的，每个通道唯一的。

        Index用来指定结构中各个属性的位置。例如，双击通道的数据的结构里iTimeStamp和iDirection分别是0和1。这在属性数组和条件数组里会用到。

        共用属性在sensrvgeneralproperties.h里声明，各通道独特属性在各自的头文件里声明。每种属性都有唯一的ID和描述，以及它们各自的数据成员，这些成员是TInt、TReal和TBuf类型。通道也可以定义属性的范围(scope)。

 

        如下例，定义中的Mandatory部分表示该属性是否是通道必须的属性，Capalibity部分表示所需的能力。

                /**

                  * - Name:         Accuracy of the channel data

                  * - Type:         TReal

                  * - Scope:        Channel item property

                  * - Mandatory:    No

                  * - Capability:   None

                  * - Description:  Returns the accuracy of this channel of the sensor as a

                  *                 percentage of reading (=data value).

                  */

                const TSensrvPropertyId KSensrvPropIdChannelAccuracy = 0x000000008;

 

        通道数据中可以设置一些列属性。如果是传感器或通道属性，item Index应为KSensrvItemIndexNone。

                  iPropertyId   = KSensrvPropIdChannelAccuracy

                  iItemIndex    = KSensrvItemIndexNone

                  iArrayIndex   = ESensrvSingleProperty

                  iRealValue    = 10.0

                  iReadOnly     = ETrue

                  iRealValueMax = n/a

                  iRealValueMin = n/a

                  iPropertyType = ESensrvRealProperty

                  iSecurityInfo = n/a

 

查找、打开、关闭通道

        使用CSensrvChannelFinder的实例来查找通道，查找返回RSensrvChannelInfoList结构的结果。例如，要查找双击通道，在TSensrvChannelInfo对象中把通道类型设置为 KSensrvChannelTypeIdAccelerometerDoubleTappingData，然后使用FindChannelsL()方法获得包含通道信息的结构channelInfoList，CSensrvChannel类使用这个结构就可以创建一个通道的实例。

                //Construct a channel finder.

                CSensrvChannelFinder* channelFinder;

                channelFinder = CSensrvChannelFinder::NewL();

                CleanupStack::PushL( channelFinder );

 

                //List of found channels.

                RSensrvChannelInfoList channelInfoList;

                CleanupClosePushL( channelInfoList );

                //Create and fill channel search criteria.

                //In this example double tapping channel is searched.

                TSensrvChannelInfo channelInfo;

                channelInfo.iChannelType = KSensrvChannelTypeIdAccelerometerDoubleTappingData;

                //Find the double tapping channel

                channelFinder->FindChannelsL( channelInfoList, channelInfo );

                if( channelInfoList.Count() != 1 )

                    {

                    //The device doesn't support double tapping channel or

                    //there are several double tapping channels.

                    }

                else

                    {

                    //double tapping channel found 

                    }

                //Open the double tapping channel.

                //When the channel object is created the channel info object 

                //must be an object returned by CSensrvChannelFinder::FindChannelsL().

                CSensrvChannel* sensorChannel;

                sensorChannel = CSensrvChannel::NewL( channelInfoList[ 0 ] );

                CleanupStack::PushL( sensorChannel ); 

                sensorChannel->OpenChannelL();

                //

                //Double tapping channel is now open.

                //

                //Close the double tapping channel.

                sensorChannel->CloseChannel();

                CleanupStack::PopAndDestroy( sensorChannel );

                CleanupStack::PopAndDestroy( &channelInfoList ); //Close() is being called on "channelInfoList"

                CleanupStack::PopAndDestroy( channelFinder );

 

侦听数据

        通道打开后，就可以侦听数据了。通道的数据保存在缓存中，可以通过GetData()方法获取。如果你要在新数据一到达时就接收，则要实现 MSensrvDataListener 接口的DataReceived()方法。

        例如，把双击通道的desired count 和 maximum count设置为1，则在每次双击发生时都会收到一个提醒。buffering period设置为0，表示消息不延时，立即通知。通道数据的缓存是客户端线程在堆上分配的，大小为其结构的大小乘以数据项的maximum number，可以通过GetData()访问。所以，如果决定缓存大小的maximum number太小，则会引发进程间通讯，从而影响效率。

        在这里，客户端实现了 MSensrvDataListener 接口，并把M类的指针赋给通道。

                iSensorChannel->StartDataListeningL( this, //this object is data listener for this channel

                        1, //aDesiredCount is one, i.e. each double tapping is notified separately

                        1, //aMaximumCount is one, i.e. object count in receiving data buffer is one

                        0 );//buffering period is not used

        侦听数据，需要实现 MSensrvDataListener 接口，需要重载它的 DataReceived() 方法。

                void CTestClass::DataReceived( CSensrvChannel& aChannel, 

                                           TInt aCount, 

                                           TInt aDataLost )

                {

                if ( aChannel.GetChannelInfo().iChannelType == KSensrvChannelTypeIdAccelerometerDoubleTappingData )

                    {

                    TSensrvTappingData tappingData;

                    TPckg<TSensrvTappingData> tappingPackage( tappingData );

                    aChannel.GetData( tappingPackage );

                    }

                }

        通道的 StopDataListening() 方法停止侦听。

 

侦听变化

获取通道属性

设置通道属性

属性数组

缩放通道数据

侦听通道属性的变化

条件侦听

        (暂略)

 

错误处理

        塞班系统的 leave 等错误机制依然有效。

 

内存开销

        传感器的内存开销基本集中在侦听数据的缓存。侦听频率和缓存大小如果不相匹配，则会引发进程间通讯，从而影响效率。

 

能力(capabilities)

        WriteDeviceData 修改channel属性时需要。

        ReadDeviceData 接收或读取channel数据时需要。

        (注：自签名和Express签名不能使用这两个能力，万恶啊)