SesameOS3 Android

日本語 | 简体中文 | English

An open-source project containing the CANDY HOUSE Android app and Sesame SDK. The project currently focuses on co.candyhouse.sesame.ble.os3 and provides BLE connectivity, registration, control, state synchronization, and firmware updates for Sesame OS3 devices.

• CANDY HOUSE official website
• Google Play
• GitHub Releases

Integrating the SDK

Requirements

• Android Studio
• JDK 17
• Android SDK 36
• minSdk 24

1. Add the dependency

To use the source module in the same project:

dependencies {
    implementation project(':sesameSdk')
}

To use JitPack, add the repository to settings.gradle:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Then add the SDK to your app's build.gradle. Replace <version> with the desired tag from Releases.

dependencies {
    implementation 'com.github.CANDY-HOUSE.SesameSDK_Android_with_DemoApp:sesame-sdk:<version>'
}

2. Configure permissions

Add the required permissions to your app's AndroidManifest.xml. Request location and Bluetooth runtime permissions before starting a BLE scan.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.INTERNET" />

<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="false" />

3. Initialize CANDY HOUSE services

To use Sesame OS3 registration and cloud features, complete the following initialization when your application starts:

1. Add AWSCognitoAuthPlugin and AWSApiPlugin to Amplify, then call Amplify.configure(...) with your Cognito and API configuration.
2. Call DeviceData.initialize(applicationContext).
3. Call CHBleManager(applicationContext).

See AWSStatus.kt and BaseApp.kt in the Demo App for complete examples.

override fun onCreate() {
    super.onCreate()

    // Initialize after configuring Amplify Auth and API
    DeviceData.initialize(applicationContext)
    CHBleManager(applicationContext)
}

The public Demo configuration for CANDY HOUSE services is intended for evaluation and may be subject to request or usage limits. For production, use your own Firebase, AWS, and Google Maps configuration, and never commit credentials to the repository.

The Demo App also requires the following local configuration files:

• app.properties: CANDY HOUSE API, AWS Cognito/IoT, and Google Maps configuration
• app/google-services.json: Firebase configuration

4. Discover and register a device

After permissions are granted, start scanning and listen for unregistered devices. Connect to a device and call register when its state becomes ReadyToRegister.

CHBleManager.delegate = object : CHBleManagerDelegate {
    override fun didDiscoverUnRegisteredCHDevices(devices: List<CHDevices>) {
        val device = devices.firstOrNull() ?: return

        device.delegate = object : CHDeviceStatusDelegate {
            override fun onBleDeviceStatusChanged(
                device: CHDevices,
                status: CHDeviceStatus,
                shadowStatus: CHDeviceStatus?
            ) {
                if (status == CHDeviceStatus.ReadyToRegister) {
                    device.register { result ->
                        result.onSuccess { /* Registration succeeded */ }
                        result.onFailure { /* Registration failed */ }
                    }
                }
            }
        }

        device.connect { }
    }
}

CHBleManager.enableScan { result ->
    result.onFailure { /* Check permissions or Bluetooth state */ }
}

Project structure

OS3 device architecture

flowchart TB
    Devices[CHDevices]

    Devices --> Lock[CHSesameLock]
    Lock --> LockBase[CHSesameOS3LockBase]
    LockBase --> S5[CHSesame5Device]
    LockBase --> Bike2[CHSesameBike2Device]
    Bike2 --> Bike3[CHSesameBike3Device<br/>+ Fingerprint capability]
    LockBase --> Bot2[CHSesameBot2Device]

    Devices --> Connector[CHSesameConnector]
    Connector --> Bio[CHSesameBiometricDevice]
    Bio --> BioImpl[CHSesameBiometricDeviceImpl<br/>Capabilities by product profile]

    Devices --> Gateway[CHWifiModule2]
    Gateway --> Hub[CHHub3 / CHHub3Device]

Supported products

The supported product range is defined by CHProductModel and grouped below by the actual Device implementation.

No longer maintained: Sesame 3 (SS2), WiFi Module 2 (WM2), Sesame Bot 1, Sesame Bike 1, and Sesame 4 (SS4).

Biometric capabilities

CHSesameBiometricDeviceImpl assembles capabilities based on each product profile.

Related APIs: CHCardCapable, CHPassCodeCapable, CHFingerPrintCapable, CHPalmCapable, CHFaceCapable, and CHRemoteNanoCapable.

Build

./gradlew :app:assembleDebug

Maintenance policy

• Add new products to CHProductModel and map them to the corresponding OS3 Device implementation.
• Keep shared behavior in base classes; implement product differences through dedicated implementations or Capability composition.
• co.candyhouse.sesame.ble.os2 contains legacy compatibility code and is outside the current maintenance scope.

For this H5 branch, see Android architecture. Standalone SDK hosts must initialize CHBleSupport with CHBleHost, CHKeyPersistence, and the gateway tenant ID before starting BLE. The JitPack coordinates above refer to existing releases; this branch is not published.