cap-sensing-kit

Installation

Install the package via npm

npm install --save cap-sensing-kit

In your capacitor project, make sure to register the Android plugin in in the projects MainActivity as follows

import com.sensingkit.plugin.SensingKit;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
      add(SensingKit.class);
    }});
  }
}

In your application, use the plugin as described below

import "cap-sensing-kit";
import {Plugins} from "@capacitor/core";

const {SensingKit} = Plugins;

//...do something with the plugin

If you just want to use the web implementation, you can import the plugin directly

import {SensingKit} from "cap-sensing-kit";
//...do something with the plugin

Availability

The web implementation of this plugin uses the Generic Sensor API which is not implemented in many Browsers by now.

SensorType	Web	Android	iOS	Description
AMBIENT_LIGHT	[x] *	[x]		Measures the ambient light level (illumination) in lx.
AMBIENT_PRESSURE		[x]		Measures the ambient air pressure in hPa or mbar.
AMBIENT_TEMPERATURE		[x]		Measures the ambient room temperature in degrees Celsius (°C).
RELATIVE_HUMIDITY		[x]		Measures the relative ambient humidity in percent (%).
ACCELEROMETER	[x] *	[x]		Measures the acceleration force in m/s2 that is applied to a device on all three physical axes (x, y, and z), including the force of gravity.
GRAVITY		[x]		Measures the force of gravity in m/s2 that is applied to a device on all three physical axes (x, y, z).
GYROSCOPE	[x] *	[x]		Measures a device's rate of rotation in rad/s around each of the three physical axes (x, y, and z).
LINEAR_ACCELERATION	[x] *	[x]		Measures the acceleration force in m/s2 that is applied to a device on all three physical axes (x, y, and z), excluding the force of gravity.
ROTATION_VECTOR		[x]		Measures the orientation of a device by providing the three elements of the device's rotation vector.
GAME_ROTATION_VECTOR		[x]
GEOMAGNETIC_ROTATION_VECTOR		[x]
MAGENTIC_FIELD	[x] *	[x]		Measures the ambient geomagnetic field for all three physical axes (x, y, z) in μT.
PROXIMITY		[x]		Measures the proximity of an object in cm relative to the view screen of a device.
ABSOLUTE_ORIENTATION	[x] *
RELATIVE_ORIENTATION	[x] *

* requires chrome://flags/#enable-generic-sensor-extra-classes to be enabled

Usage

Below, an example of working with a mobile device's ambient light sensor

import "cap-sensing-kit";
import {Plugins} from "@capacitor/core";
import {SensorType, sensorChangedEventName} from "cap-sensing-kit";
const {SensingKit} = Plugins;

const name = SensorType.AMBIENT_LIGHT; 

const {isAvailable} = await SensingKit.isSensorAvailable({name});
const {isActive} = await SensingKit.isSensorActive({name});

if(isAvailable && !isActive){
    await SensingKit.start({name});
}

const event = sensorChangedEventName(name);
const listener = SensingKit.addListener(event, (data) => {

    //Do something ... for example:
    const {value} = data;
    console.log(`Ambient light level changed...illuminance is ${value} lx`);
};

//...

await SensingKit.stop({name});
listener.remove()

API Documentation

Following, an overview over the available SensorKit methods

isSensorAvailable

isSensorAvailable(options: {name: string}): Promise<{isAvailable: boolean}> Checks whether a specific sensor is available on the device. Note: Since it is not possible to check whether a specific sensor is available or not within a web browser without trying to start it, the web implementation simply checks if the corresponding sensor API (e.g. AmbientLightSensor API) is available.

isSensorActive

isSensorActive(options: {name: string}): Promise<{isActive: boolean}> Checks whether a specific sensor was already started through the plugin.

start

start(options: {name: string, frequency?: number}): Promise<void> Starts the propagation of sensor events for the specified sensor. With the frequency property, the sampling rate (in Hz) of the sensor can be specified (if supported). frequency defaults to the maximum sampling rate (specified by browser specific Sensor API implementation) for a sensor, in the web implementation. For Android it defaults to SENSOR_DELAY_NORMAL (5 Hz). Note: Frequency is only a suggested value

stop

stop(options: {name: string}): Promise<void> Stops the propagation of sensor events for the specified sensor.