PulseKit

Continuous, multi-day periodic background data-collection engine with pluggable sensors, per-source permission metadata, batched bounded persistence, transformable event pipeline, and inversion-of-control sync/export/test tooling.

#test
#storage
#sqldelight
#sdk
#kotlin-flow
#kotlin-coroutines
#device
#compose
#background-synchronization
#android-ui

Suggest an edit

Android JVMKotlin/Native

GitHub stars1

AuthorsAlirezaJavan

Dependents0

LicenseApache License 2.0

Creation date26 days ago

Last activity2 days ago

Latest release0.6.0 (2 days ago)

GitHub repository Wiki page

PulseKit

A Kotlin Multiplatform (Android + iOS) engine for continuous or periodic, multi-day background data collection from any pluggable DataSource — location, motion, step count, and BLE scanning ship out of the box. Collected events get batched local persistence and a pluggable sync engine.

Screenshots

The demo app (app/) showcases every feature area behind bottom navigation:

_Home

_Sensors

_Bluetooth

_Sync

_Settings

Project Structure

pulsekit-core: Tracking engine, SQLDelight persistence, and PermissionController abstraction. Includes a pluggable export infrastructure (DataExporter, CsvFormatter, NdjsonFormatter).
pulsekit-location: GPS/network location DataSource with GPX and field-based exporters.
pulsekit-motion: Accelerometer and step-counter DataSource with field-based exporters.
pulsekit-bluetooth: BLE scan DataSource with field-based exporter.
pulsekit-device: Battery and device status DataSource (Level, Charging, Thermal).
pulsekit-environment: Barometer, Light, Temperature, Humidity, and Altitude DataSource.
pulsekit-sync: Network sync engine with retry/backoff logic.
pulsekit-ui: Android Services, Receivers, and Compose PermissionGate.
pulsekit-geofence: Region monitoring over the location stream.
pulsekit-testing: Test artifact with FakeDataSource and MutableTimeProvider.

Installation

dependencies {
    val version = "0.6.0"
    implementation("io.github.alirezajavan:pulsekit-core:$version")
    implementation("io.github.alirezajavan:pulsekit-location:$version")
    implementation("io.github.alirezajavan:pulsekit-motion:$version")
    implementation("io.github.alirezajavan:pulsekit-bluetooth:$version")
    implementation("io.github.alirezajavan:pulsekit-device:$version")
    implementation("io.github.alirezajavan:pulsekit-environment:$version")
    implementation("io.github.alirezajavan:pulsekit-sync:$version")
    implementation("io.github.alirezajavan:pulsekit-ui:$version") // optional
    implementation("io.github.alirezajavan:pulsekit-geofence:$version") // optional
    testImplementation("io.github.alirezajavan:pulsekit-testing:$version") // optional
}

Usage

1. Build a `PulseKit` instance

val database = createPulseKitDatabase(applicationContext)

val pulseKit = PulseKit.builder(database)
    .addDataSource(LocationDataSource(applicationContext))
    .addDataSource(MotionDataSource(applicationContext))
    .addDataSource(BatteryDataSource(applicationContext))
    .addDataSource(BarometerDataSource(applicationContext))
    .addDataSource(EnvironmentDataSource(applicationContext, sensorTypeId = SensorType.LIGHT))
    .addDataSource(
        BluetoothDataSource(applicationContext),
        mode = CollectionMode.Periodic(intervalMillis = 5.minutes.inWholeMilliseconds,
                                       windowMillis = 30.seconds.inWholeMilliseconds),
    )
    .addEventProcessor(LocationPrecisionProcessor(decimalPlaces = 3))
    .build()

2. Manage Android Foreground Service

Extend BasePulseKitService and use the provided extension functions to start/stop:

// To start:
context.startPulseKitCollection<MyTrackingService>(sourceIds = setOf(LocationDataSource.ID))

// To stop:
context.stopPulseKitCollection<MyTrackingService>()

3. Request Permissions

PermissionController handles the OS-mandated staged ordering. In Compose:

val permissions = rememberDataSourcePermissionState(controller, source)
Button(onClick = {
    permissions.request { canCollect -> if (canCollect) onStart() }
}) { Text("Collect ${source.displayName}") }

