Initial commit

2025-05-30 15:53:20 -04:00
commit 41d2eae1be
19 changed files with 1738 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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 so,
+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 alternatively 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 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