1# @ohos.sensor (Sensor) (System API) 2 3The **Sensor** module provides APIs for obtaining the sensor list and subscribing to sensor data. It also provides some common sensor algorithms. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs provided by this module are system APIs. 10 11 12## Modules to Import 13 14```ts 15import { sensor } from '@kit.SensorServiceKit'; 16``` 17 18## sensor.on 19 20### COLOR<sup>10+</sup> 21 22on(type: SensorId.COLOR, callback: Callback<ColorResponse>, options?: Options): void 23 24Subscribes to data of the color sensor. 25 26**System capability**: SystemCapability.Sensors.Sensor 27 28**System API**: This is a system API. 29 30**Parameters** 31 32| Name | Type | Mandatory| Description | 33| -------- | ------------------------------------------------- | ---- | ----------------------------------------------------------- | 34| type | [SensorId](#sensorid9).COLOR | Yes | Sensor type. The value is fixed at **SensorId.COLOR**. | 35| callback | Callback<[ColorResponse](#colorresponse10)> | Yes | Callback used to report the sensor data, which is a **ColorResponse** object. | 36| options | [Options](js-apis-sensor.md#options) | No | List of optional parameters. This parameter is used to set the data reporting frequency. The default value is 200,000,000 ns.| 37 38**Error codes** 39 40For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) and [Universal Error Codes](../errorcode-universal.md). 41 42| ID| Error Message | 43| -------- | ------------------------------------------------------------ | 44| 202 | Permission check failed. A non-system application uses the system API. | 45| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 46| 14500101 | Service exception. | 47 48**Example** 49 50```ts 51import { sensor } from '@kit.SensorServiceKit'; 52import { BusinessError } from '@kit.BasicServicesKit'; 53 54try{ 55 sensor.on(sensor.SensorId.COLOR, (data: sensor.ColorResponse) => { 56 console.log('Succeeded in getting the intensity of light: ' + data.lightIntensity); 57 console.log('Succeeded in getting the color temperature: ' + data.colorTemperature); 58 }, { interval: 100000000 }); 59 setTimeout(() => { 60 sensor.off(sensor.SensorId.COLOR); 61 }, 500); 62} catch (error) { 63 let e: BusinessError = error as BusinessError; 64 console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); 65} 66``` 67 68### SAR<sup>10+</sup> 69 70on(type: SensorId.SAR, callback: Callback<SarResponse>, options?: Options): void 71 72Subscribes to data of the Sodium Adsorption Ratio (SAR) sensor. 73 74**System capability**: SystemCapability.Sensors.Sensor 75 76**System API**: This is a system API. 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| -------- | --------------------------------------------- | ---- | ----------------------------------------------------------- | 82| type | [SensorId](#sensorid9).SAR | Yes | Sensor type. The value is fixed at **SensorId.SAR**. | 83| callback | Callback<[SarResponse](#sarresponse10)> | Yes | Callback used to report the sensor data, which is a **SarResponse** object. | 84| options | [Options](js-apis-sensor.md#options) | No | List of optional parameters. This parameter is used to set the data reporting frequency. The default value is 200,000,000 ns.| 85 86**Error codes** 87 88For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) and [Universal Error Codes](../errorcode-universal.md). 89 90| ID| Error Message | 91| -------- | ------------------------------------------------------------ | 92| 202 | Permission check failed. A non-system application uses the system API. | 93| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 94| 14500101 | Service exception. | 95 96**Example** 97 98```ts 99import { sensor } from '@kit.SensorServiceKit'; 100import { BusinessError } from '@kit.BasicServicesKit'; 101 102try { 103 sensor.on(sensor.SensorId.SAR, (data: sensor.SarResponse) => { 104 console.info('Succeeded in getting specific absorption rate : ' + data.absorptionRatio); 105 }, { interval: 100000000 }); 106 setTimeout(() => { 107 sensor.off(sensor.SensorId.SAR); 108 }, 500); 109} catch (error) { 110 let e: BusinessError = error as BusinessError; 111 console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); 112} 113``` 114 115## sensor.off 116 117### COLOR<sup>10+</sup> 118 119off(type: SensorId.COLOR, callback?: Callback<ColorResponse>): void 120 121Unsubscribes from data of the color sensor. 122 123**System capability**: SystemCapability.Sensors.Sensor 124 125**System API**: This is a system API. 126 127**Parameters** 128 129| Name | Type | Mandatory| Description | 130| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 131| type | [SensorId](#sensorid9).COLOR | Yes | Sensor type. The value is fixed at **SensorId.COLOR**. | 132| callback | Callback<[ColorResponse](#colorresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| 133 134**Error codes** 135 136For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 137 138| ID| Error Message | 139| -------- | ------------------------------------------------------------ | 140| 202 | Permission check failed. A non-system application uses the system API. | 141| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 142 143**Example** 144 145```ts 146import { sensor } from '@kit.SensorServiceKit'; 147import { BusinessError } from '@kit.BasicServicesKit'; 148 149function callback1(data: object) { 150 console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); 151} 152 153function callback2(data: object) { 154 console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); 155} 156 157try { 158 sensor.on(sensor.SensorId.COLOR, callback1); 159 sensor.on(sensor.SensorId.COLOR, callback2); 160 // Unsubscribe from callback1. 161 sensor.off(sensor.SensorId.COLOR, callback1); 162 // Unsubscribe from all callbacks of the SensorId.COLOR type. 163 sensor.off(sensor.SensorId.COLOR); 164} catch (error) { 165 let e: BusinessError = error as BusinessError; 166 console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); 167} 168``` 169 170### SAR<sup>10+</sup> 171 172off(type: SensorId.SAR, callback?: Callback<SarResponse>): void 173 174Unsubscribes from data of the SAR sensor. 175 176**System capability**: SystemCapability.Sensors.Sensor 177 178**System API**: This is a system API. 179 180**Parameters** 181 182| Name | Type | Mandatory| Description | 183| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 184| type | [SensorId](#sensorid9).SAR | Yes | Sensor type. The value is fixed at **SensorId.SAR**. | 185| callback | Callback<[SarResponse](#sarresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| 186 187**Error codes** 188 189For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 190 191| ID| Error Message | 192| -------- | ------------------------------------------------------------ | 193| 202 | Permission check failed. A non-system application uses the system API. | 194| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 195 196**Example** 197 198```ts 199import { sensor } from '@kit.SensorServiceKit'; 200import { BusinessError } from '@kit.BasicServicesKit'; 201 202function callback1(data: object) { 203 console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); 204} 205 206function callback2(data: object) { 207 console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); 208} 209 210try { 211 sensor.on(sensor.SensorId.SAR, callback1); 212 sensor.on(sensor.SensorId.SAR, callback2); 213 // Unsubscribe from callback1. 214 sensor.off(sensor.SensorId.SAR, callback1); 215 // Unsubscribe from all callbacks of the SensorId.SAR type. 216 sensor.off(sensor.SensorId.SAR); 217} catch (error) { 218 let e: BusinessError = error as BusinessError; 219 console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); 220} 221``` 222 223## SensorId<sup>9+</sup> 224 225Enumerates the sensor types. 226 227**System capability**: SystemCapability.Sensors.Sensor 228 229| Name | Value | Description | 230| ------------------- | ---- | --------------------------------------------- | 231| COLOR<sup>10+</sup> | 14 | Color sensor.<br>System API: This is a system API. | 232| SAR<sup>10+</sup> | 15 | Sodium Adsorption Ratio (SAR) sensor.<br>System API: This is a system API.| 233 234## ColorResponse<sup>10+</sup> 235 236Describes the color sensor data. It extends from [Response](js-apis-sensor.md#response). 237 238**System capability**: SystemCapability.Sensors.Sensor 239 240**System API**: This is a system API. 241 242 243| Name | Type | Readable| Writable| Description | 244| ---------------- | ------ | ---- | ---- | ----------------------------- | 245| lightIntensity | number | Yes | Yes | Intensity of light, in lux.| 246| colorTemperature | number | Yes | Yes | Color temperature, in Kelvin. | 247 248## SarResponse<sup>10+ </sup> 249 250Describes the SAR sensor data. It extends from [Response](js-apis-sensor.md#response). 251 252**System capability**: SystemCapability.Sensors.Sensor 253 254**System API**: This is a system API. 255 256 257| Name | Type | Readable| Writable| Description | 258| --------------- | ------ | ---- | ---- | ------------------------------- | 259| absorptionRatio | number | Yes | Yes | Absorption ratio, in W/kg.| 260