Halcyon Controller Specification

The Halcyon Series are all compatible with the same controllers. We made our own standard to follow across all of them, which makes it easier for us to develop and support new keyboards. The standard has two parts to it: a connector specification, and a controller implementation.

Connector specification

The connector specification specifies which functional pins are exposed to the keyboard. It is essentially a contract of which pins the controller needs to supply in order for the keyboard to perform its job.

There will be more Halcyon controllers in the future. This part of the specification ensures that future controllers can be made to be backwards compatible with current keyboards.

Voltage sense

A VCONN pin allows the controller to know whether it is connected to a host device directly. It connects to the 5V pin of the host USB cable, but not to the interconnect cable.

Inputs and outputs

There are sixteen general purpose input and output pins defined, IO_01 through IO_16. As a general rule, any inputs are assigned to the keyboard matrix pins first, and any other desired inputs are then assigned after.

A side detection pin will be mapped to an IO pin, which will be mapped to either GND or 3V3. This can be used to detect which side a keyboard is in the firmware, though other means are available (like VCONN) as well.

As an example, a keyboard with a 4x4 matrix and a rotary encoder uses its first eight IO pins to drive the matrix, and the ninth and tenth IO pin to drive the rotary encoder.

Assigning the IO pins in this manner ensures that if a future controller happens to have fewer IO to offer, it'll have greater compatibility with required features, even if optional features like an onboard encoder may not be supported.

VIK

The VIK interface is exposed through the controller, offering I2C, SPI as well as voltage and digital/analog general purpose input/outputs.

The RGB pin is connected to the data output of the last RGB LED in the chain on the keyboard, as most keyboard firmware implementations support the use of a single chain of LEDs. This choice does mean that you'll need to drive all LEDs of the keyboard, even if you set them to be off, in order to drive an RGB LED on the VIK module.

Each Halcyon keyboard will provide a switch between the 5V output of the VIK connector and the 5V supply, in order to support the use of the Cirque trackpad module which cannot accept 5V.

RGB

The same pin is used across all Halcyon keyboards to drive the chain of both underglow and per-key RGB LEDs, such as WS2812B and SK6812MINI-E LEDs.

This pin is used only for the data. The power is driven from a separate power net, which the controller can choose to toggle on or off separately. Support for this separate net was added in anticipation of a future wireless controller, in order to be able to reduce power draw.

Communication

Duplex communication is supported between two halves of a Halcyon keyboard, through an RX and a TX pin.

The RX pin of one half is connected to the TX pin of the other half, and likewise for the TX pin and RX pin.

Additional pins

Next to the pins described above, additional pins are exposed by the controller, but may not currently be in use.

Controller implementation

The controller implementation describes which pins are used for which parts of the connector specification.

Wired RP2040 controller

The first Halcyon controller is based on the RP2040 chip, and uses the following pins: