SesameOS3 Android

日本語 | 简体中文 | English

Android Web App のホストと独立した Sesame BLE SDK です。画面・アカウント・クラウド業務は Biz3、WebView・Bluetooth・OS 機能は Android が担当します。

Biz は業務ロジック、Android はネイティブ機能、Bridge は通信を担当します。

flowchart LR
  Biz[Biz3 React UI / Business] <-->|MessagePort| App[sesameApp Android]
  App --> SDK[sesameSdk BLE]
  SDK <--> Device[SESAME]
  App --> DB[(Room keys)]
  Biz <-->|WebSocket| AWS[Cloud services]

Loading

公開 SDK の導入

sesameSdk を Android アプリに組み込むことで、BLE スキャン・接続・登録・デバイス操作・状態通知を利用できます。Biz や Web App の導入は不要です。画面、アカウント、バックエンド、保存方式は導入側で選択します。

ソースのビルドには Android Studio とリポジトリの Gradle wrapper を使用します。gradle/gradle-daemon-jvm.properties は Gradle daemon に JDK 21 を指定し、両モジュールの Java ソースとバイトコードの互換レベルは 17 です。compileSdk は 36、アプリの targetSdk は 36、minSdk は 24 です。

1. 依存関係の追加

dependencies {
    implementation(project(":sesameSdk"))
}

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

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

続いてアプリの build.gradle.kts に SDK の依存関係を追加します。

dependencies {
    implementation("com.github.CANDY-HOUSE.SesameSDK_Android_with_DemoApp:sesameSdk:<version>")
}

<version> を使用するリリースタグに置き換えてください。バージョンとモジュール座標は JitPack ページ の公開成果物を参照してください。タグ一覧は Releases にあります。

2. 権限

SDK の Manifest に Bluetooth 権限を宣言しています。現在の CHBleManager.enableScan は対応するすべての Android バージョンで ACCESS_FINE_LOCATION を確認するため、ホスト側で宣言・取得してください。Android 12（API 31）以降は BLUETOOTH_SCAN と BLUETOOTH_CONNECT も必要です。これは現在の SDK 実装の要件であり、位置情報権限は旧 Android だけの要件ではありません。権限取得と Bluetooth 有効化の後にスキャンを開始します。

3. 初期化

Application で CHBleSupport と CHBleManager を初期化します。backend は登録・制限付き鍵の署名・デバイス情報通知を提供する CHBleHost、keyStore は鍵の保存と削除を担当する CHKeyPersistence の実装です。gatewayTenantId はゲートウェイ用のテナント識別子です。SDK はバックエンドの提供元、通信方式、DB を指定しません。インターフェースは CHBleSupport.kt を参照してください。

CHBleSupport.initialize(backend, keyStore, gatewayTenantId)
CHBleManager(applicationContext)

4. スキャン・接続・登録

検出コールバックで未登録デバイスを表示します。ユーザーが選んだデバイスに接続し、ReadyToRegister になってから登録します。生成された鍵は CHKeyPersistence で保存します。

import co.candyhouse.sesame.ble.*

CHBleManager.delegate = object : CHBleManagerDelegate {
    override fun didDiscoverUnRegisteredCHDevices(devices: List<CHDevices>) {
        // Display discovered devices for the user to select.
    }
}
CHBleManager.enableScan { result ->
    result.onFailure { /* Handle permission or Bluetooth errors. */ }
}

fun registerDevice(device: CHDevices) {
    var registering = false
    device.delegate = object : CHDeviceStatusDelegate {
        override fun onBleDeviceStatusChanged(device: CHDevices, status: CHDeviceStatus) {
            if (status == CHDeviceStatus.ReadyToRegister && !registering) {
                registering = true
                device.register { result ->
                    result.onSuccess { /* Registration completed. */ }
                    result.onFailure { /* Handle registration failure. */ }
                }
            }
        }
    }
    device.connect { result ->
        result.onFailure { /* Handle connection failure. */ }
    }
}

5. 鍵の復元と BLE 操作

独自ストレージから CHDevice（下記の savedKey）を読み、restoreDevice で復元します。接続・機械状態の通知を受ける CHDeviceStatusDelegate（下記の statusDelegate）を設定してください。スキャンを継続し、BLE 認証完了後に操作コマンドを送信します。

val device = CHBleManager.restoreDevice(savedKey)
device?.delegate = statusDelegate
device?.connect { result ->
    result.onFailure { /* Handle connection failure. */ }
}

// After BLE authentication completes, for a CHSesame5-compatible device:
(device as? co.candyhouse.sesame.ble.os3.sesame5.CHSesame5)?.toggle { result ->
    result.onFailure { /* Handle command failure. */ }
}

機種に対応するインターフェースを使用します。対応する鍵は CHSesame5、その他は Bike・Bot・Biometric・Hub の各インターフェースを利用します。完全な鍵ではオフライン BLE 操作が可能です。制限付き鍵の認証には署名サービスが必要です。スキャン不要時は CHBleManager.disableScan を呼び出します。

プロジェクト構成

