Skip to content

feat(devices): export Experimental 0.4 Devices SDK #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericshang98 merged 1 commit into from
Sep 7, 2026
Merged

feat(devices): export Experimental 0.4 Devices SDK #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions devices/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Do not create language-specific behavior that is absent from the shared contract

## Required local gates

From the repository root:
From this package directory:

```sh
npm run test:reference
Expand All @@ -65,11 +65,11 @@ npm run check:boundary
npm run check:naming
```

`npm run check` is the final aggregate gate. At the 2026-07-27 snapshot it
passes, including Device Info 0.2, the audited exporter, mandatory bonding,
three-second bond reset, and notification fragmentation. Run
Do not weaken or delete these assertions; a source contract and compiler gate still do not
replace the real-board checklist.
`npm run check` is the final aggregate gate. The 2026-07-27 snapshot passed,
including Device Info 0.2, the audited exporter, mandatory bonding,
three-second bond reset, and notification fragmentation. Run it before shipping.
Do not weaken or delete these assertions; a source contract and compiler gate
still do not replace the real-board checklist.

## Hardware claims

Expand Down
47 changes: 47 additions & 0 deletions devices/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,53 @@ This file records changes to public protocol behavior, shared vectors, SDK surfa

## Unreleased

## 0.4.0-experimental.1 — 2026-09-07

Wire major 1 remains compatible. This release publishes the AhaKey X1
production-port boundary and makes Experimental 0.4 the current public SDK
identity.

### Added

- AhaKey X1 production-port boundary for `device-audio/1`: physical-only
microphone start, IMA ADPCM frames, bounded credit queue, fragmentation,
timeout/error wiping, and a data-only tunnel over its existing BLE service.
- AhaKey transport descriptor and injectable host CTests for encryption gates,
stock-command coexistence, device PCM, and flow-control failure paths.

## 0.3.0-experimental.1 — 2026-08-13

Wire major 1 remains compatible. This release adds an independently negotiated
device microphone profile and a data-only compatibility transport.

### Added

- `device-audio/1` control messages, Device Info capability, binary IMA ADPCM
frames, CRC32C, fragmentation, credits, hostile vectors, and JSON Schema.
- Byte-identical JavaScript and fixed-buffer C99 audio codecs.
- Compatibility Tunnel v1 descriptors with a single fixed-opcode envelope,
strict allowlisting, encryption/bonding requirements, and no executable
plugin surface.
- A deterministic hardware-free simulator for physical-key capture, 120-second
limit, bounded RAM, credit stalls, cancellation, and missing-frame policy.

### Changed

- `voice/1` retains its existing meaning: it controls the Host microphone and
never carries audio. `device-audio/1` carries microphone audio sampled by the
physical device itself.
- A Host can prepare, reject, cancel, or terminate a device-audio stream, but
cannot remotely start the device microphone.

### Added

- AhaKey X1 integration kit: a portable C99 codec for the published AhaKey
BLE configuration protocol (`firmware/ahakey-x1/ahakey_proto.*`), the
Nexting mapping adapter for its keys, approval lever, LED strip, and OLED
(`firmware/ahakey-x1/nexting_ahakey_adapter.*`), a Device Info template,
host-side CTest coverage including the published wire captures, and the
end-to-end case document (`docs/cases/ahakey-x1-case.md`).

### Changed

- Reframed the Quickstart around the device–App–Agent architecture and split
Expand Down
20 changes: 10 additions & 10 deletions devices/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,16 @@ Unknown, malformed, unauthorized, stale, duplicate, replaced, or expired input m

## Run evidence appropriate to the change

