# 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.

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.