@ohos.sensor (Sensor) (System API)

The Sensor module provides APIs for obtaining the sensor list and subscribing to sensor data. It also provides some common sensor algorithms.

NOTE

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.

The APIs provided by this module are system APIs.

Modules to Import

import { sensor } from '@kit.SensorServiceKit';

sensor.on

COLOR¹⁰⁺

on(type: SensorId.COLOR, callback: Callback<ColorResponse>, options?: Options): void

Subscribes to data of the color sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.COLOR	Yes	Sensor type. The value is fixed at SensorId.COLOR.
callback	Callback<ColorResponse>	Yes	Callback used to report the sensor data, which is a ColorResponse object.
options	Options	No	List of optional parameters. This parameter is used to set the data reporting frequency. The default value is 200,000,000 ns.

Error codes

For details about the error codes, see Sensor Error Codes and Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.
14500101	Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try{
  sensor.on(sensor.SensorId.COLOR, (data: sensor.ColorResponse) => {
    console.info('Succeeded in getting the intensity of light: ' + data.lightIntensity);
    console.info('Succeeded in getting the color temperature: ' + data.colorTemperature);
  }, { interval: 100000000 });
  setTimeout(() => {
        sensor.off(sensor.SensorId.COLOR);
  }, 500);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
}

SAR¹⁰⁺

on(type: SensorId.SAR, callback: Callback<SarResponse>, options?: Options): void

Subscribes to data of the Sodium Adsorption Ratio (SAR) sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.SAR	Yes	Sensor type. The value is fixed at SensorId.SAR.
callback	Callback<SarResponse>	Yes	Callback used to report the sensor data, which is a SarResponse object.
options	Options	No	List of optional parameters. This parameter is used to set the data reporting frequency. The default value is 200,000,000 ns.

Error codes

For details about the error codes, see Sensor Error Codes and Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.
14500101	Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  sensor.on(sensor.SensorId.SAR, (data: sensor.SarResponse) => {
    console.info('Succeeded in getting specific absorption rate : ' + data.absorptionRatio);
  }, { interval: 100000000 });
  setTimeout(() => {
    sensor.off(sensor.SensorId.SAR);
  }, 500);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
}

sensor.off

COLOR¹⁰⁺

off(type: SensorId.COLOR, callback?: Callback<ColorResponse>): void

Unsubscribes from data of the color sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.COLOR	Yes	Sensor type. The value is fixed at SensorId.COLOR.
callback	Callback<ColorResponse>	No	Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

function callback1(data: object) {
  console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data));
}

function callback2(data: object) {
  console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data));
}

try {
  sensor.on(sensor.SensorId.COLOR, callback1);
  sensor.on(sensor.SensorId.COLOR, callback2);
  // Unsubscribe from callback1.
  sensor.off(sensor.SensorId.COLOR, callback1);
  // Unsubscribe from all callbacks of the SensorId.COLOR type.
  sensor.off(sensor.SensorId.COLOR);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
}

COLOR¹⁹⁺

off(type: SensorId.COLOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<ColorResponse>): void

Unsubscribes from data of the color sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.COLOR	Yes	Sensor type. The value is fixed at SensorId.COLOR.
sensorInfoParam	SensorInfoParam	No	Sensor parameters, including deviceId and sensorIndex.
callback	Callback<ColorResponse>	No	Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
14500101	Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

enum Ret { OK, Failed = -1 }

// Sensor callback
const sensorCallback = (response: sensor.ColorResponse) => {
  console.info(`callback response: ${JSON.stringify(response)}`);
}
// Sensor type
const sensorType = sensor.SensorId.COLOR;
const sensorInfoParam: sensor.SensorInfoParam = {};

function sensorSubscribe(): Ret {
  let ret: Ret = Ret.OK;
  try {
    // Query all sensors.
    const sensorList: sensor.Sensor[] = sensor.getSensorListSync();
    if (!sensorList.length) {
      return Ret.Failed;
    }
    // Obtain the target sensor based on the actual service logic.
    const targetSensor = sensorList
      // Filter all sensors with deviceId 1 and sensorId 2 as required. This example is for reference only. You need to adjust the filtering logic accordingly.
      .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2)
      // Select the sensor with sensorIndex 0 among all sensors of the same type.
      .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0);
    if (!targetSensor) {
      return Ret.Failed;
    }
    sensorInfoParam.deviceId = targetSensor.deviceId;
    sensorInfoParam.sensorIndex = targetSensor.sensorIndex;
    // Subscribe to sensor events.
    sensor.on(sensorType, sensorCallback, { sensorInfoParam });
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`);
    ret = Ret.Failed;
  }
  return ret;
}

function sensorUnsubscribe(): Ret {
  let ret: Ret = Ret.OK;
  try {
    sensor.off(sensorType, sensorInfoParam, sensorCallback);
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`);
    ret = Ret.Failed;
  }
  return ret;
}