モジュール / パス	役割
sesameApp	Android アプリ：WebView ホスト、BLE ブリッジ、OS 機能
sesameSdk	独立 BLE SDK：スキャン・接続・登録・操作・状態通知
sesameSdk/src/main/java/co/candyhouse/sesame/ble	公開デバイスインターフェース、製品モデル、BLE 管理
sesameSdk/src/main/java/co/candyhouse/sesame/ble/os3	Sesame OS3 プロトコルとデバイス実装
sesameApp/src/main/java/co/candyhouse/app/data	アプリ側の鍵永続化
app.properties	アプリ共通設定と Web App 環境 URL

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]

Loading

対応製品

対応範囲は 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/3
CHHub3Device	Hub 3、Hub 3 Pro

メンテナンス終了：Sesame 3（SS2）、WiFi Module 2（WM2）、Sesame Bot 1、Sesame Bike 1、Sesame 4（SS4）。これらの旧モデルは CHProductModel と各実装に残っています。上記の OS3 製品表には含めていません。

生体認証機能

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

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

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

内部開発

プロジェクト共通設定は app.properties に保持し、ルートの build.gradle.kts で読み込み、プライベートリポジトリで管理します。local.properties は sdk.dir など開発者のローカル設定専用とし、Git にコミットしません。Firebase 設定は sesameApp/google-services.json です。

aws.cognito.identityPoolId=<YOUR_IDENTITY_POOL_ID>
aws.cognito.userPoolId=<YOUR_USER_POOL_ID>
aws.cognito.appClientId=<YOUR_APP_CLIENT_ID>
candyhouse.sesame.web.dev=http://localhost:3000
candyhouse.sesame.web.prod=https://biz.candyhouse.co

Debug のページ URL は candyhouse.sesame.web.dev、Release/CI は candyhouse.sesame.web.prod で指定します。Android のブランチ名とは独立して、Biz のステージング環境または本番環境を選択できます。Biz のステージングブランチは個別に配信でき、本番 URL は https://biz.candyhouse.co です。APP のページ URL を変更した場合は Android を再ビルドします。

現在の app.properties の Release/CI URL は、本番ではなくステージングを指しています。

Web APP ルートから、それぞれ別のターミナルで実行します。Biz の開発サーバーは起動したままにします。

# Terminal 1: Biz3
cd Biz3
nvm use
yarn install --frozen-lockfile
yarn dev

# Terminal 2: Android
cd SesameOS3_Android
adb reverse tcp:3000 tcp:3000
./gradlew :sesameApp:assembleDebug

役割分担

Biz は業務ルール・状態管理・画面操作・クラウド要求を実装します。Android は WebView・BLE・権限・永続化・OS 機能を提供します。Bridge は信頼元の検証と要求・応答・イベントの通信を担当し、業務ロジックを持ちません。

flowchart TB
  Activity[SesameActivity lifecycle] --> Bridge[WebViewBridge trusted origin]
  Activity --> Media[WebMediaAccess camera / file chooser]
  Bridge --> Handler[NativeRequestHandler]
  Handler --> BLE[BleController / Registration]
  Handler --> Platform[NFC / Push / AutoUnlock / Firmware]
  BLE --> Backend[BleBackend]
  Backend --> Biz[Biz WebSocket runtime]

Loading

Amplify Auth は旧ログインの引き継ぎ、core-kotlin は現在の suspend API 用です。Amplify API プラグインはありません。バックグラウンド WebView も Biz のクラウド接続を利用し、NFC・通知・自動解錠・ファームウェア転送は各ネイティブ機能が担当します。ヘッダー・メニュー・QR スキャン画面・内部テストは Biz が描画し、Android はカメラと写真選択の権限のみを提供します。

起動とオフライン

flowchart LR
  Start[Cold start] --> Page{Network HTML available?}
  Page -->|Yes| Online[Latest Biz page]
  Page -->|No| Cache[Previously cached page]
  Online --> Local[Local device list / BLE]
  Cache --> Local
  Local -->|Cloud ready| Cloud[Updated device list]

Loading

APK に Biz の画面資源を同梱しません。Service Worker は HTML をネットワーク優先で取得し、必要な資源のキャッシュ成功後にオフライン入口を保存します。初回インストール・ドメイン変更・WebView データ削除後は一度オンラインで起動してください。OS によるキャッシュ削除があるため、未接続の初回起動は保証しません。

オフライン一覧はローカル DB から取得し、Cognito・WebSocket を待ちません。offlineDevices は名前・モデル・UUID・権限レベルのみを返し、鍵は返しません。オンラインの登録、鍵の同期・共有、制限付き鍵の署名では、必要な鍵情報が信頼された Bridge を通過します。オフライン一覧の制限は、すべての鍵が Biz を通らないことを意味しません。完全なオンライン一覧で表示範囲を更新し、ログアウトしたアカウントの再表示を防ぎます。未同期鍵は保持します。制限付き鍵の署名、クラウド操作、登録、ファームウェア取得には通信が必要です。

鍵はネイティブの Room（word_database）に保存し、WebView ストレージ（IndexedDB など）には置きません。BLE はネイティブが実行するため、鍵をネイティブに置くことで Bridge 経由の受け渡しを減らせます。WebView ストレージは同一オリジンの JS から読み取れ、WebView データの消去やシステムによる回収で失われる可能性があります。

同じ applicationId・互換署名・許可される versionCode による上書き更新では、データを消去しなければ DB と設定を引き継ぎます。LegacySession が旧ログインを、KeyHandoff がゲスト鍵の同期を担当します。