SesameOS3 Android

日本語 | 简体中文 | English

CANDY HOUSE の Android アプリと Sesame SDK を収録したオープンソースプロジェクトです。現在は co.candyhouse.sesame.ble.os3 を中心に、Sesame OS3 デバイスの BLE 接続、登録、操作、状態同期、ファームウェア更新を提供しています。

SDK の導入

動作環境

Android Studio
JDK 17
Android SDK 36
minSdk 24

1. 依存関係を追加する

同じプロジェクト内のソースコードを使用する場合：

dependencies {
    implementation project(':sesameSdk')
}

JitPack を使用する場合、settings.gradle にリポジトリを追加します。

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

アプリの build.gradle に SDK を追加します。<version> は Releases にある利用したいタグへ置き換えてください。

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

2. 権限を設定する

アプリの AndroidManifest.xml に必要な権限を追加し、BLE スキャン前に位置情報および Bluetooth の実行時権限を取得してください。

<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. CANDY HOUSE サービスを初期化する

Sesame OS3 の登録やクラウド機能を利用するには、アプリ起動時に以下を初期化します。

Amplify に AWSCognitoAuthPlugin と AWSApiPlugin を登録し、Cognito / API の設定で Amplify.configure(...) を実行する。
DeviceData.initialize(applicationContext) を実行する。
CHBleManager(applicationContext) を実行する。

実装例は Demo App の AWSStatus.kt と BaseApp.kt を参照してください。

override fun onCreate() {
    super.onCreate()

    // Amplify の Auth / API 設定後に初期化する
    DeviceData.initialize(applicationContext)
    CHBleManager(applicationContext)
}

公開 Demo 用の CANDY HOUSE サービス設定は評価用途であり、リクエスト数などに制限がある場合があります。本番環境では、自分の Firebase / AWS / Google Maps 設定を使用し、認証情報をリポジトリへコミットしないでください。

Demo App を実行する場合は、次のローカル設定も必要です。

app.properties：CANDY HOUSE API、AWS Cognito / IoT、Google Maps の設定
app/google-services.json：Firebase の設定

4. デバイスを検出して登録する

権限取得後にスキャンを開始し、未登録デバイスを受け取ります。接続後、状態が ReadyToRegister になった時点で register を実行してください。

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 { /* 登録成功 */ }
                        result.onFailure { /* 登録失敗 */ }
                    }
                }
            }
        }

        device.connect { }
    }
}

CHBleManager.enableScan { result ->
    result.onFailure { /* 権限または Bluetooth の状態を確認 */ }
}

プロジェクト構成

モジュール	内容
`app`	デバイス、アカウント、フレンドなどを含む Android Demo App
`sesameSdk`	BLE、OS3 デバイス実装、ホストサービスのインターフェース（DB と AWS は app/data）
`sesameSdk/.../ble`	公開デバイス API、製品モデル、デバイス管理
`sesameSdk/.../ble/os3`	現在メンテナンスしている OS3 プロトコルとデバイス実装

OS3 デバイス構成

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]

対応製品

対応範囲は CHProductModel を基準とし、実際の Device 実装ごとに分類しています。

Device 実装	製品
`CHSesame5Device`	Sesame 5、Sesame 5 Pro、Sesame 5 US、Sesame 6、Sesame 6 Pro、Sesame 6 Pro SlidingDoor、Sesame miwa、BLE Connector 1
`CHSesameBike2Device`	Sesame Bike 2
`CHSesameBike3Device`	Sesame Bike 3（指紋機能を組み合わせ）
`CHSesameBot2Device`	Sesame Bot 2、Sesame Bot 3
`CHSesameBiometricDeviceImpl`	Open Sensor 1/2、Remote、Remote Nano、Sesame Touch 1/1 Pro/2/2 Pro、Sesame Face 1/1 Pro/1 AI/1 Pro AI/2/2 Pro/2 AI/2 Pro AI
`CHHub3Device`	Hub 3、Hub 3 Pro

メンテナンス終了：Sesame 3（SS2）、WiFi Module 2（WM2）、Sesame Bot 1、Sesame Bike 1、Sesame 4（SS4）。

生体認証機能

CHSesameBiometricDeviceImpl は製品 Profile に応じて機能を組み合わせます。

製品シリーズ	機能
Touch	カード、指紋
Touch Pro	カード、指紋、暗証番号
Face	カード、指紋、手のひら、顔認証
Face Pro	カード、指紋、暗証番号、手のひら、顔認証
Face AI	手のひら、顔認証
Face Pro AI	暗証番号、手のひら、顔認証

関連 API：CHCardCapable、CHPassCodeCapable、CHFingerPrintCapable、CHPalmCapable、CHFaceCapable、CHRemoteNanoCapable。

ビルド

./gradlew :app:assembleDebug

メンテナンス方針

新製品は CHProductModel に追加し、対応する OS3 Device 実装へマッピングします。
共通処理は基底クラスへ集約し、製品差分は個別実装または Capability の組み合わせで対応します。
co.candyhouse.sesame.ble.os2 は互換性維持のための旧コードであり、現在のメンテナンス対象外です。

H5 ブランチの構成は Android アーキテクチャを参照してください。SDK 単独利用時は BLE 起動前に CHBleSupport へ CHBleHost、CHKeyPersistence、ゲートウェイのテナント識別子を設定します。上記 JitPack 座標は既存リリース用で、このブランチは未公開です。

penguin/SesameSDK_Android_with_DemoApp

README.md