SAR¹⁰⁺

off(type: SensorId.SAR, callback?: Callback<SarResponse>): void

Unsubscribes from data of the SAR sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.SAR	Yes	Sensor type. The value is fixed at SensorId.SAR.
callback	Callback<SarResponse>	No	Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

function callback1(data: object) {
  console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data));
}

function callback2(data: object) {
  console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data));
}

try {
  sensor.on(sensor.SensorId.SAR, callback1);
  sensor.on(sensor.SensorId.SAR, callback2);
  // Unsubscribe from callback1.
  sensor.off(sensor.SensorId.SAR, callback1);
  // Unsubscribe from all callbacks of the SensorId.SAR type.
  sensor.off(sensor.SensorId.SAR);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
}

SAR¹⁹⁺

off(type: SensorId.SAR, sensorInfoParam?: SensorInfoParam, callback?: Callback<SarResponse>): void

Unsubscribes from data of the SAR sensor.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	SensorId.SAR	Yes	Sensor type. The value is fixed at SensorId.SAR.
sensorInfoParam	SensorInfoParam	No	Sensor parameters, including deviceId and sensorIndex.
callback	Callback<SarResponse>	No	Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission check failed. A non-system application uses the system API.
14500101	Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception.

Example

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

enum Ret { OK, Failed = -1 }

// Sensor callback
const sensorCallback = (response: sensor.SarResponse) => {
  console.info(`callback response: ${JSON.stringify(response)}`);
}
// Sensor type
const sensorType = sensor.SensorId.SAR;
const sensorInfoParam: sensor.SensorInfoParam = {};

function sensorSubscribe(): Ret {
  let ret: Ret = Ret.OK;
  try {
    // Query all sensors.
    const sensorList: sensor.Sensor[] = sensor.getSensorListSync();
    if (!sensorList.length) {
      return Ret.Failed;
    }
    // Obtain the target sensor based on the actual service logic.
    const targetSensor = sensorList
      // Filter all sensors with deviceId 1 and sensorId 2 as required. This example is for reference only. You need to adjust the filtering logic accordingly.
      .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2)
      // Select the sensor with sensorIndex 0 among all sensors of the same type.
      .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0);
    if (!targetSensor) {
      return Ret.Failed;
    }
    sensorInfoParam.deviceId = targetSensor.deviceId;
    sensorInfoParam.sensorIndex = targetSensor.sensorIndex;
    // Subscribe to sensor events.
    sensor.on(sensorType, sensorCallback, { sensorInfoParam });
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`);
    ret = Ret.Failed;
  }
  return ret;
}

function sensorUnsubscribe(): Ret {
  let ret: Ret = Ret.OK;
  try {
    sensor.off(sensorType, sensorInfoParam, sensorCallback);
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`);
    ret = Ret.Failed;
  }
  return ret;
}

SensorId⁹⁺

Enumerates the sensor types.

System capability: SystemCapability.Sensors.Sensor

Name	Value	Description
COLOR¹⁰⁺	14	Color sensor. System API: This is a system API.
SAR¹⁰⁺	15	Sodium Adsorption Ratio (SAR) sensor. System API: This is a system API.

ColorResponse¹⁰⁺

Describes the color sensor data. It extends from Response.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
lightIntensity	number	No	No	Intensity of light, in lux.
colorTemperature	number	No	No	Color temperature, in Kelvin.

SarResponse¹⁰⁺

Describes the SAR sensor data. It extends from Response.

System capability: SystemCapability.Sensors.Sensor

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
absorptionRatio	number	No	No	Absorption ratio, in W/kg.

SensorInfoParam¹⁹⁺

Defines sensor parameters.

System capability: SystemCapability.Sensors.Sensor

Atomic service API: This API can be used in atomic services since API version 19.

Name	Type	Read-Only	Optional	Description
deviceId	number	No	Yes	Device ID. The default value is -1, indicating the local device. You can use getSensorList or sensorStatusChange to obtain the device ID.
sensorIndex	number	No	Yes	Sensor index. The default value is 0, which indicates the default sensor on the device. You can use getSensorList or sensorStatusChange to obtain the sensor ID.

@ohos.sensor (Sensor) (System API)

Modules to Import

sensor.on

COLOR10+

SAR10+

sensor.off

COLOR10+

COLOR19+

SAR10+

SAR19+

SensorId9+

ColorResponse10+

SarResponse10+

SensorInfoParam19+

COLOR¹⁰⁺

SAR¹⁰⁺

COLOR¹⁰⁺

COLOR¹⁹⁺

SAR¹⁰⁺

SAR¹⁹⁺

SensorId⁹⁺

ColorResponse¹⁰⁺

SarResponse¹⁰⁺

SensorInfoParam¹⁹⁺