diff --git a/en/application-dev/device/sensor-guidelines.md b/en/application-dev/device/sensor-guidelines.md index dcfffc55a6400f21c9180ee3306af16ae8713119..50ebd3428f89eba4f968dd98e5fe2edee91bee34 100644 --- a/en/application-dev/device/sensor-guidelines.md +++ b/en/application-dev/device/sensor-guidelines.md @@ -26,58 +26,30 @@ | -------- | -------- | -------- | | ohos.sensor | sensor.on(sensorType, callback:AsyncCallback<Response>): void | Subscribes to data changes of a type of sensor.| | ohos.sensor | sensor.once(sensorType, callback:AsyncCallback<Response>): void | Subscribes to only one data change of a type of sensor.| -| ohos.sensor | sensor.off(sensorType, callback:AsyncCallback<void>): void | Unsubscribes from sensor data changes.| +| ohos.sensor | sensor.off(sensorType, callback?:AsyncCallback<void>): void | Unsubscribes from sensor data changes.| ## How to Develop -1. To obtain data from a type of sensor, configure the requested permissions in the **config.json** file. - - ``` - "reqPermissions":[ - { - "name":"ohos.permission.ACCELEROMETER", - "reason":"", - "usedScene":{ - "ability": ["sensor.index.MainAbility",".MainAbility"], - "when":"inuse" - } - }, - { - "name":"ohos.permission.GYROSCOPE", - "reason":"", - "usedScene":{ - "ability": ["sensor.index.MainAbility",".MainAbility"], - "when":"inuse" - } - }, - { - "name":"ohos.permission.ACTIVITY_MOTION", - "reason":"ACTIVITY_MOTION_TEST", - "usedScene":{ - "ability": ["sensor.index.MainAbility",".MainAbility"], - "when":"inuse" - } - }, - { - "name":"ohos.permission.READ_HEALTH_DATA", - "reason":"HEALTH_DATA_TEST", - "usedScene":{ - "ability": ["sensor.index.MainAbility",".MainAbility"], - "when":"inuse" - } - }, - ] - ``` +1. Before obtaining data from a type of sensor, check whether the required permission has been configured.
+ The system provides the following sensor-related permissions: + - ohos.permission.ACCELEROMETER + + - ohos.permission.GYROSCOPE + + - ohos.permission.ACTIVITY_MOTION + + - ohos.permission.READ_HEALTH_DATA + + For details about how to configure a permission, see [Declaring Permissions](../security/accesstoken-guidelines.md). 2. Subscribe to data changes of a type of sensor. ``` - import sensor from "@ohos.sensor" - sensor.on(sensor.sensorType.SENSOR_TYPE_ACCELEROMETER,function(data){ - console.info("Subscription succeeded. data = "+ data); // The call is successful, and the obtained sensor data is printed. - } - ); + import sensor from "@ohos.sensor"; + sensor.on(sensor.SensorType.SENSOR_TYPE_ID_ACCELEROMETER, function(data){ + console.info("Data obtained successfully. x: " + data.x + "y: " + data.y + "z: " + data.z); // Data is obtained. + }); ``` The following figure shows the successful call result when **SensorType** is **SENSOR_TYPE_ID_ACCELEROMETER**. @@ -87,11 +59,8 @@ 3. Unsubscribe from sensor data changes. ``` - import sensor from "@ohos.sensor" - sensor.off(sensor.sensorType.SENSOR_TYPE_ACCELEROMETER,function() { - console.info("Succeeded in unsubscribing from acceleration sensor data."); // The unsubscription is successful, and the result is printed. - } - ); + import sensor from "@ohos.sensor"; + sensor.off(sensor.SensorType.SENSOR_TYPE_ID_ACCELEROMETER); ``` The following figure shows the successful call result when **SensorType** is **SENSOR_TYPE_ID_ACCELEROMETER**. @@ -101,11 +70,10 @@ 4. Subscribe to only one data change of a type of sensor. ``` - import sensor from "@ohos.sensor" - sensor.once(sensor.sensorType.SENSOR_TYPE_ACCELEROMETER,function(data) { - console.info("Data obtained successfully. data=" + data); // The call is successful, and the obtained sensor data is printed. - } - ); + import sensor from "@ohos.sensor"; + sensor.once(sensor.SensorType.SENSOR_TYPE_ID_ACCELEROMETER, function(data) { + console.info("Data obtained successfully. x: " + data.x + "y: " + data.y + "z: " + data.z); // Data is obtained. + }); ``` The following figure shows the successful call result when **SensorType** is **SENSOR_TYPE_ID_ACCELEROMETER**. @@ -115,11 +83,12 @@ If the API fails to be called, you are advised to use the **try/catch** statement to capture error information that may occur in the code. Example: ``` + import sensor from "@ohos.sensor"; try { - sensor.once(sensor.sensorType.SENSOR_TYPE_ACCELEROMETER,function(data) { - console.info("Data obtained successfully. data=" + data); // The call is successful, and the obtained sensor data is printed. + sensor.once(sensor.SensorType.SENSOR_TYPE_ID_ACCELEROMETER, function(data) { + console.info("Data obtained successfully. x: " + data.x + "y: " + data.y + "z: " + data.z); // Data is obtained. }); } catch (error) { - console.error(error); + console.error("Failed to get sensor data"); } - ``` + ``` \ No newline at end of file diff --git a/en/application-dev/device/sensor-overview.md b/en/application-dev/device/sensor-overview.md index 671cc29ade0a832dc835ab4c03529ef9c9771280..adfa2440c20108a5efe6753e9dc1be8fb350ebcf 100644 --- a/en/application-dev/device/sensor-overview.md +++ b/en/application-dev/device/sensor-overview.md @@ -6,29 +6,29 @@ Sensors in OpenHarmony are an abstraction of underlying sensor hardware. Your ap A sensor is a device to detect events or changes in an environment and send messages about the events or changes to another device (for example, a CPU). Generally, a sensor is composed of sensitive components and conversion components. Sensors are the cornerstone of the IoT. A unified sensor management framework is required to achieve data sensing at a low latency and low power consumption, thereby keeping up with requirements of "1+8+N" products or business in the Seamless AI Life Strategy. The sensor list is as follows: -| Type | Name | Description | Usage | -| --------------------------------------- | ------------------ | ------------------------------------------------------------ | ---------------------------------------- | -| SENSOR_TYPE_ACCELEROMETER | Acceleration sensor | Measures the acceleration (including the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Detecting the motion status | -| SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED | Uncalibrated acceleration sensor| Measures the uncalibrated acceleration (including the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Measuring the acceleration bias estimation | -| SENSOR_TYPE_LINEAR_ACCELERATION | Linear acceleration sensor | Measures the linear acceleration (excluding the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Detecting the linear acceleration in each axis | -| SENSOR_TYPE_GRAVITY | Gravity sensor | Measures the gravity acceleration applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Measuring the gravity | -| SENSOR_TYPE_GYROSCOPE | Gyroscope sensor | Measures the rotation angular velocity of a device on three physical axes (X, Y, and Z), in the unit of rad/s.| Measuring the rotation angular velocity | -| SENSOR_TYPE_GYROSCOPE_UNCALIBRATED | Uncalibrated gyroscope sensor| Measures the uncalibrated rotation angular velocity of a device on three physical axes (X, Y, and Z), in the unit of rad/s.| Measuring the bias estimation of the rotation angular velocity | -| SENSOR_TYPE_SIGNIFICANT_MOTION | Significant motion sensor | Checks whether a device has a significant motion on three physical axes (X, Y, and Z). The value **0** means that the device does not have a significant motion, and **1** means the opposite.| Detecting significant motions of a device | -| SENSOR_TYPE_PEDOMETER_DETECTION | Pedometer detection sensor | Detects whether a user takes a step. The value can be **0** (the user does not take a step) or **1** (the user takes a step).| Detecting whether a user takes a step | -| SENSOR_TYPE_PEDOMETER | Pedometer sensor | Records the number of steps a user has walked. | Providing the number of steps a user has walked | -| SENSOR_TYPE_AMBIENT_TEMPERATURE | Ambient temperature sensor | Measures the ambient temperature, in the unit of degree Celsius (°C). | Measuring the ambient temperature | -| SENSOR_TYPE_MAGNETIC_FIELD | Magnetic field sensor | Measures the magnetic field on three physical axes (X, Y, and Z), in the unit of μT.| Creating a compass | -| SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED | Uncalibrated magnetic field sensor | Measures the uncalibrated magnetic field on three physical axes (X, Y, and Z), in the unit of μT.| Measuring the magnetic field bias estimation | -| SENSOR_TYPE_HUMIDITY | Humidity sensor | Measures the ambient relative humidity, in a percentage (%). | Monitoring the dew point, absolute humidity, and relative humidity | -| SENSOR_TYPE_BAROMETER | Barometer sensor | Measures the barometric pressure, in the unit of hPa or mbar. | Measuring the barometric pressure | -| SENSOR_TYPE_ORIENTATION | Orientation sensor | Measures the rotation angles of a device on three physical axes (X, Y, and Z), in the unit of rad.| Providing the three orientation angles of the screen | -| SENSOR_TYPE_ROTATION_VECTOR | Rotation vector sensor | Measures the rotation vector of a device. It is a composite sensor that generates data from the acceleration sensor, magnetic field sensor, and gyroscope sensor.| Detecting the orientation of a device in the East, North, Up (ENU) Cartesian coordinate system | -| SENSOR_TYPE_PROXIMITY | Proximity sensor | Measures the distance between a visible object and the device screen. | Measuring the distance between a person and the device during a call | -| SENSOR_TYPE_AMBIENT_LIGHT | Ambient light sensor | Measures the ambient light intensity of a device, in the unit of lux. | Automatically adjusting the screen brightness and checking whether the screen is covered on the top| -| SENSOR_TYPE_HEART_RATE | Heart rate sensor | Measures the heart rate of a user. | Providing users' heart rate data | -| SENSOR_TYPE_WEAR_DETECTION | Wear detection sensor | Checks whether a user is wearing a wearable device. | Detecting wearables | -| SENSOR_TYPE_HALL | Hall effect sensor | Detects a magnetic field around a device. | Smart cover mode of the device | +| Type | Name | Description | Usage | +| --------------------------------------- | --------- | ---------------------------------------- | -------------------- | +| SENSOR_TYPE_ACCELEROMETER | Acceleration sensor | Measures the acceleration (including the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Detecting the motion status | +| SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED | Uncalibrated acceleration sensor| Measures the uncalibrated acceleration (including the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Measuring the acceleration bias estimation | +| SENSOR_TYPE_LINEAR_ACCELERATION | Linear acceleration sensor | Measures the linear acceleration (excluding the gravity acceleration) applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Detecting the linear acceleration in each axis | +| SENSOR_TYPE_GRAVITY | Gravity sensor | Measures the gravity acceleration applied to a device on three physical axes (X, Y, and Z), in the unit of m/s2.| Measuring the gravity | +| SENSOR_TYPE_GYROSCOPE | Gyroscope sensor | Measures the rotation angular velocity of a device on three physical axes (X, Y, and Z), in the unit of rad/s.| Measuring the rotation angular velocity | +| SENSOR_TYPE_GYROSCOPE_UNCALIBRATED | Uncalibrated gyroscope sensor| Measures the uncalibrated rotation angular velocity of a device on three physical axes (X, Y, and Z), in the unit of rad/s.| Measuring the bias estimation of the rotation angular velocity | +| SENSOR_TYPE_SIGNIFICANT_MOTION | Significant motion sensor | Checks whether a device has a significant motion on three physical axes (X, Y, and Z). The value **0** means that the device does not have a significant motion, and **1** means the opposite.| Detecting significant motions of a device | +| SENSOR_TYPE_PEDOMETER_DETECTION | Pedometer detection sensor | Detects whether a user takes a step. The value can be **0** (the user does not take a step) or **1** (the user takes a step).| Detecting whether a user takes a step | +| SENSOR_TYPE_PEDOMETER | Pedometer sensor | Records the number of steps a user has walked. | Providing the number of steps a user has walked | +| SENSOR_TYPE_AMBIENT_TEMPERATURE | Ambient temperature sensor | Measures the ambient temperature, in the unit of degree Celsius (°C). | Measuring the ambient temperature | +| SENSOR_TYPE_MAGNETIC_FIELD | Magnetic field sensor | Measures the magnetic field on three physical axes (X, Y, and Z), in the unit of μT.| Creating a compass | +| SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED | Uncalibrated magnetic field sensor | Measures the uncalibrated magnetic field on three physical axes (X, Y, and Z), in the unit of μT.| Measuring the magnetic field bias estimation | +| SENSOR_TYPE_HUMIDITY | Humidity sensor | Measures the ambient relative humidity, in a percentage (%). | Monitoring the dew point, absolute humidity, and relative humidity | +| SENSOR_TYPE_BAROMETER | Barometer sensor | Measures the barometric pressure, in the unit of hPa or mbar.| Measuring the barometric pressure | +| SENSOR_TYPE_ORIENTATION | Orientation sensor | Measures the rotation angles of a device on three physical axes (X, Y, and Z), in the unit of rad. | Providing the three orientation angles of the screen | +| SENSOR_TYPE_ROTATION_VECTOR | Rotation vector sensor | Measures the rotation vector of a device. It is a composite sensor that generates data from the acceleration sensor, magnetic field sensor, and gyroscope sensor. | Detecting the orientation of a device in the East, North, Up (ENU) Cartesian coordinate system | +| SENSOR_TYPE_PROXIMITY | Proximity sensor | Measures the distance between a visible object and the device screen. | Measuring the distance between a person and the device during a call | +| SENSOR_TYPE_AMBIENT_LIGHT | Ambient light sensor | Measures the ambient light intensity of a device, in the unit of lux. | Automatically adjusting the screen brightness and checking whether the screen is covered on the top| +| SENSOR_TYPE_HEART_RATE | Heart rate sensor | Measures the heart rate of a user. | Providing users' heart rate data | +| SENSOR_TYPE_WEAR_DETECTION | Wear detection sensor | Checks whether a user is wearing a wearable device. | Detecting wearables | +| SENSOR_TYPE_HALL | Hall effect sensor | Detects a magnetic field around a device. | Smart cover mode of the device | ## Working Principles @@ -52,15 +52,12 @@ The following modules work cooperatively to implement OpenHarmony sensors: Senso 1. To obtain data of the following sensors, you must claim the required permissions. - Table 7 Sensor data permissions - - | Sensor | Permission | Sensitivity | Permission Description | - | ------------------------- | -------------------------------- | ------------ | ----------------------- | - | Acceleration sensor, uncalibrated acceleration sensor, and linear acceleration sensor| ohos.permission.ACCELEROMETER | system_grant | Allows an application to subscribe to data of these acceleration-related sensors in the motion category.| - | Gyroscope sensor and uncalibrated gyroscope sensor | ohos.permission.GYROSCOPE | system_grant | Allows an application to subscribe to data of the gyroscope-related sensors in the motion category.| - | Pedometer sensor | ohos.permission.ACTIVITY_MOTION | user_grant | Allows an application to subscribe to the motion status. | - | Heart rate sensor | ohos.permission.READ_HEALTH_DATA | user_grant | Allows an application to read health data. | - - +| Sensor | Permission | Sensitivity | Permission Description | +| ------------------------- | -------------------------------- | ------------ | ----------------------- | +| Acceleration sensor, uncalibrated acceleration sensor, and linear acceleration sensor| ohos.permission.ACCELEROMETER | system_grant | Allows an application to subscribe to data of these acceleration-related sensors in the motion category.| +| Gyroscope sensor and uncalibrated gyroscope sensor | ohos.permission.GYROSCOPE | system_grant | Allows an application to subscribe to data of the gyroscope-related sensors in the motion category.| +| Pedometer sensor | ohos.permission.ACTIVITY_MOTION | user_grant | Allows an application to subscribe to the motion status. | +| Heart rate sensor | ohos.permission.READ_HEALTH_DATA | user_grant | Allows an application to read health data. | 2. The APIs for subscribing to and unsubscribing from sensor data work in pairs. If you do not need sensor data, call the unsubscription API to stop sensor data reporting. + \ No newline at end of file diff --git a/en/application-dev/device/vibrator-guidelines.md b/en/application-dev/device/vibrator-guidelines.md index 9731fa6cec8da388719b61cf7cf7b0e542f87ca4..0dfc8344e5bb27a7ab6b6cd11943595c9f7855a6 100644 --- a/en/application-dev/device/vibrator-guidelines.md +++ b/en/application-dev/device/vibrator-guidelines.md @@ -10,77 +10,42 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md ## Available APIs -| Module| API| Description| -| -------- | -------- | -------- | -| ohos.vibrator | vibrate(duration: number): Promise<void> | Triggers vibration with the specified duration. This API uses a promise to return the result.| -| ohos.vibrator | vibrate(duration: number, callback?: AsyncCallback<void>): void | Triggers vibration with the specified duration. This API uses a callback to return the result.| -| ohos.vibrator | vibrate(effectId: EffectId): Promise<void> | Triggers vibration with the specified effect. This API uses a promise to return the result.| +| Module | API | Description | +| ------------- | ---------------------------------------- | ------------------------------- | +| ohos.vibrator | vibrate(duration: number): Promise<void> | Triggers vibration with the specified duration. This API uses a promise to return the result. | +| ohos.vibrator | vibrate(duration: number, callback?: AsyncCallback<void>): void | Triggers vibration with the specified duration. This API uses a callback to return the result. | +| ohos.vibrator | vibrate(effectId: EffectId): Promise<void> | Triggers vibration with the specified effect. This API uses a promise to return the result. | | ohos.vibrator | vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void | Triggers vibration with the specified effect. This API uses a callback to return the result.| -| ohos.vibrator | stop(stopMode: VibratorStopMode): Promise<void> | Stops vibration. This API uses a promise to return the result.| -| ohos.vibrator | stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void | Stops vibration. This API uses a callback to return the result.| +| ohos.vibrator | stop(stopMode: VibratorStopMode): Promise<void>| Stops vibration. This API uses a promise to return the result. | +| ohos.vibrator | stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void | Stops vibration. This API uses a callback to return the result. | ## How to Develop -1. Declare the permissions required for controlling vibrators on the hardware device in the `config.json` file. - - ``` - "reqPermissions": [ - { - "name": "ohos.permission.ACCELEROMETER", - "reason": "", - "usedScene": { - "ability": [ - ".MainAbility" - ], - "when": "inuse" - } - }, - { - "name": "ohos.permission.VIBRATE", - "reason": "", - "usedScene": { - "ability": [ - ".MainAbility" - ], - "when": "inuse" - } - }, - { - "name": "ohos.permission.ACTIVITY_MOTION", - "reason": "", - "usedScene": { - "ability": [ - ".MainAbility" - ], - "when": "inuse" - } - }, - ] - ``` +1. Before using the vibrator on a device, you must declare the **ohos.permission.VIBRATE** permission. For details about how to configure a permission, see [Declaring Permissions](../security/accesstoken-guidelines.md). 2. Trigger the device to vibrate. - + ``` import vibrator from "@ohos.vibrator" - vibrator.vibrate(1000).then((error)=>{ - if (error){ // The call fails, and error.code and error.message are printed. - Console.log("Promise return failed.error.code"+error.code+"error.message"+error.message); - }else{ // The call is successful, and the device starts to vibrate. - Console.log("Promise returned to indicate a successful vibration.") - }; + vibrator.vibrate(1000).then((error) => { + if (error) { // The call fails, and error.code and error.message are printed. + console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); + } else { // The call is successful, and the device starts to vibrate. + console.log("Promise returned to indicate a successful vibration.") + } }) ``` 3. Stop the vibration. - + ``` import vibrator from "@ohos.vibrator" - vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then((error)=>{ - if(error){ // The call fails, and error.code and error.message are printed. - Console.log("Promise return failed.error.code"+error.code+"error.message"+error.message); - }else{ // The call is successful, and the device stops vibrating. - Console.log("Promise returned to indicate a successful stop."); - }; + vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then((error) => { + if (error) { // The call fails, and error.code and error.message are printed. + console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); + } else { // The call is successful, and the device stops vibrating. + console.log("Promise returned to indicate successful."); + } }) ``` diff --git a/en/application-dev/device/vibrator-overview.md b/en/application-dev/device/vibrator-overview.md index 05e9b06d5c906c7e0ad46a6dc7e7f65400b6bc20..045419585fb852efb033cc87a085a1d2a80a9488 100644 --- a/en/application-dev/device/vibrator-overview.md +++ b/en/application-dev/device/vibrator-overview.md @@ -10,7 +10,7 @@ The vibrator is a Misc device that consists of four modules: Vibrator API, Vibra **Figure 1** Vibrator in Misc devices -![en-us_image_0000001180249428.png](figures/en-us_image_0000001180249428.png) +![0752d302-aeb9-481a-bb8f-e5524eb61eeb](figures/0752d302-aeb9-481a-bb8f-e5524eb61eeb.png) - Vibrator API: provides basic vibrator APIs, including the APIs for obtaining the vibrator list, querying the vibrator by effect, and triggering and stopping vibration. @@ -23,4 +23,7 @@ The vibrator is a Misc device that consists of four modules: Vibrator API, Vibra ## Constraints -When using a vibrator, you must declare the **ohos.permission.VIBRATE** permission before you can control the vibration effect. The authorization mode of this permission is **system_grant**. +When using a vibrator, you must declare the **ohos.permission.VIBRATE** permission before you can control the vibration effect. + + +