Skip to content

protocol.md

Latest commit

 

History

History
131 lines (94 loc) · 4.4 KB

protocol.md

File metadata and controls

131 lines (94 loc) · 4.4 KB
Raw

BLE protocol notes

CapSol uses the TRIKI Cap behavior independently documented by TRIKI Control. The notes below cover only the subset CapSol needs for Voice control, orientation, battery status, and LED alerts.

Device identity

  • Advertised family name: Triki
  • Model: CAP001
  • Producer: Caps Apps (distributed by Żabka)

The cap exposes a Nordic UART Service (NUS)-style profile:

NUS service:  6e400001-b5a3-f393-e0a9-e50e24dcca9e
RX  (write):  6e400002-b5a3-f393-e0a9-e50e24dcca9e
TX  (notify): 6e400003-b5a3-f393-e0a9-e50e24dcca9e
LED (write):  6e400004-b5a3-f393-e0a9-e50e24dcca9e

The standard BLE Battery Service is exposed separately:

Battery service: 0000180f-0000-1000-8000-00805f9b34fb
Battery level:   00002a19-0000-1000-8000-00805f9b34fb

Starting the motion stream

CapSol starts the stream by writing this command to RX:

20 10 00 d0 07 34 00 03

The 0x0034 little-endian rate field requests the approximately 53 Hz stream used by the desktop motion controller.

Motion frames

Motion notifications on TX are decoded as 14-byte frames:

22 II G0 G0 G1 G1 G2 G2 A0 A0 A1 A1 A2 A2
  • 22: frame marker.
  • II: packet-group identifier in the range 0..15.
  • G0..G2: three signed 16-bit little-endian gyroscope channels.
  • A0..A2: three signed 16-bit little-endian accelerometer channels.

CapSol preserves the packet identifier for press inference, uses all six channels to confirm motion and detect approval turns, and uses accelerometer Z for upright/upside-down state.

At rest, lying flat, gravity is close to magnitude 2048 in raw accelerometer units. Delivery can be fragmented or bursty, so the parser retains partial bytes until a complete frame is available and searches for the next valid marker after malformed data.

Connected button behavior

The cap does not publish a dedicated button characteristic. CapSol recognizes the measured marker sequence:

  • at least five baseline 0 samples;
  • at least two consecutive 1 samples within 500 ms.

CapSol emits on the second 1 sample so the action occurs on button-down instead of waiting for the trailing 0. Arbitrary nonzero resets and marker bursts without a preceding zero baseline are rejected. Recent gyroscope or accelerometer movement is required additionally while the LED controller is active, preventing LED traffic from imitating a physical press.

Offline wake behavior

CapSol never maps an advertisement or reconnect directly to Voice. The manufacturer payload (a0 0a) and advertised service UUID are the same during ordinary autonomous advertising and after a wake; scanner delivery gaps are also not proof that the radio was asleep.

The first physical press can wake an offline cap so CapSol reconnects and starts UART. A Voice action still requires a later connected-stream marker.

Approval-turn behavior

Approval turns use TRIKI Control's calibrated vertical-twist model. CapSol learns gyro bias during a 1.2-second median bootstrap, smooths the gravity vector, subtracts the bias, and projects the corrected gyro onto the normalized gravity axis.

At the default sensitivity of 50, a gesture requires:

  • corrected total spin of at least 800;
  • projected twist of at least 1000;
  • projected twist of at least 55% of corrected total spin;
  • three consecutive qualifying samples.

The 0..100 sensitivity slider applies the original threshold mapping:

twist_on    = 1600 - sensitivity * 12
twist_off   = twist_on * 0.69
turn_spin   = 1300 - sensitivity * 10

One threshold crossing produces one right/left event. The detector rearms only after a one-second cooldown followed by 250 ms of stationary sensor data, so a brief threshold dip or counter-rotation cannot emit another decision.

Battery level

CapSol reads the single-byte standard Battery Level characteristic after GATT connect and every 60 seconds while the session remains active. The byte is clamped to 0..100 and shown as a percentage. A missing or temporarily unreadable value is reported as unavailable without interrupting motion input.

LED writes

The LED characteristic uses write-with-response:

01  # LED on
00  # LED off

CapSol uses those writes for two-pulse task-complete notifications and, when enabled in Advanced, two-pulse completed Voice-reply notifications. The LED is always returned to off when a pattern finishes or the BLE client disconnects.