| Change | Minimum evidence |
| --- | --- |
| Protocol or vectors | JavaScript, Swift, Kotlin, and C sanitizer suites |
| Official App integration | Private Nexting App validation; not part of this public repository |
| Public documentation system | Documentation contract, links, public-boundary, naming, and diff checks |
| C device core | CMake build and CTest with ASan/UBSan |
| BLE simulator | Private integration contract and warnings-as-errors `swiftc` build |
| Reference firmware | Firmware contract plus every affected pinned board build |
| Hardware claim | Complete dated real-iPhone checklist for the exact board and firmware commit |
| Documentation only | Link, public-boundary, naming, and diff checks |
| Change | Minimum evidence |
| --------------------------- | ---------------------------------------------------------------------------- |
| Protocol or vectors | JavaScript, Swift, Kotlin, and C sanitizer suites |
| Official App integration | Private Nexting App validation; not part of this public repository |
| Public documentation system | Documentation contract, links, public-boundary, naming, and diff checks |
| C device core | CMake build and CTest with ASan/UBSan |
| BLE simulator | Private integration contract and warnings-as-errors `swiftc` build |
| Reference firmware | Firmware contract plus every affected pinned board build |
| Hardware claim | Complete dated real-iPhone checklist for the exact board and firmware commit |
| Documentation only | Link, public-boundary, naming, and diff checks |

The exact commands and current known failures live in [`docs/development.md`](docs/development.md). Do not delete, skip, or weaken a failing security assertion to make a branch green.

Expand Down
18 changes: 9 additions & 9 deletions devices/QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,22 @@ side of that contract; it does not provide a kit for building another App.

## What each layer does

| Layer | Responsibility | Does not receive |
| --- | --- | --- |
| Nexting device | Report physical intent and render bounded state | Agent credentials, accounts, session routes |
| Trusted Host | Authorize the device, validate fresh input, and map profiles to Agent actions | Unbounded or unauthenticated device commands |
| Agent integration | Continue the Claude Code, Codex, or compatible Agent session | A direct connection from accessory firmware |
| Layer | Responsibility | Does not receive |
| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------- |
| Nexting device | Report physical intent and render bounded state | Agent credentials, accounts, session routes |
| Trusted Host | Authorize the device, validate fresh input, and map profiles to Agent actions | Unbounded or unauthenticated device commands |
| Agent integration | Continue the Claude Code, Codex, or compatible Agent session | A direct connection from accessory firmware |

This separation lets one public device protocol support a button, wearable,
macropad, desk panel, or custom display without placing private Agent logic in
firmware.

## Choose your path

| Path | Start | First proof |
| --- | --- | --- |
| Use a supported first-party Nexting product | Follow that product's in-App onboarding, connect the Agent, then pair and authorize the product | The same Agent session receives one validated physical action |
| Build with the Nexting SDK | Download the public SDK and run the protocol and firmware checks before adapting hardware | A deterministic profile exchange and a reproducible firmware build |
| Path | Start | First proof |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Use a supported first-party Nexting product | Follow that product's in-App onboarding, connect the Agent, then pair and authorize the product | The same Agent session receives one validated physical action |
| Build with the Nexting SDK | Download the public SDK and run the protocol and firmware checks before adapting hardware | A deterministic profile exchange and a reproducible firmware build |

First-party product onboarding does not authorize third-party or DIY hardware.
If you do not own a supported product, use the SDK path today.
Expand Down
63 changes: 34 additions & 29 deletions devices/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,34 +27,35 @@ The device does not run the Agent session and does not receive Agent credentials

## Choose your path

