@system.sensor (Sensor)
The Sensor module provides APIs for querying the sensor list, subscribing to or unsubscribing from sensor data, and executing control commands.
The sensors are classified into the following categories based on their functions: motion, environment, orientation, light, body, and other categories (such as Hall effect sensors). Each category includes different sensor types. A sensor type may be a single hardware sensor or a composite of multiple hardware sensors.
NOTE
- The APIs of this module are no longer maintained since API version 8. You are advised to use
@ohos.sensorinstead.- The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
- This module requires hardware support and can only be debugged on real devices.
Modules to Import
import sensor from '@system.sensor';
sensor.subscribeAccelerometer
subscribeAccelerometer(options: subscribeAccelerometerOptions): void
Subscribes to data changes of the acceleration sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.ACCELEROMETER (a system permission)
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | subscribeAccelerometerOptions | Yes | Type of data to return. |
Example
sensor.subscribeAccelerometer({
interval: 'normal',
success: function(ret) {
console.log('X-axis data: ' + ret.x);
console.log('Y-axis data: ' + ret.y);
console.log('Z-axis data: ' + ret.z);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeAccelerometer
unsubscribeAccelerometer(): void
Unsubscribes from data changes of the acceleration sensor.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.ACCELEROMETER (a system permission)
Example
sensor.unsubscribeAccelerometer();
sensor.subscribeCompass
subscribeCompass(options: SubscribeCompassOptions): void
Subscribes to data changes of the compass sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeCompassOptions | Yes | Type of data to return. |
Example
sensor.subscribeCompass({
success: function(ret) {
console.log('get data direction:' + ret.direction);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeCompass
unsubscribeCompass(): void
Unsubscribes from data changes of the compass sensor.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeCompass();
sensor.subscribeProximity
subscribeProximity(options: SubscribeProximityOptions): void
Subscribes to data changes of the proximity sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeProximityOptions | Yes | Type of data to return. |
Example
sensor.subscribeProximity({
success: function(ret) {
console.log('get data distance:' + ret.distance);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeProximity
unsubscribeProximity(): void
Unsubscribes from data changes of the proximity sensor.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeProximity();
sensor.subscribeLight
subscribeLight(options: SubscribeLightOptions): void
Subscribes to data changes of the ambient light sensor. If this API is called multiple times, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeLightOptions | Yes | Type of data to return. |
Example
sensor.subscribeLight({
success: function(ret) {
console.log('get data intensity:' + ret.intensity);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeLight
unsubscribeLight(): void
Unsubscribes from data changes of the ambient light sensor.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeLight();
sensor.subscribeStepCounter
subscribeStepCounter(options: SubscribeStepCounterOptions): void
Subscribes to data changes of the step counter sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.ACTIVITY_MOTION
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeStepCounterOptions | Yes | Type of data to return. |
Example
sensor.subscribeStepCounter({
success: function(ret) {
console.log('get step value:' + ret.steps);
},
fail: function(data, code) {
console.log('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeStepCounter
unsubscribeStepCounter(): void
Unsubscribes from data changes of the step counter sensor.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.ACTIVITY_MOTION
Example
sensor.unsubscribeStepCounter();
sensor.subscribeBarometer
subscribeBarometer(options: SubscribeBarometerOptions): void
Subscribes to data changes of the barometer sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeBarometerOptions | Yes | Type of data to return. |
Example
sensor.subscribeBarometer({
success: function(ret) {
console.log('get data value:' + ret.pressure);
},
fail: function(data, code) {
console.log('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeBarometer
unsubscribeBarometer(): void
Unsubscribes from data changes of the barometer sensor.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeBarometer();
sensor.subscribeHeartRate
subscribeHeartRate(options: SubscribeHeartRateOptions): void
Subscribes to data changes of the heart rate sensor. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.READ_HEALTH_DATA
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeHeartRateOptions | Yes | Type of data to return. |
Example
sensor.subscribeHeartRate({
success: function(ret) {
console.log('get heartrate value:' + ret.heartRate);
},
fail: function(data, code) {
console.log('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeHeartRate
unsubscribeHeartRate(): void
Unsubscribes from data changes of the heart rate sensor.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.READ_HEALTH_DATA
Example
sensor.unsubscribeHeartRate();
sensor.subscribeOnBodyState
subscribeOnBodyState(options: SubscribeOnBodyStateOptions): void
Subscribes to changes of the wearing state of a wearable device. If this API is called multiple times for the same application, the last call takes effect.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeOnBodyStateOptions | Yes | Type of data to return. |
Example
sensor.subscribeOnBodyState({
success: function(ret) {
console.log('get on-body state value:' + ret.value);
},
fail: function(data, code) {
console.log('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeOnBodyState
unsubscribeOnBodyState(): void
Unsubscribes from changes of the wearing state of a wearable device.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeOnBodyState();
sensor.getOnBodyState
getOnBodyState(options: GetOnBodyStateOptions): void
Obtains the wearing state of a wearable device.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | GetOnBodyStateOptions | Yes | Type of data to return. |
Example
sensor.getOnBodyState({
success: function(ret) {
console.log('on body state: ' + ret.value);
},
fail: function(data, code) {
console.log('Subscription failed. Code: ' + code + '; Data: ' + data);
},
});
sensor.subscribeDeviceOrientation6+
subscribeDeviceOrientation(options: SubscribeDeviceOrientationOptions): void
Subscribes to data changes of the device orientation sensor.
If this API is called multiple times for the same application, the last call takes effect. However, this API cannot be called multiple times in one click event.
System capability: SystemCapability.Sensors.Sensor
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeDeviceOrientationOptions | Yes | Type of data to return. |
Example
sensor.subscribeDeviceOrientation({
interval: 'normal',
success: function(ret) {
console.log('Alpha data: ' + ret.alpha);
console.log('Beta data: ' + ret.beta);
console.log('Gamma data: ' + ret.gamma);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; Data: ' + data);
}
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeDeviceOrientation6+
unsubscribeDeviceOrientation(): void
Unsubscribes from data changes of the device orientation sensor.
System capability: SystemCapability.Sensors.Sensor
Example
sensor.unsubscribeDeviceOrientation();
sensor.subscribeGyroscope6+
subscribeGyroscope(options: SubscribeGyroscopeOptions): void
Subscribes to data changes of the gyroscope sensor.
If this API is called multiple times for the same application, the last call takes effect. However, this API cannot be called multiple times in one click event.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.GYROSCOPE (a system permission)
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SubscribeGyroscopeOptions | Yes | Type of data to return. |
Example
sensor.subscribeGyroscope({
interval: 'normal',
success: function(ret) {
console.log('X-axis data: ' + ret.x);
console.log('Y-axis data: ' + ret.y);
console.log('Z-axis data: ' + ret.z);
},
fail: function(data, code) {
console.error('Subscription failed. Code: ' + code + '; data: ' + data);
}
});
NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestory callback.
sensor.unsubscribeGyroscope6+
unsubscribeGyroscope(): void
Unsubscribes from data changes of the gyroscope sensor.
System capability: SystemCapability.Sensors.Sensor
Required permissions: ohos.permission.GYROSCOPE (a system permission)
Example
sensor.unsubscribeGyroscope();
subscribeAccelerometerOptions
Defines the type of data to return for a subscription to the acceleration sensor data.
Required permissions: ohos.permission.ACCELEROMETER
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| interval | string | Yes | Execution frequency of the callback for returning the acceleration sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios. |
| success | AccelerometerResponse | Yes | Called when the acceleration sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
AccelerometerResponse
Defines the type of data to include in an AccelerometerResponse object.
Required permissions: ohos.permission.ACCELEROMETER
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| x | number | Yes | Acceleration on the x-axis. |
| y | number | Yes | Acceleration on the y-axis. |
| z | number | Yes | Acceleration on the z-axis. |
SubscribeCompassOptions
Defines the type of data to return for a subscription to the compass sensor data.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | CompassResponse | Yes | Called when the compass sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
CompassResponse
Defines the type of data to include in a CompassResponse object.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| direction | number | Yes | Direction of the device, in degrees. |
SubscribeProximityOptions
Defines the type of data to return for a subscription to the proximity sensor data.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | ProximityResponse | Yes | Called when the proximity sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
ProximityResponse
Defines the type of data to include in a ProximityResponse object.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| distance | number | Yes | Distance between a visible object and the device screen. |
SubscribeLightOptions
Defines the type of data to return for a subscription to the ambient light sensor data.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | LightResponse | Yes | Called when the ambient light sensor data changes |
| fail | Function | No | Callback upon an API call failure. |
LightResponse
Defines the type of data to include in a LightResponse object.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| intensity | number | Yes | Light intensity, in lux. |
SubscribeStepCounterOptions
Defines the type of data to return for a subscription to the step counter sensor data.
Required permissions: ohos.permission.ACTIVITY_MOTION
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | StepCounterResponse | Yes | Called when the step counter sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
StepCounterResponse
Defines the type of data to include in a StepCounterResponse object.
Required permissions: ohos.permission.ACTIVITY_MOTION
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| steps | number | Yes | Number of counted steps after the sensor is restarted. |
SubscribeBarometerOptions
Defines the type of data to return for a subscription to the barometer sensor data.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | BarometerResponse | Yes | Called when the barometer sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
BarometerResponse
Defines the type of data to include in a BarometerResponse object.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| pressure | number | Yes | Pressure, in pascal. |
SubscribeHeartRateOptions
Defines the type of data to return for a subscription to the heart rate sensor data.
Required permissions: ohos.permission.READ_HEALTH_DATA
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | HeartRateResponse | Yes | Called when the heart rate sensor data changes. This callback is invoked every five seconds. |
| fail | Function | No | Callback upon an API call failure. |
HeartRateResponse
Defines the type of data to include in a HeartRateResponse object.
Required permissions: ohos.permission.READ_HEALTH_DATA
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| heartRate | number | Yes | Heart rate. |
SubscribeOnBodyStateOptions
Defines the type of data to return for a subscription to the wearing state changes.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | OnBodyStateResponse | Yes | Called when the wearing state changes. |
| fail | Function | No | Callback upon an API call failure. |
OnBodyStateResponse
Defines the wearing state.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | boolean | Yes | Whether the wearable device is worn. |
GetOnBodyStateOptions
Defines the type of data to return for obtaining the wearing state.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | OnBodyStateResponse | No | Callback upon a successful API call. |
| fail | Function | No | Callback upon an API call failure. |
| complete | Function | No | Called when the API call is complete. |
SubscribeDeviceOrientationOptions6+
Defines the type of data to return for a subscription to the device orientation sensor data.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| interval | string | Yes | Interval at which the callback is invoked to return the device orientation sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios. |
| success | DeviceOrientationResponse | Yes | Called when the device orientation sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
DeviceOrientationResponse6+
Defines the type of data to include in a DeviceOrientationResponse object.
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| alpha | number | Yes | Rotation angle around the Z axis when the X/Y axis of the device coincides with the X/Y axis of the earth. |
| beta | number | Yes | Rotation angle around the X axis when the Y/Z axis of the device coincides with the Y/Z axis of the earth. |
| gamma | number | Yes | Rotation angle around the Y axis when the X/Z axis of the device coincides with the X/Z axis of the earth. |
SubscribeGyroscopeOptions6+
Defines the type of data to return for a subscription to the gyroscope sensor data.
Required permissions: ohos.permission.GYROSCOPE
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| interval | string | Yes | Interval at which the callback is invoked to return the gyroscope sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios. |
| success | GyroscopeResponse | Yes | Called when the gyroscope sensor data changes. |
| fail | Function | No | Callback upon an API call failure. |
GyroscopeResponse6+
Defines the type of data to include in a GyroscopeResponse object.
Required permissions: ohos.permission.GYROSCOPE
System capability: SystemCapability.Sensors.Sensor
| Name | Type | Mandatory | Description |
|---|---|---|---|
| x | number | Yes | Rotation angular velocity of the X axis. |
| y | number | Yes | Rotation angular velocity of the Y axis. |
| z | number | Yes | Rotation angular velocity of the Z axis. |