Getting Started

This article will describe the main structure of SDK, how to include and use it in your project. For more information and usage examples please refer to sample app source code.

Structure of Android SDK

Corsano SDK consists of the following modules:

• ble – connecting to a Corsano bracelet over Bluetooth Low Energy (BLE) and performing remote commands. It can be used for getting raw data.
• data – retrieving, storing and processing health data obtained from the Corsano bracelet.
• dfu – performing device firmware upgrades.
• ui – a ready-made Wearing Optimization screen you can drop into your app. Optional.

core is pulled in automatically as a dependency of the modules above; you do not declare it yourself.

There could be other modules in the future. Stay tuned for the updates.

Note: If you'd like to work with lower level commands, then ble module will be enough, but you may also want to use data, which will provide summaries and persistent storage.

See the Change Log for the release history.

Installing SDK to your project

Requirements:

	Requirement
Android API	21 (Android 5.0) or above — API 23 (Android 6.0) if you use the ui module
Java / JVM target	17 (the ble module targets 11)

To include a release version to you project just add whatever modules you need in build.gradle's dependencies section:

dependencies {
    def corsanoSdkVersion = "1.3.1"

    // this is a minimum requirement
    implementation "com.corsano.sdk:ble:$corsanoSdkVersion"

    // data storage and processing
    implementation "com.corsano.sdk:data:$corsanoSdkVersion"

    // device firmware update module
    implementation "com.corsano.sdk:dfu:$corsanoSdkVersion"

    // ready-made Wearing Optimization UI (requires minSdk 23)
    implementation "com.corsano.sdk:ui:$corsanoSdkVersion"
}

For build.gradle.kts use the following snippet:

dependencies {
    val corsanoSdkVersion = "1.3.1"

    // this is a minimum requirement
    implementation("com.corsano.sdk:ble:$corsanoSdkVersion")

    // data storage and processing
    implementation("com.corsano.sdk:data:$corsanoSdkVersion")

    // device firmware update module
    implementation("com.corsano.sdk:dfu:$corsanoSdkVersion")

    // ready-made Wearing Optimization UI (requires minSdk 23)
    implementation("com.corsano.sdk:ui:$corsanoSdkVersion")
}

Note: You can add any of the modules or all of them to your project.

Initializing SDK

Initialization of all SDK modules is performed through this sample code. Put this to you Application onCreate() method:

val dfuConfig = CorsanoDfu.Config(notificationTarget = MainActivity::class.java)

        val dataConfig = DataSdk.Config(
            slotsIntervalSecs = 10 * 60,
            ppg2ThresholdFileSize = 500 * 1024,
            bioZThresholdFileSize = 30 * 1024,
            accThresholdFileSize = 30 * 1024,
            licenceKey = "my_key" // update your licence key here, if you need a key, see https://corsano.com/contact-us/
        ) // Add data config here if needed

        val config = CorsanoSdkConfig.Builder()
            .logger(SdkLogger.LogCat(Log.DEBUG))
            .addModuleConfig(dfuConfig)
            .addModuleConfig(dataConfig)
            .build()

        CorsanoSdk.initialize(this, config)

Licence Key

The licence key is mandatory to use the Corsano SDK, please contact your Corsano account manager or use our contact page if you do not have one. The licence key will be valid for the duration of the subscription.

How the key is validated

Validation happens in two stages, and they fail in different ways.

1. The key must be present. If licenceKey is null, CorsanoSdk.initialize() throws IllegalArgumentException immediately, on the calling thread. This one you can catch.

2. The key is then checked against the Corsano backend. Initialization does not wait for this. The SDK calls the licence service in the background and, if the key is rejected, throws IllegalArgumentException from that background coroutine.

Warning: Because the backend check runs asynchronously, a rejected key surfaces after initialize() has already returned, and a try/catch around initialize() will not catch it. Treat it as a crash you need to avoid in production rather than an error you can recover from — verify the key during development, and make sure it is valid before shipping.

The rejection reasons are:

Status	Meaning
VALID	The key is accepted; the subscription window is stored locally.
UNKNOWN	The key is not recognised by the licence service.
EXPIRED	The subscription window has passed. The error reports the subscription start and end dates.
PHONE_DATE_ERROR	The phone's clock has been set manually and cannot be trusted for an expiry check.

If the device is offline the check cannot complete and initialization proceeds — so a bad key may go unnoticed until the app next runs with connectivity.

Your licence also determines which raw data types you are entitled to: accelerometer, PPG (green), ECG, PPG2, BioZ and raw temperature. If a raw stream you expect is missing, check your subscription before debugging the bracelet.

Other parameters

More on Data configuration here

DFU configuration

You can also provide specific parameters for any particular module. In the example below, we are setting notificationTarget for the DFU module.

val dfuConfig = CorsanoDfu.Config(
                                notificationTarget = MainActivity::class.java
)
val config = CorsanoSdkConfig.Builder()
        .addModuleConfig(dfuConfig)
        .build()
CorsanoSdk.initialize(context, config)

Logger configuration

You can set schedulers and logger instance to be used in all SDK modules by supplying your own config:

val config = CorsanoSdkConfig.Builder()
        .commandScheduler(Scheduler.newThread("ble-handler"))
        .callbackScheduler(Scheduler.MAIN)
        .logger(SdkLogger.LogCat(level = Log.INFO))
        .build()
CorsanoSdk.initialize(context, config)