Skip to content
Capacitor plugin for accessing device sensors
Java TypeScript Swift Ruby Objective-C JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
android
ios
src
.gitignore
.npmignore
CapSensingKit.podspec
package-lock.json
package.json
readme.md
rollup.config.js
tsconfig.json

readme.md

npm version

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
  • *
Measures the ambient light level (illumination) in lx.
AMBIENT_PRESSURE
Measures the ambient air pressure in hPa or mbar.
AMBIENT_TEMPERATURE
Measures the ambient room temperature in degrees Celsius (°C).
RELATIVE_HUMIDITY
Measures the relative ambient humidity in percent (%).
ACCELEROMETER
  • *
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
Measures the force of gravity in m/s2 that is applied to a device on all three physical axes (x, y, z).
GYROSCOPE
  • *
Measures a device's rate of rotation in rad/s around each of the three physical axes (x, y, and z).
LINEAR_ACCELERATION
  • *
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
Measures the orientation of a device by providing the three elements of the device's rotation vector.
GAME_ROTATION_VECTOR
GEOMAGNETIC_ROTATION_VECTOR
MAGENTIC_FIELD
  • *
Measures the ambient geomagnetic field for all three physical axes (x, y, z) in μT.
PROXIMITY
Measures the proximity of an object in cm relative to the view screen of a device.
ABSOLUTE_ORIENTATION
  • *
RELATIVE_ORIENTATION
  • *

* 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.

You can’t perform that action at this time.