| You want to… | Start here |
| --- | --- |
| Understand and connect Nexting | [Follow the public Quickstart](QUICKSTART.md) |
| Build the XIAO approval reference | [Build the reference approval controller](docs/reference-approval-controller.md) |
| Get ideas for what to build | [Browse the use cases](docs/use-cases.md) |
| Build and flash a supported board | [Run the first approval](docs/first-approval.md), then use the [reference-board track](docs/implementation-tracks.md#track-1-run-a-reference-board) |
| Understand the device connection contract | [Browse every public interface](docs/interfaces.md) |
| Port a new MCU, RTOS, or chip family | [Build the public foundation](docs/foundation-development.md), then use the [MCU port track](docs/implementation-tracks.md#track-3-port-a-new-mcu-or-rtos) |
| Implement another protocol tool | Use the [protocol-tooling track](docs/implementation-tracks.md#track-3-maintain-protocol-tooling) |
| Make a compatibility claim | [Understand compatibility evidence](docs/conformance.md) |
| Upgrade an Experimental 0.1 integration | [Read the 0.2 migration guide](docs/migration-0.1-to-0.2.md) |

## Experimental 0.2.0-experimental.2

The release keeps wire major 1 and publishes nine independently negotiated
| You want to… | Start here |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Understand and connect Nexting | [Follow the public Quickstart](QUICKSTART.md) |
| Build the XIAO approval reference | [Build the reference approval controller](docs/reference-approval-controller.md) |
| Get ideas for what to build | [Browse the use cases](docs/use-cases.md) |
| Build and flash a supported board | [Run the first approval](docs/first-approval.md), then use the [reference-board track](docs/implementation-tracks.md#track-1-run-a-reference-board) |
| Understand the device connection contract | [Browse every public interface](docs/interfaces.md) |
| Port a new MCU, RTOS, or chip family | [Build the public foundation](docs/foundation-development.md), then use the [MCU port track](docs/implementation-tracks.md#track-3-port-a-new-mcu-or-rtos) |
| Implement another protocol tool | Use the [protocol-tooling track](docs/implementation-tracks.md#track-3-maintain-protocol-tooling) |
| Make a compatibility claim | [Understand compatibility evidence](docs/conformance.md) |
| Upgrade an Experimental 0.1 integration | [Read the 0.2 migration guide](docs/migration-0.1-to-0.2.md) |

## Experimental 0.4.0-experimental.1

The release keeps wire major 1 and publishes ten independently negotiated
profiles. A device declares only the profiles and hardware it implements:

| Profile | What it carries |
| --- | --- |
| `approval/1` | One active Allow/Deny request with TTL |
| `status/1` | Volatile Agent state for up to eight slots |
| `navigation/1` | Bounded options, cursor movement, and selection |
| `keys/1` | Host-defined key labels/light state and generic key events |
| `rotary/1` | Host-defined dial labels plus relative turn/press events |
| `voice/1` | Push-to-talk start/stop/cancel control; no audio |
| `text/1` | Bounded plain text for a device display |
| `usage/1` | Model label and bounded usage counters |
| `config/1` | Versioned atomic configuration and result |
| Profile | What it carries |
| -------------- | ---------------------------------------------------------- |
| `approval/1` | One active Allow/Deny request with TTL |
| `status/1` | Volatile Agent state for up to eight slots |
| `navigation/1` | Bounded options, cursor movement, and selection |
| `keys/1` | Host-defined key labels/light state and generic key events |
| `rotary/1` | Host-defined dial labels plus relative turn/press events |
| `voice/1` | Start/stop/cancel control for the Host microphone; no audio |
| `device-audio/1` | Physical-device microphone audio with credits and cancellation |
| `text/1` | Bounded plain text for a device display |
| `usage/1` | Model label and bounded usage counters |
| `config/1` | Versioned atomic configuration and result |

Public:

Expand Down Expand Up @@ -83,9 +84,13 @@ the device supports. The Host rejects traffic for undeclared profiles.
The profiles carry generic physical intent, not private Agent commands. The
trusted Host's Agent adapter decides whether key 3 means `fork`, whether a dial
switches a session or model, and which bounded text is safe to display.
`voice/1` carries only push-to-talk control: capture, permission, audio, and
transcription stay on the Host microphone. This lets DIY hardware remain useful
without receiving Agent credentials, internal session IDs, or account data.
`voice/1` carries only Host-microphone control. `device-audio/1` is separate:
it carries IMA ADPCM sampled by a microphone on the physical device, and only a
local physical input can begin a stream. Both paths reuse the official App's
speech-to-text and isolated Agent routing without giving hardware Agent
credentials, internal session IDs, or account data. See
[Device audio](docs/device-audio.md) and the
[Compatibility Tunnel](docs/compatibility-tunnel.md).

Two identity tiers share the contract: Nexting first-party products (PIN, Ring) carry production identity and the full capability set; third-party and DIY devices use the same protocol under explicit, revocable user authorization in the Host App.

Expand Down
Loading