Facilitates sensor data acquisition and management by supporting accelerometer, gyroscope, magnetometer, barometer, step counter, and location sensors, with built-in permission handling capabilities.
KSensor is a Kotlin Multiplatform library for observing device sensors and system states. Each sensor or state is grouped into its own plugin, allowing you to include only the features you need. This prevents pulling in unnecessary code and permissions.
All data emitted by plugins is wrapped in a KSensorResponse<T> which includes:
data: The actual sensor or state data.platform: The platform type (Android or iOS).timestamp: The system time when the data was collected.Some plugins require system permissions to function. Each plugin exposes a requiredPermissions list indicating what it needs. KSensor provides a PermissionHandler interface in the Core module to help check and request these permissions across platforms.
KSensor {
startOnBoot:
}
[!IMPORTANT] : To use "Start on Boot", you must register your plugins and call in your class. While the library handles the system boot broadcast automatically, calling in your application class ensures that observations are resumed whenever the app process is created.
You must ensure that the necessary permissions are granted before starting sensor observations. Each plugin section below lists its required permissions.
For Android, you must add the permissions to the Manifest file manually.
The foundation of the library. It is required for all plugins.
Dependency:
implementation("io.github.shadadman:ksensor-core:version")
These plugins provide access to hardware sensors for monitoring movement, environment, and health.
Provides access to hardware sensors for tracking movement.
Dependency:
implementation("io.github.shadadman:ksensor-sensors-motion:version")
Required Permissions:
ACTIVITY_RECOGNITION (Required for Step Counter)ACTIVITY_RECOGNITION (Motion & Fitness)Add the following to your AndroidManifest.xml:
android.permission.ACTIVITY_RECOGNITIONAdd the following key to your Info.plist:
NSMotionUsageDescription: Required for Step Counter and movement detection.Data Models (Wrapped in KSensorResponse):
Accelerometer(values: Vector3)Gyroscope(values: Vector3)StepCounter(steps: Int)MotionDetector(type: MotionType) (Detects Walking, Running, Cycling, etc.)Provides data from sensors that monitor the ambient environment.
Dependency:
implementation("io.github.shadadman:ksensor-sensors-environment:version")
Required Permissions: None
Data Models (Wrapped in KSensorResponse):
Barometer(pressure: Float)LightIlluminance(illuminance: Float)Proximity(distanceInCM: Float, isNear: Boolean)Provides location services and spatial orientation data.
Dependency:
implementation("io.github.shadadman:ksensor-sensors-positioning:version")
Required Permissions:
LOCATIONAdd the following to your AndroidManifest.xml:
android.permission.ACCESS_FINE_LOCATIONandroid.permission.ACCESS_COARSE_LOCATIONData Models (Wrapped in KSensorResponse):
Location(latitude: Double?, longitude: Double?, altitude: Double?)Magnetometer(values: Vector3)Orientation(orientation: DeviceOrientation, orientationInt: Int)Heading(magneticHeading: Double, trueHeading: Double, deviceHeading: Double, courseOverGround: Double)LocationStatus(isLocationOn: Boolean)Provides high-level data related to user input gestures.
Dependency:
implementation("io.github.shadadman:ksensor-sensors-interaction:version")
Required Permissions: None
Data Models (Wrapped in KSensorResponse):
TouchGestures(x: Float, y: Float, type: TouchGestureType)Provides access to health related data.
Dependency:
implementation("io.github.shadadman:ksensor-sensors-health:version")
Required Permissions:
BODY_SENSORSCAMERAAdd the following to your AndroidManifest.xml:
android.permission.BODY_SENSORSandroid.permission.CAMERAandroid.permission.health.READ_HEART_RATE (Optional: for Health Connect / API 36+)Add the following keys to your Info.plist:
NSCameraUsageDescription: Required for Camera PPG.NSHealthUpdateUsageDescription & NSHealthShareUsageDescription: Required for HealthKit data.Data Models (Wrapped in KSensorResponse):
HeartRate(heartRate: Float, source: HeartRateSource, confidence: Float, quality: Float)The Health plugin implements a robust fallback strategy for heart rate detection on phones:
What is PPG? PPG is a non-invasive method that uses a light source (the phone's flash) and a photodetector (the phone's camera) to measure the volumetric variations of blood circulation. By analyzing the "redness" of your finger over the camera lens, KSensor can estimate user heart rate with high precision using an advanced digital signal processing pipeline (Butterworth filters and adaptive peak detection).
These plugins provide monitoring for various device system and connectivity states.
Provides information about the network connectivity of the device.
Dependency:
implementation("io.github.shadadman:ksensor-states-network:version")
Required Permissions: None
Data Models (Wrapped in KSensorResponse):
ConnectivityStatus(isConnected: Boolean)CurrentActiveNetwork(activeNetwork: ActiveNetwork) (Values: WIFI, CELLULAR, NONE)Provides access to general device system states like battery and volume.
Dependency:
implementation("io.github.shadadman:ksensor-states-system:version")
Required Permissions: None
Data Models (Wrapped in KSensorResponse):
Provides monitoring for BLE connection and discovery events.
Dependency:
implementation("io.github.shadadman:ksensor-states-bluetooth:version")
Required Permissions:
BLUETOOTHAdd the following to your AndroidManifest.xml:
android.permission.BLUETOOTH_SCAN (API 31+)android.permission.BLUETOOTH_CONNECT (API 31+)android.permission.ACCESS_FINE_LOCATION (Required for discovery on older versions)Data Models (Wrapped in KSensorResponse):
BleConnectionStatus(connectedDevices: List<BleDevice>)BleDiscoversStatus(discoveredDevices: List<BleDevice>)BleDevice(id: String, name: String)Tracks the visibility and lifecycle state of the application.
Dependency:
implementation("io.github.shadadman:ksensor-states-lifecycle:version")
Required Permissions: None
Data Models (Wrapped in KSensorResponse):
AppVisibilityStatus(isAppVisible: Boolean)KSensor registry to retrieve the plugin and observe its data using Kotlin Flow.Example to observe using State:
@Composable
fun OrientationSampleUsingState() {
// Register a plugin
val plugin = remember {
KSensor.get<PositioningPlugin>(PluginId.POSITIONING)
?: createPositioningPlugin().also { KSensor.register(it) }
}
// Use state
val orientation by plugin.orientation().collectAsState(null)
println("OrientationData as state: ${orientation?.data}")
}
Example to observe using Effect:
@Composable
fun OrientationSampleUsingEffect() {
// Register a plugin
val plugin = remember {
KSensor.get<PositioningPlugin>(PluginId.POSITIONING)
?: createPositioningPlugin().also { KSensor.register(it) }
}
// Use effect
LaunchedEffect(plugin) {
plugin.orientation().collect {
println("OrientationData in effect: ${it.data}")
}
}
}
To help AI agents (like Claude, GPT, or IDE assistants) understand and work with KSensor more effectively, we provide a SKILL section. You can inject these documents into your LLM's context to get high-quality code generation and architectural advice specific to KSensor.
SKILL.md and into your LLM's system prompt or context window.Copyright (c) 2026 KSensor
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
KSensor.start()Applicationstart()iOS: iOS does not allow arbitrary code execution on boot. To achieve "Start on Boot" behavior, you must call KSensor.start() in your AppDelegate's didFinishLaunchingWithOptions. If you have background modes enabled (like Location or HealthKit), the system will relaunch your app into the background after a reboot, and calling KSensor.start() will resume observations.
BatteryStatus(levelPercent: Int?, chargingState: ChargingState, health: BatteryHealth?, temperatureC: Float?)VolumeStatus(volumePercentage: Int)LocaleStatus(languageCode: String, countryCode: String, fullLocaleString: String, displayName: String, isRTL: Boolean)ScreenStatus(isScreenOn: Boolean)BrightnessStatus(screenBrightness: Int)LockStatus(isDeviceLocked: Boolean)PowerSaveStatus(isPowerSaveMode: Boolean)StorageStatus(totalBytes: Long, usedBytes: Long, freeBytes: Long)CONTRIBUTING_SKILL.mdSKILL/ folder to provide the agent with deep knowledge of KSensor's plugin system and implementation details.CONTRIBUTING_SKILL.md when you want the LLM to help you write a new custom plugin for a specific sensor or platform state.Surfaced from shared tags and platforms — no rankings paid for.