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&lt;ColorResponse&gt;, 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&lt;[ColorResponse](#colorresponse10)&gt; | 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&lt;SarResponse&gt;, 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&lt;[SarResponse](#sarresponse10)&gt; | 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&lt;ColorResponse&gt;): 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&lt;[ColorResponse](#colorresponse10)&gt; | 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&lt;SarResponse&gt;): 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&lt;[SarResponse](#sarresponse10)&gt; | 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