I did a thing: GitHub - gadkrumholz/particle-adp8866-m1: particle.io dkms and python drivers for m1 enclosure for particle.io tachyon · GitHub
Particle M1 LED Controller (ADP8866)
A native Linux DKMS kernel driver and user-space controller for the ADP8866 LED multiplexer on the Particle M1 enclosure.
This repository provides a clean, upstream-compliant mechanism to interface with the M1's hardware RGB LEDs. It safely maps the hardware phase-routing, handles charge-pump initialization, and seamlessly integrates with the Linux LED subsystem triggers (like activity or default-on) while preserving manual user-space override capabilities.
Repository Structure
-
/dkms- The GPLv2 Linux kernel module and Device Tree Source (particle-adp8866-m1.dts). -
/systemd- Configuration files to set initial hardware parameters on boot. -
/scripts- Python-based CLI (particle-adp8866-m1.py) for advanced synchronized LED control.
Prerequisites
This driver is designed for Ubuntu 24.04 running kernel 6.8+. It has also been tested with Ubuntu 20.04.
Ensure your system is up to date and has the standard build tools installed before proceeding.
Installation Guide
Follow these 5 exact steps to compile the driver, inject it into your kernel, and configure it for early-boot execution.
1. Install Dependencies
Install the Dynamic Kernel Module Support (DKMS) framework and the Device Tree Compiler:
sudo apt update
sudo apt install dkms device-tree-compiler
2. Install the Kernel Driver (DKMS)
Copy the driver source directory into /usr/src/ and tell DKMS to build and install it. DKMS will automatically rebuild this driver in the background whenever you update your Ubuntu kernel in the future.
sudo cp -r dkms /usr/src/adp8866-led-1.0
sudo dkms add -m adp8866-led -v 1.0
sudo dkms build -m adp8866-led -v 1.0
sudo dkms install -m adp8866-led -v 1.0
3. Compile and Deploy the Device Tree Overlay
The DTS file maps the physical routing of the LEDs to the I2C bus and assigns the Linux triggers. Compile it into a blob (.dtbo), mount the M1's userdata partition, ensure the boot directory exists, and register the overlay with the bootloader:
# Compile the overlay
dtc -@ -I dts -O dtb -o particle-adp8866-m1.dtbo dkms/particle-adp8866-m1.dts
# Mount the userdata partition
sudo mount /dev/disk/by-partlabel/userdata /mnt/userdata/
# Ensure the target boot directory exists
sudo mkdir -p /mnt/userdata/boot/
# Copy the compiled overlay to the boot directory
sudo cp particle-adp8866-m1.dtbo /mnt/userdata/boot/
# Register the overlay in the bootloader configuration
echo "overlays=particle-adp8866-m1.dtbo" | sudo tee -a /mnt/userdata/boot/overlays.txt
4. Enable Boot-Up Brightness (Optional)
By default, standard Linux triggers like activity pulse at maximum brightness (255). To force a dimmer boot-up threshold (e.g., 50) without permanently locking out user-space, we use systemd-tmpfiles to write to sysfs during boot.
sudo cp systemd/m1-leds.conf /etc/tmpfiles.d/
sudo systemd-tmpfiles --create
5. Configure Early Boot Loading (Optional)
To ensure the driver loads as early as possible (before standard user-space), add it to your initial ramdisk modules list:
echo "adp8866-led" | sudo tee -a /etc/initramfs-tools/modules
Then, repackage the boot image to include the new driver:
sudo update-initramfs -u
Reboot your system to apply all changes.
Usage
Standard Sysfs Interface
Once rebooted, the LEDs are natively exposed to the Linux kernel. You can control them exactly like any other standard hardware device:
# Turn Group 1 Blue LED on fully
echo 255 > "/sys/class/leds/m1:user1:blue/brightness"
# Assign the activity trigger to Group 2 Red
echo "activity" > "/sys/class/leds/m1:user2:red/trigger"
Python CLI (Advanced Synchronization)
For complex, multi-group synchronized fading or autonomous hardware blinking, use the provided Python CLI (particle-adp8866-m1.py). This script bypasses standard triggers to communicate directly with the ADP8866's internal timers.
NOTE: cannot have the DKMS driver loaded for this script to function
Dependencies:
sudo apt install python3-smbus2
Examples:
# Fade Group 1 to solid White
sudo python3 scripts/particle-adp8866-m1.py --group 1 --rgb 50 50 50 --fade
# Trigger the autonomous, phase-locked SOS panic strobe across all LEDs
sudo python3 scripts/particle-adp8866-m1.py --sos
# Enable a synchronized hardware Heartbeat on Group 2 (Red)
sudo python3 scripts/particle-adp8866-m1.py --group 2 --rgb 127 0 0 --hb
# Turn everything off and put the hardware in Standby
sudo python3 scripts/particle-adp8866-m1.py --off
***
Tested under both 20.04 and 24.04
***