Connect AhaKey keys and its device microphone to Nexting

What the public devices/ directory is

The devices/ directory on GitHub is the public contract between hardware developers and the Nexting App. It is not the App or cloud source. A device uses this contract to declare capabilities, send physical input, and receive bounded state. The official App owns authorization, speech-to-text, Agent selection, and the remote session.

The actual data path

physical voice key
  → AhaKey microphone
  → CH582/CH58x-targeted firmware port: PCM16 / 16 kHz / mono
  → IMA ADPCM + CRC32C + BLE fragmentation
  → Nexting App: reassembly, decode, speech-to-text
  → Agent selected when recording began
  → App / LED / OLED state feedback

AhaKey is the nearby input device; the Agent may run on another computer. The keyboard never receives Agent credentials, internal session IDs, account data, or cloud routes. Those remain inside the Nexting App and its trusted Host.

Hardware capability mapping

A production AhaKey integration must bind the physical voice key. It may reuse a configurable key or use a separate input. The public protocol does not dictate the product layout, and Device Info declares only capabilities that exist and have passed hardware verification.

How the Nexting App stays vendor-neutral

The App core has no AhaKey model branch and does not parse stock AhaKey commands. It handles Device Info, generic profiles, and four logical channels. AhaKey GATT UUIDs and A0–A3 opcodes live only in a declarative transport descriptor and the firmware adapter. A future device can use different UUIDs, chips, and controls while reusing the same App audio and Agent pipeline.

Three integration modes

Connection and recording lifecycle

1. 1

   Pair, bond, and encrypt

   The App connects only after the signed-in user explicitly authorizes the third-party device. Revocation, logout, or disconnect terminates capture and clears temporary state.
2. 2

   Read Device Info

   The device declares identity, controls, display, battery, and the exact profiles it implements. Undeclared capabilities stay disabled.
3. 3

   Load the transport descriptor

   The descriptor maps vendor GATT onto control_down, control_up, audio_up, and flow_down. The App above that layer sees logical channels only.
4. 4

   Prepare the recording session

   The App sends audio_config to say authorization and buffers are ready. It may prepare capture, but it cannot remotely start the AhaKey microphone.
5. 5

   Start from the physical key

   The firmware creates audio_begin and uploads frames only after physical input. The App decodes them into its existing speech-to-text and Agent-send path.
6. 6

   Stop, cancel, and wipe on failure

   A release at or after 450 ms submits. A release before 450 ms latches recording and the next physical press submits. Cancel, timeout, disconnect, CRC failure, or a credit stall ends and wipes the stream. A stale result cannot enter a new device or Agent session.

device-audio/1 rules that matter

voice/1 keeps its existing meaning: lifecycle control for the Host or phone microphone, with no audio bytes.device-audio/1 is a separately negotiated profile carrying audio sampled by the physical device itself. They are not interchangeable.

What the CH58x-targeted firmware port must connect

Public AhaKey release and flashing material targets the CH582 family and CH58x tooling, but no public BOM, schematic, or chip-marking evidence confirms the exact production controller. Experimental 0.4 implements encoding, fragmentation, flow control, lifecycle, and the Compatibility Tunnel. A production port must connect microphone, BLE, and display callbacks; no Agent or Nexting App logic belongs in the keyboard.

devices/sdk/c/include/nexting_device.h
devices/sdk/c/src/nexting_device.c
devices/sdk/c/include/nexting_device_audio.h
devices/sdk/c/src/nexting_device_audio.c
devices/firmware/ahakey-x1/CMakeLists.txt
devices/firmware/ahakey-x1/ahakey_proto.h
devices/firmware/ahakey-x1/ahakey_proto.c
devices/firmware/ahakey-x1/nexting_ahakey_adapter.h

notify_7344(...);          // BLE notify
vendor_7343_write(...);    // preserve stock command handling
microphone_start(...);     // PCM16 / 16 kHz / mono / 320 samples
microphone_stop(...);      // user submits
microphone_cancel(...);    // stop now and wipe DMA / ring buffers
render_audio_state(...);   // ready / receiving / transcribing / submitted / error

The upstream public firmware repository supplies CH582 release HEX files and flashing instructions, but not buildable v1.1.0 production source, a schematic, or a public PCM callback. This guide therefore does not invent a final ADC/I2S/PDM symbol. Bind it after production source and a physical unit are available.

Connecting the keys

Stock HID key assignments remain configurable and can be saved to flash. This is a reference mapping for approvals and generic keys, not a required product layout. A production port must call the physical audio entry point for the chosen voice key.

Key1 → F18   approval/1 Allow
Key2 → F19   approval/1 Deny
Key3 → F13   keys/1 slot 0
Key4 → F14   keys/1 slot 1
lever        keys/1 slot 7 (press / release)
voice down   nexting_ahakey_port_voice_pressed(...)
voice up     nexting_ahakey_port_voice_released(...)
voice cancel nexting_ahakey_port_voice_cancel(...)

Current availability and evidence

Verify each item when hardware arrives

1. 1

   Confirm the controller and wire PCM

   Confirm the production controller from the physical unit or vendor BOM, connect its real microphone driver, and verify every sampling, frame-size, and pre-key capture rule above.
2. 2

   Wire physical input and state

   Call the voice press/release entry points and visibly render ready, receiving, transcribing, submitted, and error.
3. 3

   Publish real Device Info

   Set a stable per-device UUID and real firmware version. Declare device-audio/1 only after microphone tests pass.
4. 4

   Exercise both phone platforms

   Verify start, tap-to-latch, release-to-submit, cancel, disconnect, and reconnect on iPhone and Android.
5. 5

   Prove the audio source

   Complete a recording with phone microphone permission disabled and capture BLE evidence tying audio_begin and frames to the physical key and device.
6. 6

   Stress the failure paths

   Stop credits and inject loss or CRC faults. Verify every flow-control, loss, cancellation, queue, and wipe limit in the table above.