# Sesame OS3 driver

This directory contains the Sesame protocol, BlueZ transport and hardware-free
tests. Supported advertised models: Sesame 5, 5 Pro, 6 and 6 Pro. It does not
implement Sesame OS2, Hub/Matter setup, cloud guest-key signing or firmware updates.

The protocol is adapted from the MIT-licensed CANDY HOUSE Android SDK at
`d12f23c25bffd5adf6361abd0db82bb144441875`. See `LICENSE` and the root `NOTICE`.

## Integration

`Discover` scans powered local BlueZ adapters. Devices are matched by their
advertised Sesame UUID and supported product ID, not by a friendly name or fixed
Bluetooth MAC. `Register` enrolls an unregistered device with P-256 ECDH and calls
a persistence callback as soon as the 16-byte credential is available. It never
issues a reset. Registration here provisions BLE access, not a Sesame cloud
account. `Probe` validates an imported local key by logging in without moving
the motor. Cloud-only guest keys are not supported.

`Client.Run` maintains a connection and reconnects after transport or crypto
failure. `Action` serializes operations on that connection and waits for the
lock's result code. Failed/timed-out operations are not replayed after reconnect.
`State` returns the latest immutable snapshot; pointers in snapshots must not be
modified by callers. Each reconnect clears state until new publications arrive. Discovery prefers
advertisements received in the current scan when BlueZ has cached multiple
addresses for one UUID. Scans request LE transport, the FD81 service and duplicate
manufacturer reports, and connection setup requires a report from the current
scan (there is no cached-address fallback). This follows the Android SDK's
ReceivedAdV → connectGatt(TRANSPORT_LE) → service discovery → notifications →
initial-token/login sequence. BlueZ handles the platform-specific GATT setup.
Connect and GATT setup each have an 8-second limit; transient setup failures
close the failed link and rescan, up to three attempts within the 30-second
setup deadline, plus bounded scan/disconnect cleanup. Commands and registration
exchanges are never automatically replayed. Disconnect releases notifications
before closing the device. Connection setup and login have separate deadlines;
errors identify discovery, connection, GATT services, notification subscription
or initial-token/login waits, and connection failures are logged without keys.

Commands: `lock`, `unlock`, `set-lock`, `set-unlock`, `set-boundary`. Calibration
captures the current reported position; saving either endpoint preserves the
other endpoint. Boundary capture is allowed only after firmware has published
its boundary capability. Positions use the SDK's signed 16-bit angle values;
negative values, including -1, are valid.

OS3 framing uses 19 payload bytes per GATT fragment. Local login uses AES-CMAC.
The fixed CCM profile is 13-byte nonce, 4-byte tag, AAD 00; the nonce contains an
8-byte LE counter, zero, and a 4-byte token. Unsupported token lengths fail
explicitly. No keys, authentication data or decrypted packets are logged.

`Link`/`Dialer` separate the session protocol from BlueZ so a future ESP32 GATT
tunnel can reuse this implementation. This release requires the HA/server's
local Bluetooth adapter to reach the lock; it does not use HA Bluetooth proxies
or add an ESP32 central role.

## Validation

Run `go test -race ./...` and `go vet ./...` at repository root. Tests cover RFC
4493 CMAC vectors, independently generated OpenSSL/Python CCM vectors with high
counter bytes, tampering, framing, P-256 registration, commands, calibration,
unsupported boundary settings, cancellation, private storage and HTTP validation.

Still requires real hardware validation: local BLE registration/login, initial
token length and response encryption, notifications during manual movement,
calibration/motor behavior, coexistence with the phone app, and battery impact
of a persistent connection. Unit tests do not establish those device behaviors.


## Connection workflow reference

Transport lifecycle was compared with SDK commit
`61e2a6a` (mirror of `8887141f1b5482451442647ff455313b755a8655`), especially
`CHBleManager.kt`, `CHSesameOS3.kt`, `CHBaseDevice.kt`, and the app's
`BleController.kt`. The SDK also reconnects from newly received advertisements;
its Android callbacks are mapped to BlueZ discovery reports and GATT properties
here. Bounded transport retries are a Go/BlueZ policy, not an SDK timeout value.
The existing local-key login algorithm already matches this SDK.

The private D-Bus test runs a simulated BlueZ service and verifies LE scan
filters, rescan after a failed connection, write-without-response selection,
buffering of an initial token emitted during StartNotify, and StopNotify before
Disconnect. It does not emulate controller radio behavior or establish that
Android and a Linux USB dongle have equivalent connection reliability.