Maintainers

| Maintainer | GitHub | Social | | -----------| -------| -------| | Elvin Chu | Elvincth | @elvincth |

Installation

Step 1

npm install capacitor-plugin-lightsensor --save
npx cap sync

Step 2

IOS Platform: No further action required.

Android Platform: Register the plugin in your main activity (MainActivity.java):

import com.gren.plugin.lightsensor.LightSensor; //ADD this line

public class MainActivity extends BridgeActivity {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    this.init(
        savedInstanceState,
        new ArrayList<Class<? extends Plugin>>() {

          {
             add(LightSensor.class); //ADD this line
          }
        }
      );
  }
}

Supported methods

| Name | Android | iOS | Web | | :------------------ | :------ | :-- | :-- | | init | ✅ | ❌ | ✅ | | registerListener | ✅ | ❌ | ✅ | | unregisterListener | ✅ | ❌ | ✅ | | getInfo | ✅ | ❌ | ❌ | | isAvailable | ✅ | ❌ | ✅ |

Usage

Getting illuminance level

import { SensorManager } from "capacitor-plugin-lightsensor";
import { Plugins } from "@capacitor/core"; 
const { LightSensor } = Plugins;

async function getLux() {
  try {
    //Initialize the sensor with some settings
    await LightSensor.init({
      SensorDelay: SensorManager.SENSOR_DELAY_UI, //Optional, for android only Default is SENSOR_DELAY_NORMAL
    });

    //Register onLightSensorChanged listener
    await LightSensor.registerListener();

    //Listen for the sensor change
    window.addEventListener("onLightSensorChanged", (evt) => {
      console.log("value", evt.value); //The illuminance (lux) level 
      console.log("accuracy", evt.accuracy); //Android only the accuracy of this event, for web return -1
      console.log("timestamp", evt.timestamp); //For android in nanoseconds, For web in millisecond
      
      console.log("onLightSensorChanged", JSON.stringify(evt));  
      //{"isTrusted":false,"accuracy":3,"timestamp":58769305913765,"value":281.9115905761719}
    });

  } catch (error) {
    console.log("Error occur:", error);
  }
}

Pause the sensor after registered

import { SensorManager } from "capacitor-plugin-lightsensor";
import { Plugins } from "@capacitor/core"; 
const { LightSensor } = Plugins;

async function pause() {
  try {
   
    //Pause the sesnor
    await LightSensor.unregisterListener();
    
    //To resume, run register again
    //await LightSensor.registerListener();

  } catch (error) {
    console.log("Error occur:", error);
  }
}

Check the availability of light sensor

import { SensorManager } from "capacitor-plugin-lightsensor";
import { Plugins } from "@capacitor/core"; 
const { LightSensor } = Plugins;

async function checkSensor() {
  const isSensorAvailable = await LightSensor.isAvailable();

  if (isSensorAvailable.status) {
    console.log("There is light sensor on this device");
  } else {
    console.log("No light sensor on this device");
  }
  
  console.log("isSensorAvailable", JSON.stringify(isSensorAvailable)); // {"status":true} or {"status":false}
}

Getting the light sensor information (Android ONLY)

import { SensorManager } from "capacitor-plugin-lightsensor";
import { Plugins } from "@capacitor/core"; 
const { LightSensor } = Plugins;

async function getInfo() {
  try {
    const sensorInfo = await LightSensor.getInfo();

    //For android only, if web all number will return -1
    
    console.log("vendor", sensorInfo.vendor); //vendor string of this sensor
    console.log("version", sensorInfo.version); //version of the sensor's module
    console.log("type", sensorInfo.type); //generic type of this sensor
    console.log("maxRange", sensorInfo.maxRange); //maximum range of the sensor in the sensor's unit.
    console.log("resolution", sensorInfo.resolution); //resolution of the sensor in the sensor's unit.
    console.log("power", sensorInfo.power); //the power in mA used by this sensor while in use
    console.log("minDelay", sensorInfo.minDelay); //the minimum delay allowed between two events in microsecond or zero if this sensor only returns a value when the data it's measuring changes.
    console.log("minDelay", sensorInfo.maxDelay); //The max delay for this sensor in microseconds.

    console.log("sensorInfo", JSON.stringify(sensorInfo));
    //{"vendor":"OnePlus","version":1,"type":5,"maxRange":4096,"resolution":1,"power":1.7049999237060547,"minDelay":0,"maxDelay":0}
  } catch (error) {
    console.log("Light sensor not available");
  }
}

API

Methods

init(...)

Initialize the light sensor with settings (See example here )

| Param | Type | Description | |---------|---------|------------------------| | option | object | See option table |

Option

| Key | Type | Description | |-------------|-------------------------------------|------------------------------------------------------------------------| | SensorDelay | Enum (SensorManager) | Optional, for android only Default is SensorManager.SENSOR_DELAY_NORMAL |

Returns: Promise

registerListener()

Register onLightSensorChanged listener (To start or resume the sensor, see example here )

Returns: Promise

unregisterListener()

Unregister onLightSensorChanged listener (To stop or pause the sensor, see example here )

Returns: Promise

isAvailable()

Check if the device have a light sensor or not (See example here )

Returns: Promise of following object structure:

| Key | Type | Description | |--------|---------|--------------------| | status | Boolean | Have light sensor? |

getInfo()

Get light sensor information (See example here )

Returns: Promise of following object structure:

| Key | Type | Description | |------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------| | vendor | object | Vendor string of this sensor | | version | Number | Version of the sensor's module | | type | Number | Generic type of this sensor | | maxRange | Number | Maximum range of the sensor in the sensor's unit | | resolution | Number | Resolution of the sensor in the sensor's unit | | power | Number | The power in mA used by this sensor while in use | | minDelay | Number | The minimum delay allowed between two events in microsecond or zero if this sensor only returns a value when the data it's measuring changes | | maxDelay | Number | The max delay for this sensor in microseconds |

Events

onLightSensorChanged

See example here

Returns: object of following object structure:

| Key | Type | Description | |-----------|---------|--------------------------------------------------------------------------------------------------------------------| | isTrusted | Boolean | Returns true if event was dispatched by the user agent, and false otherwise. (Capacitor thing you can ignore this) | | accuracy | Boolean | Android only the accuracy of this event, for web return -1 | | timestamp | Number | For android in nanoseconds, For web in millisecond | | value | Number | The illuminance (lux) level |

Enums

SensorManager

| Members | Value | Description | |----------------------|-------|-----------------------------------------------| | SENSOR_DELAY_FASTEST | 0 | Get sensor data as fast as possible | | SENSOR_DELAY_GAME | 1 | Rate suitable for games | | SENSOR_DELAY_UI | 2 | Rate suitable for the user interface | | SENSOR_DELAY_NORMAL | 3 | Normal rate (Default) |