@capgo/capacitor-light-sensor

Capacitor plugin for accessing the device's ambient light sensor.

Why Capacitor Light Sensor?

• Real Ambient Light Data: Get accurate light level readings in lux
• Efficient Sensor Access: Uses native Android sensor APIs for optimal performance
• Configurable Update Intervals: Control how often you receive sensor updates
• Battery Conscious: Start and stop the sensor as needed to conserve battery
• TypeScript Support: Full type definitions for a great developer experience

Platform Support

| Platform | Support | |----------|---------| | Android | ✅ Full support via TYPE_LIGHT sensor | | iOS | ❌ Not available (no public API) | | Web | ❌ Not available |

Installation

npm install @capgo/capacitor-light-sensor
npx cap sync

Requirements

Android

• Minimum SDK: 24 (Android 7.0)
• Target SDK: 36
• Device must have a light sensor (most Android phones do)

High Sampling Rate (Android 12+)

For update intervals below 200ms on Android 12 and above, add this permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

Usage

import { LightSensor } from '@capgo/capacitor-light-sensor';

// Check if sensor is available
const { available } = await LightSensor.isAvailable();

if (available) {
  // Start listening with 500ms update interval
  await LightSensor.start({ updateInterval: 500 });

  // Add listener for sensor data
  const handle = await LightSensor.addListener('lightSensorChange', (data) => {
    console.log(`Light level: ${data.illuminance} lux`);
    console.log(`Timestamp: ${data.timestamp}`);
  });

  // Later, stop the sensor
  await LightSensor.stop();
  await handle.remove();
}

Light Level Reference

| Lux Value | Condition | |-----------|-----------| | 0.0001 | Moonless, overcast night | | 0.27-1 | Full moon on a clear night | | 3.4 | Dark limit of civil twilight | | 50 | Family living room | | 80 | Office hallway | | 100 | Very dark overcast day | | 400 | Sunrise/sunset on clear day | | 1,000 | Overcast day | | 10,000-25,000 | Full daylight (indirect) | | 32,000-100,000 | Direct sunlight |

API

• isAvailable()
• start(...)
• stop()
• addListener('lightSensorChange', ...)
• removeAllListeners()
• checkPermissions()
• requestPermissions()
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor plugin for accessing the device's ambient light sensor.

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check if the light sensor is available on the current device. You should always check sensor availability before attempting to use it.

Returns: Promise<IsAvailableResult>

Since: 0.0.1

start(...)

start(options?: StartOptions | undefined) => Promise<void>

Start listening to light sensor updates. This will begin sensor measurements at the specified interval. Use addListener to receive the sensor data.

| Param | Type | Description | | ------------- | ----------------------------------------------------- | -------------------------------------- | | options | StartOptions | - Configuration options for the sensor |

Since: 0.0.1

stop()

stop() => Promise<void>

Stop listening to light sensor updates. This will stop the sensor and conserve battery.

Since: 0.0.1

addListener('lightSensorChange', ...)

addListener(eventName: 'lightSensorChange', listenerFunc: LightSensorCallback) => Promise<PluginListenerHandle>

Add a listener for light sensor change events. The listener will be called whenever new sensor data is available.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------ | | eventName | 'lightSensorChange' | - Must be 'lightSensorChange' | | listenerFunc | LightSensorCallback | - Callback function to receive sensor data |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for light sensor events.

Since: 0.0.1

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the current permission status for high sampling rate sensors. On Android 12+, the HIGH_SAMPLING_RATE_SENSORS permission is required for sensor update intervals below 200ms.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission for high sampling rate sensors. On Android 12+, this requests the HIGH_SAMPLING_RATE_SENSORS permission.

Returns: Promise<PermissionStatus>

Since: 0.0.1

getPluginVersion()

getPluginVersion() => Promise<VersionResult>

Get the current version of the plugin.

Returns: Promise<VersionResult>

Since: 0.0.1

Interfaces

IsAvailableResult

Result indicating whether the sensor is available.

| Prop | Type | Description | Since | | --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ----- | | available | boolean | Whether the light sensor is available on this device. Always false on iOS as the light sensor API is not available. | 0.0.1 |

StartOptions

Options for starting the light sensor listener.

| Prop | Type | Description | Default | Since | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ----- | | updateInterval | number | The desired interval between sensor updates in milliseconds. On Android 12+, there's a minimum interval of 200ms unless the app has the HIGH_SAMPLING_RATE_SENSORS permission. | 200 | 0.0.1 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

LightSensorMeasurement

A single light sensor measurement.

| Prop | Type | Description | Since | | ----------------- | ------------------- | ---------------------------------------------------- | ----- | | illuminance | number | Ambient light level in lux (lx). | 0.0.1 | | timestamp | number | Timestamp of the measurement in seconds since epoch. | 0.0.1 |

PermissionStatus

Result of a permission request or check.

| Prop | Type | Description | Since | | ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | highSamplingRate | 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' | Whether the high sampling rate sensor permission is granted. On Android 12+, this permission is required for update intervals below 200ms. | 0.0.1 |

VersionResult

Plugin version information.

| Prop | Type | Description | Since | | ------------- | ------------------- | ---------------------------------- | ----- | | version | string | The current version of the plugin. | 0.0.1 |

Type Aliases

LightSensorCallback

Callback function for light sensor updates.

(measurement: LightSensorMeasurement): void

Contributing

See CONTRIBUTING.md for details on how to contribute to this plugin.

License

MPL-2.0

Credits

This SDK has been inspired by Expo light sensor.