传感器开发概述
基本概念
HarmonyOS传感器是应用访问底层硬件传感器的一种设备抽象概念。开发者根据传感器提供的Sensor API，可以查询设备上的传感器，订阅传感器的数据，并根据传感器数据定制相应的算法，开发各类应用，比如指南针、运动健康、游戏等。
根据传感器的用途，可以将传感器分为六大类：运动类传感器、环境类传感器、方向类传感器、光线类传感器、健康类传感器、其他类传感器（如霍尔传感器），每一大类传感器包含不同类型的传感器，某种类型的传感器可能是单一的物理传感器，也可能是由多个物理传感器复合而成。
表1 传感器列表
分类
API类名
传感器类型
中文描述
说明
主要用途
运动类
ohos.sensor.agent.CategoryMotionAgent
SENSOR_TYPE_ACCELEROMETER
加速度传感器
测量三个物理轴（x、y 和 z）上，施加在设备上的加速度（包括重力加速度），单位 : m/s2
检测运动状态
SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED
未校准加速度传感器
测量三个物理轴（x、y 和 z）上，施加在设备上的未校准的加速度（包括重力加速度），单位 : m/s2
检测加速度偏差估值
SENSOR_TYPE_LINEAR_ACCELERATION
线性加速度传感器
测量三个物理轴（x、y 和 z）上，施加在设备上的线性加速度（不包括重力加速度），单位 : m/s2
检测每个单轴方向上的线性加速度
SENSOR_TYPE_GRAVITY
重力传感器
测量三个物理轴（x、y 和 z）上，施加在设备上的重力加速度，单位 : m/s2
测量重力大小
SENSOR_TYPE_GYROSCOPE
陀螺仪传感器
测量三个物理轴（x、y 和 z）上，设备的旋转角速度，单位 : rad/s
测量旋转的角速度
SENSOR_TYPE_GYROSCOPE_UNCALIBRATED
未校准陀螺仪传感器
测量三个物理轴（x、y 和 z）上，设备的未校准旋转角速度，单位 : rad/s
测量旋转的角速度及偏差估值
SENSOR_TYPE_SIGNIFICANT_MOTION
大幅度动作传感器
测量三个物理轴（x、y 和 z）上，设备是否存在大幅度运动；如果取值为1则代表存在大幅度运动，取值为0则代表没有大幅度运动
用于检测设备是否存在大幅度运动
SENSOR_TYPE_DROP_DETECTION
跌落检测传感器
检测设备的跌落状态；如果取值为1则代表发生跌落，取值为0则代表没有发生跌落
用于检测设备是否发生了跌落
SENSOR_TYPE_PEDOMETER_DETECTION
计步器检测传感器
检测用户的计步动作；如果取值为1则代表用户产生了计步行走的动作；取值为0则代表用户没有发生运动
用于检测用户是否有计步的动作
SENSOR_TYPE_PEDOMETER
计步器传感器
统计用户的行走步数
用于提供用户行走的步数数据
环境类
ohos.sensor.agent.CategoryEnvironmentAgent
SENSOR_TYPE_AMBIENT_TEMPERATURE
环境温度传感器
测量环境温度，单位 : 摄氏度 (°C)
测量环境温度
SENSOR_TYPE_MAGNETIC_FIELD
磁场传感器
测量三个物理轴向（x、y、z）上，环境地磁场，单位 : μT
创建指南针
SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED
未校准磁场传感器
测量三个物理轴向（x、y、z）上，未校准环境地磁场，单位 : μT
测量地磁偏差估值
SENSOR_TYPE_HUMIDITY
湿度传感器
测量环境的相对湿度，以百分比 (%) 表示
监测露点、绝对湿度和相对湿度
SENSOR_TYPE_BAROMETER
气压计传感器
测量环境气压，单位 : hPa 或 mbar
测量环境气压
SENSOR_TYPE_SAR
比吸收率传感器
测量比吸收率，单位：W/kg
测量设备的电磁波能量吸收比值。
方向类
ohos.sensor.agent.CategoryOrientationAgent
SENSOR_TYPE_6DOF
6自由度传感器
测量上下、前后、左右方向上的位移，单位：m或mm；测量俯仰、偏摆、翻滚的角度，单位：rad
检测设备的三个平移自由度以及旋转自由度，用于目标定位追踪，如：VR
SENSOR_TYPE_SCREEN_ROTATION
屏幕旋转传感器
检测设备屏幕的旋转状态
用于检测设备屏幕是否发生了旋转
SENSOR_TYPE_DEVICE_ORIENTATION
设备方向传感器
测量设备的旋转方向，单位：rad
用于检测设备旋转方向的角度值
SENSOR_TYPE_ORIENTATION
方向传感器
测量设备围绕所有三个物理轴（x、y、z）旋转的角度值，单位：rad
用于提供屏幕旋转的3个角度值
SENSOR_TYPE_ROTATION_VECTOR
旋转矢量传感器
测量设备旋转矢量，复合传感器：由加速度传感器、磁场传感器、陀螺仪传感器合成
检测设备相对于东北天坐标系的方向
SENSOR_TYPE_GAME_ROTATION_VECTOR
游戏旋转矢量传感器
测量设备游戏旋转矢量，复合传感器：由加速度传感器、陀螺仪传感器合成
应用于游戏场景
SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR
地磁旋转矢量传感器
测量设备地磁旋转矢量，复合传感器：由加速度传感器、磁场传感器合成
用于测量地磁旋转矢量
光线类
ohos.sensor.agent.CategoryLightAgent
SENSOR_TYPE_PROXIMITY
接近光传感器
测量可见物体相对于设备显示屏的接近或远离状态
通话中设备相对人的位置
SENSOR_TYPE_TOF
ToF传感器
测量光在介质中行进一段距离所需的时间
识别人像
SENSOR_TYPE_AMBIENT_LIGHT
环境光传感器
测量设备周围光线强度，单位：lux
自动调节屏幕亮度，检测屏幕上方是否有遮挡
SENSOR_TYPE_COLOR_TEMPERATURE
色温传感器
测量环境中的色温
应用于设备的影像处理
SENSOR_TYPE_COLOR_RGB
RGB颜色传感器
测量环境中的RGB颜色值
通过三原色的反射比率实现颜色检测
SENSOR_TYPE_COLOR_XYZ
XYZ颜色传感器
测量环境中的XYZ颜色值
用于辨识真色色点，还原色彩更真实
健康类
ohos.sensor.agent.CategoryBodyAgent
SENSOR_TYPE_HEART_RATE
心率传感器
测量用户的心率数值
用于提供用户的心率健康数据
SENSOR_TYPE_WEAR_DETECTION
佩戴检测传感器
检测用户是否佩戴
用于检测用户是否佩戴智能穿戴
其他类
ohos.sensor.agent.CategoryOtherAgent
SENSOR_TYPE_HALL
霍尔传感器
测量设备周围是否存在磁力吸引
设备的皮套模式
SENSOR_TYPE_GRIP_DETECTOR
手握检测传感器
检测设备是否有抓力施加
用于检查设备侧边是否被手握住
SENSOR_TYPE_MAGNET_BRACKET
磁铁支架传感器
检测设备是否被磁吸
检测设备是否位于车内或者室内
SENSOR_TYPE_PRESSURE_DETECTOR
按压检测传感器
检测设备是否有压力施加
用于检测设备的正上方是否存在按压
运作机制
HarmonyOS传感器包含如下四个模块：Sensor API、Sensor Framework、Sensor Service、HD_IDL层。
图1 HarmonyOS传感器
'Sensor API：提供传感器的基础API，主要包含查询传感器的列表、订阅/取消传感器的数据、执行控制命令等，简化应用开发。
Sensor Framework：主要实现传感器的订阅管理，数据通道的创建、销毁、订阅与取消订阅，实现与SensorService的通信。
Sensor Service：主要实现HD_IDL层数据接收、解析、分发，前后台的策略管控，对该设备Sensor的管理，Sensor权限管控等。
HD_IDL层：对不同的FIFO、频率进行策略选择，以及对不同设备的适配。
约束与限制
针对某些传感器，开发者需要请求相应的权限，才能获取到相应传感器的数据。
表2 传感器权限列表
传感器数据订阅和取消订阅接口成对调用，当不再需要订阅传感器数据时，开发者需要调用取消订阅接口进行资源释放。
传感器开发
场景介绍
通过方向传感器数据，可以感知用户设备当前的朝向，从而达到为用户指明方位的目的。
通过重力和陀螺仪传感器数据，能感知设备倾斜和旋转量，提高用户在游戏场景中的体验。
通过接近光传感器数据，感知距离遮挡物的距离，使设备能够自动亮灭屏，达到防误触目的。
通过气压计传感器数据，可以准确的判断设备当前所处的海拔。
通过环境光传感器数据，设备能够实现背光自动调节。
通过霍尔传感器数据，设备可以实现皮套功能等。
接口说明
HarmonyOS传感器提供的功能有：查询传感器的列表、订阅/取消订阅传感器数据、查询传感器的最小采样时间间隔、执行控制命令。
以订阅方向类别的传感器数据为例，本节示例涉及的接口如下：
表1 CategoryOrientationAgent的主要接口
表2 SensorAgent的主要接口
表3 CategoryEnvironmentData的主要接口
表4 CategoryOrientationData的主要接口
开发步骤
权限配置
如果设备上使用了传感器权限列表中的传感器，需要请求相应的权限，开发者才能获取到传感器数据。
表5 不同敏感级别的传感器举例
开发者需要在config.json里面配置权限：
- 开发者如果需要获取加速度的数据，需要进行如下权限配置。
"reqPermissions": [ { "name": "ohos.permission.ACCELEROMETER", "reason": "", "usedScene": { "ability": [ ".MainAbility" ], "when": "inuse" } } ]
- 对于需要用户授权的权限，如计步器传感器，需要进行如下权限配置。
"reqPermissions": [ { "name": "ohos.permission.ACTIVITY_MOTION", "reason": "", "usedScene": { "ability": [ ".MainAbility" ], "when": "inuse" } } ]
由于敏感权限需要用户授权，因此，开发者在应用启动时或者调用订阅数据接口前，需要调用权限检查和请求权限接口。
@Override public void onStart(Intent intent) { super.onStart(intent); if (verifySelfPermission("ohos.permission.ACTIVITY_MOTION") != 0) { if (canRequestPermission("ohos.permission.ACTIVITY_MOTION")) { requestPermissionsFromUser(new String[] {"ohos.permission.ACTIVITY_MOTION"}, 1); } } // ... } @Override public void onRequestPermissionsFromUserResult(int requestCode, String[] permissions, int[] grantResults) { // 匹配requestPermissionsFromUser的requestCode if (requestCode == 1) { if (grantResults.length > 0 && grantResults[0] == 0) { // 权限被授予 } else { // 权限被拒绝 } } }
使用传感器
以使用方向类别的传感器为例，运动类、环境类、健康类等类别的传感器使用方法类似。
- 1.获取待订阅数据的传感器。
- 2.创建传感器回调。
- 3.订阅传感器数据。
- 4.接收并处理传感器数据。
- 5.取消订阅传感器数据。
private static final long INTERVAL = 100000000L; private Button btnSubscribe; private Button btnUnsubscribe; private CategoryOrientationAgent categoryOrientationAgent = new CategoryOrientationAgent(); private ICategoryOrientationDataCallback orientationDataCallback; private CategoryOrientation orientationSensor; private int matrix_length = 9; private int rotationVectorLength = 9; @Override public void onStart(Intent intent) { super.onStart(intent); super.setUIContent(ResourceTable.Layout_sensor_layout); findComponent(rootComponent); // 创建传感器回调对象。 orientationDataCallback = new ICategoryOrientationDataCallback() { @Override public void onSensorDataModified(CategoryOrientationData categoryOrientationData) { // 对接收的categoryOrientationData传感器数据对象解析和使用 int dim = categoryOrientationData.getSensorDataDim(); // 获取传感器的维度信息 float degree = categoryOrientationData.getValues()[0]; // 获取方向类传感器的第一维数据 float[] rotationMatrix = new float[matrix_length]; CategoryOrientationData.getDeviceRotationMatrix(rotationMatrix, categoryOrientationData.values); // 根据旋转矢量传感器的数据获得旋转矩阵 float[] rotationAngle = new float[rotationVectorLength]; rotationAngle = CategoryOrientationData.getDeviceOrientation(rotationMatrix, rotationAngle); // 根据计算出来的旋转矩阵获取设备的方向 } @Override public void onAccuracyDataModified(CategoryOrientation categoryOrientation, int index) { // 使用变化的精度 } @Override public void onCommandCompleted(CategoryOrientation categoryOrientation) { // 传感器执行命令回调 } }; btnSubscribe.setClickedListener(v -> { // 获取传感器对象，并订阅传感器数据 orientationSensor = categoryOrientationAgent.getSingleSensor( CategoryOrientation.SENSOR_TYPE_ORIENTATION); if (orientationSensor != null) { categoryOrientationAgent.setSensorDataCallback( orientationDataCallback, orientationSensor, INTERVAL); } }); // 取消订阅传感器数据 btnUnsubscribe.setClickedListener(v -> { if (orientationSensor != null) { categoryOrientationAgent.releaseSensorDataCallback( orientationDataCallback, orientationSensor); } }); } private void findComponent(Component component) { btnSubscribe = (Button) component.findComponentById(ResourceTable.Id_btnSubscribe); btnUnsubscribe = (Button) component.findComponentById(ResourceTable.Id_btnUnsubscribe); }
另外，CategoryEnvironmentData中地磁场算法相关接口的使用示例如下：
- 构造指定地点和时间的磁场
long timeMillis = new GregorianCalendar(2020, 1, 1).getTimeInMillis(); CategoryEnvironmentData.GeomagneticField geomagneticField = new CategoryEnvironmentData.GeomagneticField(80, 0, 0, timeMillis);
- 获取指定地点和时间的磁场数据
float geomagneticX = geomagneticField.obtainX(); float geomagneticY = geomagneticField.obtainY(); float geomagneticZ = geomagneticField.obtainZ(); float deflectionAngle = geomagneticField.obtainDeflectionAngle(); float geomagneticDip = geomagneticField.obtainGeomagneticDip(); float levelIntensity = geomagneticField.obtainLevelIntensity(); float totalIntensity = geomagneticField.obtainTotalIntensity();