4. Sync and Export Data

// Sync to backend
val syncEngine = SyncEngine(pulseKit.syncSource, MyBackendUploader())
syncEngine.start(applicationScope)

// Query and Export
val events = pulseKit.queryEvents(EventQuery(limit = 100)).asFlow()

// Use a specific data source's exporter
val locationSource = pulseKit.dataSources.find { it.id == LocationDataSource.ID }
val exporter = locationSource?.exporter!!

// Export to GPX
(exporter as LocationExporter).exportToGpx(events, output)

// Export to CSV with custom columns
val csv = CsvFormatter(exporter, columns = listOf("latitude", "longitude", "speed"))
csv.format(events, output)

Platform Setup

Android (Zero-Manifest Policy)

Explicitly declare permissions and components in your AndroidManifest.xml:

FOREGROUND_SERVICE, WAKE_LOCK, RECEIVE_BOOT_COMPLETED.
Data source permissions (e.g., ACCESS_FINE_LOCATION).
Your BasePulseKitService and PulseKitBootReceiver subclasses.

Use pulseKit.validateAndroidSetup(...) at startup to verify your manifest.

iOS

Add NSLocationAlwaysAndWhenInUseUsageDescription, NSMotionUsageDescription, and location to UIBackgroundModes. Use IosPulseKitHost to keep the process alive.

Supported Data Sources by Platform

Source	Android	iOS	Notes
Location	✅	✅	iOS requires `UIBackgroundModes`
Motion	✅	✅
Steps	✅	✅
Bluetooth	✅	✅	iOS background scanning is limited
Battery	✅	✅
Barometer	✅	✅	iOS uses `CMAltimeter`
Environment	✅	❌	Light, Temp, Humidity (Android only)
Rel. Altitude	❌	✅	iOS only (`CMAltimeter`)

Contributing

See CLAUDE.md for conventions and REFACTOR_PLAN.md for the roadmap.

License

Apache License 2.0.

Android JVMKotlin/Native

GitHub stars1

AuthorsAlirezaJavan

Dependents0

LicenseApache License 2.0

Creation date26 days ago

Last activity2 days ago

Latest release0.6.0 (2 days ago)

GitHub repository Wiki page

PulseKit

Screenshots

The demo app (app/) showcases every feature area behind bottom navigation:

_Home

_Sensors

_Bluetooth

_Sync

_Settings

Project Structure

pulsekit-core: Tracking engine, SQLDelight persistence, and PermissionController abstraction. Includes a pluggable export infrastructure (DataExporter, CsvFormatter, NdjsonFormatter).
pulsekit-location: GPS/network location DataSource with GPX and field-based exporters.
pulsekit-motion: Accelerometer and step-counter DataSource with field-based exporters.
pulsekit-bluetooth: BLE scan DataSource with field-based exporter.
pulsekit-device: Battery and device status DataSource (Level, Charging, Thermal).
pulsekit-environment: Barometer, Light, Temperature, Humidity, and Altitude DataSource.
pulsekit-sync: Network sync engine with retry/backoff logic.
pulsekit-ui: Android Services, Receivers, and Compose PermissionGate.
pulsekit-geofence: Region monitoring over the location stream.
pulsekit-testing: Test artifact with FakeDataSource and MutableTimeProvider.

Installation

dependencies {
    val version = "0.6.0"
    implementation("io.github.alirezajavan:pulsekit-core:$version")
    implementation("io.github.alirezajavan:pulsekit-location:$version")
    implementation("io.github.alirezajavan:pulsekit-motion:$version")
    implementation("io.github.alirezajavan:pulsekit-bluetooth:$version")
    implementation("io.github.alirezajavan:pulsekit-device:$version")
    implementation("io.github.alirezajavan:pulsekit-environment:$version")
    implementation("io.github.alirezajavan:pulsekit-sync:$version")
    implementation("io.github.alirezajavan:pulsekit-ui:$version") // optional
    implementation("io.github.alirezajavan:pulsekit-geofence:$version") // optional
    testImplementation("io.github.alirezajavan:pulsekit-testing:$version") // optional
}

