# HyperX Alloy Elite 2 Automatic Backlight

This project automatically controls the RGB backlight of a HyperX Alloy Elite 2
keyboard based on ADC readings from an attached light dependent resistor. The
backlight automatically turns on to white when the LDR reading is below
a programmed threshold and otherwise turns all RGB lights completely off.

![Keyboard RGB turning on and off with ambient lighting](lightonoff.gif)

## Setup

### Hardware

You will need the following hardware to make the device:
- Raspberry Pi Pico
- USB extension cable
- light dependent resistor such as GL5528 (specific part number may vary)
- 10k ohm resistor (resistance value may vary)

You will need to cut the USB extension in half and connect the wires from the
female end to the Raspberry Pi Pico. The default configuration is to attach the
USB's green wire to pin 1/GP0 and USB's white wire to pin 2/GP1. You will also
need to connect the red to 5V VBUS/VSYS (since you'll be powering from the
USB host device, VBUS should be fine) and the black to any ground pin. Pin 38
is the closest and most convenient. While you can connect the Raspberry Pi Pico
to the host device using the micro USB port and a micro USB cable, since
you have already sacrificed half of the USB extension cable, you might as well
use the male half to create a standard USB-A connection.  If you wish to do,
then simply connect the red and black wires of the male connector end to
VBUS (5V) and GND, respectively. For the data wires, you can solder them to the
two test points TP2 and TP3 on the back of the Raspberry Pi Pico. The white
cable goes to TP2 and the green cable to TP3.

![Back of Raspberry Pi Pico with USB connections to TP2 and TP3](back.jpg)

The LDR should then be connected to the ADC2 pin (pin 34/GP28) and 3.3V (pin 36)
or alternative to the ADC_VREF (pin 35) and the regular resistor between ADC2
and any ground, including ADC_GND (pin 33). The results look something like
the following.

![Back of Raspberry Pi Pico with USB and LDR connected](front.jpg)

The individual wires on the USB can be fragile, so hot glue or other strain
relief is a good idea. There is also a [model for a 3D printed
enclosure](pico-usb-ldr.stl) that you can use to place the Pico inside with a
hole for the LDR to detect ambient light.

![3D printed enclosure with finished device](enclosure.jpg)

## Software

Flash the [hyperx_kb_rgb.uf2](hyperx_kb_rgb.uf2) file to the Raspberry Pi Pico,
and connect the keyboard to the female USB port and the insert the male USB
connector of the device into your host device such as PC.

If you wish to change the ADC reading threshold for changing the lighting,
you can do so in the `get_light` function of [hyperx_elite2.c](hyperx_elite2.c).

You can change the color used in the two different modes inside the `rgb_task()`
function of [hyperx_elite2.c](hyperx_elite2.c).

If you used a different ADC pin than ADC2, you can change the selected ADC pin
in the `startADC()` function of [hyperx_elite2.c](hyperx_elite2.c).

For any of the changes above, you will need to modify the
[CMakeLists.txt](CMakeLists.txt) file and compile the program yourself. You
will need to change `PICO_SDK_PATH` and `PICO_PIO_USB_PATH` to the
directories where you have the
[Raspberry Pi Pico SDK](https://github.com/raspberrypi/pico-sdk) and
[Pico-PIO-USB](https://github.com/sekigon-gonnoc/Pico-PIO-USB) library
downloaded on your machine.

## Licensing

This software is distributed under the [GNU General Public License version
3](LICENSE), with the exception of the libraries in the following section.

## Credits

The project uses code from the following sources:
- [OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB/) for code related to
  HyperX's [RGB lighting protocol](https://gitlab.com/CalcProgrammer1/OpenRGB/-/blob/master/Controllers/HyperXKeyboardController/HyperXAlloyElite2Controller/HyperXAlloyElite2Controller.cpp)
  on the Alloy Elite 2 keyboard licensed under GNU-GPLv2
- [Pico-PIO-USB](https://github.com/sekigon-gonnoc/Pico-PIO-USB/) for templates
  used from the [host_hid_to_device_cdc](https://github.com/sekigon-gonnoc/Pico-PIO-USB/tree/control-keyboard-led/examples/host_hid_to_device_cdc)
  example released under the MIT license
- [TinyUSB](https://github.com/hathach/tinyusb) for templates used in
  [tusb_config.h](tusb_config.h) distributed under the MIT license
