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

`MoveTo(ctx, position)` experimentally sends OS3 item 84 with a signed
16-bit little-endian absolute angle. The SDK defines this item but does not
expose it for Sesame 5/6, so its payload and firmware behavior still require
hardware validation. The calibration popup exposes it as **Set position**.
It preserves saved endpoints, returns firmware rejection codes, and does not
claim movement until live status reports it. -32768 is reserved for no target;
accepted input is -32767 through 32767. Commands are not replayed on reconnect.

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.