Usage

1. Build a `PulseKit` instance

val database = createPulseKitDatabase(applicationContext)

val pulseKit = PulseKit.builder(database)
    .addDataSource(LocationDataSource(applicationContext))
    .addDataSource(MotionDataSource(applicationContext))
    .addDataSource(BatteryDataSource(applicationContext))
    .addDataSource(BarometerDataSource(applicationContext))
    .addDataSource(EnvironmentDataSource(applicationContext, sensorTypeId = SensorType.LIGHT))
    .addDataSource(
        BluetoothDataSource(applicationContext),
        mode = CollectionMode.Periodic(intervalMillis = 5.minutes.inWholeMilliseconds,
                                       windowMillis = 30.seconds.inWholeMilliseconds),
    )
    .addEventProcessor(LocationPrecisionProcessor(decimalPlaces = 3))
    .build()

2. Manage Android Foreground Service

Extend BasePulseKitService and use the provided extension functions to start/stop:

// To start:
context.startPulseKitCollection<MyTrackingService>(sourceIds = setOf(LocationDataSource.ID))

// To stop:
context.stopPulseKitCollection<MyTrackingService>()

3. Request Permissions

PermissionController handles the OS-mandated staged ordering. In Compose:

val permissions = rememberDataSourcePermissionState(controller, source)
Button(onClick = {
    permissions.request { canCollect -> if (canCollect) onStart() }
}) { Text("Collect ${source.displayName}") }

4. Sync and Export Data

// Sync to backend
val syncEngine = SyncEngine(pulseKit.syncSource, MyBackendUploader())
syncEngine.start(applicationScope)

// Query and Export
val events = pulseKit.queryEvents(EventQuery(limit = 100)).asFlow()

// Use a specific data source's exporter
val locationSource = pulseKit.dataSources.find { it.id == LocationDataSource.ID }
val exporter = locationSource?.exporter!!

// Export to GPX
(exporter as LocationExporter).exportToGpx(events, output)

// Export to CSV with custom columns
val csv = CsvFormatter(exporter, columns = listOf("latitude", "longitude", "speed"))
csv.format(events, output)

Platform Setup

Android (Zero-Manifest Policy)

Explicitly declare permissions and components in your AndroidManifest.xml:

FOREGROUND_SERVICE, WAKE_LOCK, RECEIVE_BOOT_COMPLETED.
Data source permissions (e.g., ACCESS_FINE_LOCATION).
Your BasePulseKitService and PulseKitBootReceiver subclasses.

Use pulseKit.validateAndroidSetup(...) at startup to verify your manifest.

iOS

Add NSLocationAlwaysAndWhenInUseUsageDescription, NSMotionUsageDescription, and location to UIBackgroundModes. Use IosPulseKitHost to keep the process alive.

Supported Data Sources by Platform

Source	Android	iOS	Notes
Location	✅	✅	iOS requires `UIBackgroundModes`
Motion	✅	✅
Steps	✅	✅
Bluetooth	✅	✅	iOS background scanning is limited
Battery	✅	✅
Barometer	✅	✅	iOS uses `CMAltimeter`
Environment	✅	❌	Light, Temp, Humidity (Android only)
Rel. Altitude	❌	✅	iOS only (`CMAltimeter`)

Contributing

See CLAUDE.md for conventions and REFACTOR_PLAN.md for the roadmap.

License

Apache License 2.0.

PulseKit

PulseKit

Screenshots

Project Structure

Installation

Usage

1. Build a PulseKit instance

2. Manage Android Foreground Service

3. Request Permissions

4. Sync and Export Data

Platform Setup

Android (Zero-Manifest Policy)

iOS

Supported Data Sources by Platform

Contributing

License

PulseKit

Screenshots

Project Structure

Installation

Usage

1. Build a PulseKit instance

2. Manage Android Foreground Service

3. Request Permissions

4. Sync and Export Data

Platform Setup

Android (Zero-Manifest Policy)

iOS

Supported Data Sources by Platform

Contributing

License

1. Build a `PulseKit` instance

1. Build a `PulseKit` instance