1# Sensor 2 3 4>  **NOTE** 5> - The initial APIs of this module are supported since API version 4. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6> - The APIs of this module are no longer maintained since API version 8. You are advised to use [Sensor](js-apis-sensor.md) instead. 7> - This module requires hardware support and can only be debugged on real devices. 8 9 10## Modules to Import 11 12 13``` 14import sensor from '@system.sensor'; 15``` 16 17 18## Error Codes 19 20| Error Code | Description | 21| ---------- | ---------------------------------------- | 22| 900 | The current device does not support the corresponding sensor. | 23 24## sensor.subscribeAccelerometer 25 26subscribeAccelerometer(Object): void 27 28Subscribes to data changes of the acceleration sensor. If this API is called multiple times for the same application, the last call takes effect. 29 30**System capability**: SystemCapability.Sensors.Sensor 31 32**Required permissions**: ohos.permission.ACCELEROMETER (a system permission) 33 34**Parameters** 35 36| Name | Type | Mandatory | Description | 37| -------- | -------- | --------- | ---------------------------------------- | 38| interval | string | Yes | Execution frequency of the callback for returning the acceleration sensor data.<br>The default value is **normal**. The options are as follows:<br>- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.<br>- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.<br>- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios. | 39| success | Function | Yes | Called when the acceleration sensor data changes. | 40| fail | Function | No | Callback upon failure. | 41 42Return values of the success callback 43 44| Name | Type | Description | 45| ---- | ------ | --------------------------- | 46| x | number | Acceleration on the x-axis. | 47| y | number | Acceleration on the y-axis. | 48| z | number | Acceleration on the z-axis. | 49 50**Example** 51 52``` 53sensor.subscribeAccelerometer({ 54 interval: 'normal', 55 success: function(ret) { 56 console.log('X-axis data: ' + ret.x); 57 console.log('Y-axis data: ' + ret.y); 58 console.log('Z-axis data: ' + ret.z); 59 }, 60 fail: function(data, code) { 61 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 62 }, 63}); 64``` 65 66>  **NOTE** 67> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 68 69## sensor.unsubscribeAccelerometer 70 71unsubscribeAccelerometer(): void 72 73Unsubscribes from data changes of the acceleration sensor. 74 75**System capability**: SystemCapability.Sensors.Sensor 76 77**Required permissions**: ohos.permission.ACCELEROMETER (a system permission) 78 79**Example** 80 81``` 82sensor.unsubscribeAccelerometer(); 83``` 84 85## sensor.subscribeCompass 86 87subscribeCompass(Object): void 88 89Subscribes to data changes of the compass sensor. If this API is called multiple times for the same application, the last call takes effect. 90 91**System capability**: SystemCapability.Sensors.Sensor 92 93**Parameters** 94 95| Name | Type | Mandatory | Description | 96| ------- | -------- | --------- | ---------------------------------------- | 97| success | Function | Yes | Called when the compass sensor data changes. | 98| fail | Function | No | Callback upon failure. | 99 100Return values of the success callback 101 102| Name | Type | Description | 103| --------- | ------ | ------------------------------------ | 104| direction | number | Direction of the device, in degrees. | 105 106**Example** 107 108``` 109sensor.subscribeCompass({ 110 success: function(ret) { 111 console.log('get data direction:' + ret.direction); 112 }, 113 fail: function(data, code) { 114 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 115 }, 116}); 117``` 118 119>  **NOTE** 120> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 121 122## sensor.unsubscribeCompass 123 124unsubscribeCompass(): void 125 126Unsubscribes from data changes of the compass sensor. 127 128**System capability**: SystemCapability.Sensors.Sensor 129 130**Example** 131 132``` 133sensor.unsubscribeCompass(); 134``` 135 136## sensor.subscribeProximity 137 138subscribeProximity(Object): void 139 140Subscribes to data changes of the proximity sensor. If this API is called multiple times for the same application, the last call takes effect. 141 142**System capability**: SystemCapability.Sensors.Sensor 143 144**Parameters** 145 146| Name | Type | Mandatory | Description | 147| ------- | -------- | --------- | ---------------------------------------- | 148| success | Function | Yes | Called when the proximity sensor data changes. | 149| fail | Function | No | Callback upon failure. | 150 151Return values of the success callback 152 153| Name | Type | Description | 154| -------- | ------ | ---------------------------------------- | 155| distance | number | Distance between a visible object and the device screen. | 156 157**Example** 158 159``` 160sensor.subscribeProximity({ 161 success: function(ret) { 162 console.log('get data distance:' + ret.distance); 163 }, 164 fail: function(data, code) { 165 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 166 }, 167}); 168``` 169 170>  **NOTE** 171> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 172 173## sensor.unsubscribeProximity 174 175unsubscribeProximity(): void 176 177Unsubscribes from data changes of the proximity sensor. 178 179**System capability**: SystemCapability.Sensors.Sensor 180 181**Example** 182 183``` 184sensor.unsubscribeProximity(); 185``` 186 187## sensor.subscribeLight 188 189sensor.subscribeLight(Object): void 190 191Subscribes to data changes of the ambient light sensor. If this API is called multiple times, the last call takes effect. 192 193**System capability**: SystemCapability.Sensors.Sensor 194 195**Parameters** 196 197| Name | Type | Mandatory | Description | 198| ------- | -------- | --------- | ---------------------------------------- | 199| success | Function | Yes | Called when the ambient light sensor data changes | 200| fail | Function | No | Callback upon failure. | 201 202Return values of the success callback 203 204| Name | Type | Description | 205| --------- | ------ | ------------------------ | 206| intensity | number | Light intensity, in lux. | 207 208**Example** 209 210``` 211sensor.subscribeLight({ 212 success: function(ret) { 213 console.log('get data intensity:' + ret.intensity); 214 }, 215 fail: function(data, code) { 216 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 217 }, 218}); 219``` 220 221>  **NOTE** 222> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 223 224## sensor.unsubscribeLight 225 226unsubscribeLight(): void 227 228Unsubscribes from data changes of the ambient light sensor. 229 230**System capability**: SystemCapability.Sensors.Sensor 231 232**Example** 233 234``` 235sensor.unsubscribeLight(); 236``` 237 238## sensor.subscribeStepCounter 239 240subscribeStepCounter(Object): void 241 242Subscribes to data changes of the step counter sensor. If this API is called multiple times for the same application, the last call takes effect. 243 244**System capability**: SystemCapability.Sensors.Sensor 245 246**Required permissions**: ohos.permission.ACTIVITY_MOTION 247 248**Parameters** 249 250| Name | Type | Mandatory | Description | 251| ------- | -------- | --------- | ---------------------------------------- | 252| success | Function | Yes | Called when the step counter sensor data changes. | 253| fail | Function | No | Callback upon failure. | 254 255Return values of the success callback 256 257| Name | Type | Description | 258| ----- | ------ | ---------------------------------------- | 259| steps | number | Number of counted steps after the sensor is restarted.<br> | 260 261**Example** 262 263``` 264sensor.subscribeStepCounter({ 265 success: function(ret) { 266 console.log('get step value:' + ret.steps); 267 }, 268 fail: function(data, code) { 269 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 270 }, 271}); 272``` 273 274>  **NOTE** 275> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 276 277## sensor.unsubscribeStepCounter 278 279unsubscribeStepCounter(): void 280 281Unsubscribes from data changes of the step counter sensor. 282 283**System capability**: SystemCapability.Sensors.Sensor 284 285**Required permissions**: ohos.permission.ACTIVITY_MOTION 286 287**Example** 288 289``` 290sensor.unsubscribeStepCounter(); 291``` 292 293 294## sensor.subscribeBarometer 295 296subcribeBarometer(Object): void 297 298Subscribes to data changes of the barometer sensor. If this API is called multiple times for the same application, the last call takes effect. 299 300**System capability**: SystemCapability.Sensors.Sensor 301 302**Parameters** 303 304| Name | Type | Mandatory | Description | 305| ------- | -------- | --------- | ---------------------------------------- | 306| success | Function | Yes | Called when the barometer sensor data changes. | 307| fail | Function | No | Callback upon failure. | 308 309Return values of the success callback 310 311| Name | Type | Description | 312| -------- | ------ | -------------------- | 313| pressure | number | Pressure, in pascal. | 314 315**Example** 316 317``` 318sensor.subscribeBarometer({ 319 success: function(ret) { 320 console.log('get data value:' + ret.pressure); 321 }, 322 fail: function(data, code) { 323 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 324 }, 325}); 326``` 327 328>  **NOTE** 329> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 330 331 332## sensor.unsubscribeBarometer 333 334unsubscribeBarometer(): void 335 336Unsubscribes from data changes of the barometer sensor. 337 338**System capability**: SystemCapability.Sensors.Sensor 339 340**Example** 341 342``` 343sensor.unsubscribeBarometer(); 344``` 345 346 347## sensor.subscribeHeartRate 348 349subscribeHeartRate(Object): void 350 351Subscribes to data changes of the heart rate sensor. If this API is called multiple times for the same application, the last call takes effect. 352 353**System capability**: SystemCapability.Sensors.Sensor 354 355**Required permissions**: ohos.permission.READ_HEALTH_DATA 356 357**Parameters** 358 359| Name | Type | Mandatory | Description | 360| ------- | -------- | --------- | ---------------------------------------- | 361| success | Function | Yes | Called when the heart rate sensor data changes. This callback is invoked every five seconds. | 362| fail | Function | No | Callback upon failure. | 363 364Return values of the success callback 365 366| Name | Type | Description | 367| --------- | ------ | ----------- | 368| heartRate | number | Heart rate. | 369 370**Example** 371 372``` 373sensor.subscribeHeartRate({ 374 success: function(ret) { 375 console.log('get heartrate value:' + ret.heartRate); 376 }, 377 fail: function(data, code) { 378 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 379 }, 380}); 381``` 382 383>  **NOTE** 384> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 385 386 387## sensor.unsubscribeHeartRate 388 389unsubscribeHeartRate(): void 390 391Unsubscribes from data changes of the heart rate sensor. 392 393**System capability**: SystemCapability.Sensors.Sensor 394 395**Required permissions**: ohos.permission.READ_HEALTH_DATA 396 397**Example** 398 399``` 400sensor.unsubscribeHeartRate(); 401``` 402 403## sensor.subscribeOnBodyState 404 405subscribeOnBodyState(Object): void 406 407Subscribes 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. 408 409**System capability**: SystemCapability.Sensors.Sensor 410 411**Parameters** 412 413| Name | Type | Mandatory | Description | 414| ------- | -------- | --------- | -------------------------------------- | 415| success | Function | Yes | Called when the wearing state changes. | 416| fail | Function | No | Callback upon failure. | 417 418Return values of the success callback 419 420| Name | Type | Description | 421| ----- | ------- | ------------------------------------ | 422| value | boolean | Whether the wearable device is worn. | 423 424**Example** 425 426``` 427sensor.subscribeOnBodyState({ 428 success: function(ret) { 429 console.log('get on-body state value:' + ret.value); 430 }, 431 fail: function(data, code) { 432 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 433 }, 434}); 435``` 436 437>  **NOTE** 438> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 439 440## sensor.unsubscribeOnBodyState 441 442unsubscribeOnBodyState(): void 443 444Unsubscribes from changes of the wearing state of a wearable device. 445 446**System capability**: SystemCapability.Sensors.Sensor 447 448**Example** 449 450``` 451sensor.unsubscribeOnBodyState(); 452``` 453 454## sensor.getOnBodyState 455 456getOnBodyState(Object): void 457 458Obtains the wearing state of a wearable device. 459 460**System capability**: SystemCapability.Sensors.Sensor 461 462**Parameters** 463 464| Name | Type | Mandatory | Description | 465| -------- | -------- | --------- | -------------------------------------- | 466| success | Function | No | Callback upon success. | 467| fail | Function | No | Callback upon failure. | 468| complete | Function | No | Called when the execution is complete. | 469 470Return values of the success callback 471 472| Name | Type | Description | 473| ----- | ------- | ------------------------------------ | 474| value | boolean | Whether the wearable device is worn. | 475 476**Example** 477 478``` 479sensor.getOnBodyState({ 480 success: function(ret) { 481 console.log('on body state: ' + ret.value); 482 }, 483 fail: function(data, code) { 484 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 485 }, 486}); 487``` 488 489## sensor.subscribeDeviceOrientation<sup>6+</sup> 490 491subscribeDeviceOrientation(interval: string, success: (data: DeviceOrientationResponse), fail?: (data: string, code: number)): void 492 493Subscribes to data changes of the device orientation sensor. 494 495If 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. 496 497**System capability**: SystemCapability.Sensors.Sensor 498 499**Parameters** 500 501| Name | Type | Mandatory | Description | 502| -------- | -------- | --------- | ---------------------------------------- | 503| interval | string | Yes | Interval at which the callback is invoked to return the device orientation sensor data.<br>The default value is **normal**. The options are as follows:<br>- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.<br>- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.<br>- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios. | 504| success | Function | Yes | Called when the device orientation sensor data changes. | 505| fail | Function | No | Callback upon failure. | 506 507 Return values of the success callback 508| Name | Type | Description | 509| ----- | ------ | ---------------------------------------- | 510| alpha | number | Rotation angle around the Z axis when the X/Y axis of the mobile device coincides with the X/Y axis of the earth. | 511| beta | number | Rotation angle around the X axis when the Y/Z axis of the mobile device coincides with the Y/Z axis of the earth. | 512| gamma | number | Rotation angle around the Y axis when the X/Z axis of the mobile device coincides with the X/Z axis of the earth. | 513 514**Example** 515 516``` 517sensor.subscribeDeviceOrientation({ 518 interval: 'normal', 519 success: function(ret) { 520 console.log('Alpha data: ' + ret.alpha); 521 console.log('Beta data: ' + ret.beta); 522 console.log('Gamma data: ' + ret.gamma); 523 }, 524 fail: function(data, code) { 525 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 526 } 527}); 528``` 529 530>  **NOTE** 531> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 532 533## sensor.unsubscribeDeviceOrientation<sup>6+</sup> 534 535unsubscribeDeviceOrientation(): void 536 537Unsubscribes from data changes of the device orientation sensor. 538 539**System capability**: SystemCapability.Sensors.Sensor 540 541**Example** 542 543``` 544sensor.unsubscribeDeviceOrientation(); 545``` 546 547## sensor.subscribeGyroscope<sup>6+</sup> 548 549subscribeGyroscope(interval: string, success: (data: GyroscopeResponse), fail?: (data: string, code: number)): void 550 551Subscribes to data changes of the gyroscope sensor. 552 553If 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. 554 555**System capability**: SystemCapability.Sensors.Sensor 556 557**Required permissions**: ohos.permission.GYROSCOPE (a system permission) 558 559**Parameters** 560 561| Name | Type | Mandatory | Description | 562| -------- | -------- | --------- | ---------------------------------------- | 563| interval | string | Yes | Interval at which the callback is invoked to return the gyroscope sensor data.<br>The default value is **normal**. The options are as follows:<br>- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.<br>- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.<br>- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios. | 564| success | Function | Yes | Called when the gyroscope sensor data changes. | 565| fail | Function | No | Callback upon failure. | 566 567Return values of the success callback 568 569| Name | Type | Description | 570| ---- | ------ | ---------------------------------------- | 571| x | number | Rotation angular velocity of the X axis. | 572| y | number | Rotation angular velocity of the Y axis. | 573| z | number | Rotation angular velocity of the Z axis. | 574 575**Example** 576 577``` 578sensor.subscribeGyroscope({ 579 interval: 'normal', 580 success: function(ret) { 581 console.log('X-axis data: ' + ret.x); 582 console.log('Y-axis data: ' + ret.y); 583 console.log('Z-axis data: ' + ret.z); 584 }, 585 fail: function(data, code) { 586 console.error('Subscription failed. Code: ' + code + '; data: ' + data); 587 } 588}); 589``` 590 591>  **NOTE** 592> To reduce performance overhead, you are advised to unsubscribe from the sensor data in the **onDestory** callback. 593 594## sensor.unsubscribeGyroscope<sup>6+</sup> 595 596unsubscribeGyroscope(): void 597 598Unsubscribes from data changes of the gyroscope sensor. 599 600**System capability**: SystemCapability.Sensors.Sensor 601 602**Required permissions**: ohos.permission.GYROSCOPE (a system permission) 603 604**Example** 605 606``` 607sensor.unsubscribeGyroscope(); 608``` 609
