---
# System prepended metadata

title: Untitled

---

## The new pairing process 

Moving to a new protocol gives us the opportunity to explore a new way of pairing.
Unlike WebUSB, WebHID allows a website to list and connect to previously paired devices without going through the initial browser - device pairing flow everytime.
This is very similar to the bluetooth pairing / connecting flow. With this convention in mind here is a new flow proposal:

### Functionality

#### Sucessful pairing flow.

- The host initiates an HID connection and sends a packet to require pairing.
- The device replies with a sequence of matrix positions and waits for that sequence to be typed on.
- The host displays the sequence to the user.
- The user types the sequence properly.
- The keyboard reports a sucessful pairing to the host and saves the pairing sequence in EEPROM.
- The hosts receives a sucessful pairing packet and saves the pairing code for later uses.

#### Failed pairing flow.
- The host initiates an HID connection and sends a packet to require pairing.
- The device replies with a sequence of matrix positions and waits for that sequence to be typed on.
- The host displays the sequence to the user.
- The user screws up the sequence.
- The keyboard reports a failed pairing to the host and stops the pairing process.
- The hosts receives a failed pairing packet, notifies the user and restarts a pairing process.

#### Sucessful subsequent connections.
- The host initiates an HID connection and sends a packet to require connection with the stored pairing sequence.
- The device compairs the sequence from the packet and the EEPROM, it matches.
- The keyboard reports a sucessful pairing to the host.
- The hosts receives a sucessful pairing packet, live training is working.
 
#### Failed subsequent connections.
- The host initiates an HID connection and sends a packet to require connection with the stored pairing sequence.
- The device compairs the sequence from the packet and the EEPROM, it doesn't matches.
- The keyboard reports a failed pairing to the host.
- The hosts receives a failed pairing packet, notifies the user and starts a new pairing process.

#### Edge cases
- A keyboard can be paired with several hosts (Multiple browsers on the same computer or several computers). The keyboard needs to store multiple pairing codes.
- Plugging several keyboards to the same host should work.
- When in pairing mode since the keyboard will intercept key codes, we need to handle cases where the host disconnects while pairing and resume normal operations.

### Implementation details

- The feature will be available when the `ORYX_ENABLE = yes` make flag is set. This will be the case by default, a toggle on Oryx's advanced settings will allow to disable it.
- All the code to keep track of the pairing state, protocol implementation will reside in the `oryx.c / oryx.h` files, with the exception of the lufa / chibios usb protocol code where the state might be reset when sending rawhid packets to the host fail.
- Pairing codes will be stored with a max number set in a define. New pairing codes will push the older ones if the max capacity is reached (FIFO).
- Bonus points: Red indicator leds blink when pairing fails, Green ones blink when pairing succeeds.
