What You Will Learn

Prerequisites

Why LEDs Need Their Own Subsystem

A status LED is physically nothing more than a GPIO pin driving a small current through a diode, so it’s tempting to control it exactly like any other GPIO line. The problem is that “on” and “off” is rarely the whole story. Real LEDs need variable brightness (for LEDs wired to PWM-capable pins or driver ICs), event-driven blinking (heartbeat, disk activity, network activity) without the CPU waking up on a timer, and predictable naming so scripts and services can find “the LED for Wi-Fi status” without hardcoding a GPIO number that changes between board revisions.

The kernel’s LED class, implemented in drivers/leds/, solves all three. It exposes every registered LED under /sys/class/leds/, with a small, consistent set of attribute files regardless of whether the LED is wired to a plain GPIO, a PWM channel, or a dedicated LED driver chip on I2C or SPI.

The LED Naming Convention

Each LED directory under /sys/class/leds/ is named using the pattern devicename:color:function. The kernel documentation recommends this convention so tooling can reason about an LED’s purpose without needing board-specific knowledge — for example, spotting the LED whose function is heartbeat or status regardless of which vendor built the board.

Exploring the sysfs Interface

Start by listing the registered LEDs. On a typical single-board computer you’ll see something like this:

$ ls /sys/class/leds
board:green:status   board:green:activity   board:red:power

Each LED directory exposes a small, fixed set of attribute files:

$ ls /sys/class/leds/board:green:status
brightness  max_brightness  subsystem  trigger  uevent  device  power

• max_brightness — read-only, the highest value the LED accepts.
• brightness — read/write, current level from 0 (off) to max_brightness. LEDs without hardware brightness control simply treat any non-zero write as “on”.
• trigger — read/write, the kernel-side event source currently driving the LED.

Setting Brightness Directly

With no trigger active (or the trigger set to none), you own the LED completely through brightness:

# cat /sys/class/leds/board:green:status/max_brightness
255
# echo 255 > /sys/class/leds/board:green:status/brightness
# echo 0   > /sys/class/leds/board:green:status/brightness

If the LED is currently bound to an active trigger, writes to brightness may be overridden by the trigger the moment it fires again — so disable the trigger first if you want full manual control.

Working With Triggers

Reading trigger lists every trigger available for that LED, with the active one shown in square brackets:

$ cat /sys/class/leds/board:green:status/trigger
[none] mmc0 timer oneshot heartbeat panic gpio default-on

Select a different trigger by writing its name:

# echo timer > /sys/class/leds/board:green:status/trigger

Selecting timer creates two new attribute files that only exist while that trigger is active, letting you control the on/off period in milliseconds without writing a single line of driver code:

$ ls /sys/class/leds/board:green:status
brightness  delay_off  delay_on  max_brightness  trigger  ...
# echo 200 > /sys/class/leds/board:green:status/delay_on
# echo 800 > /sys/class/leds/board:green:status/delay_off

The heartbeat trigger is worth knowing specifically — it mimics a human pulse rate that scales with system load average, which is why it’s the default “is this board alive” indicator on many distributions. If the underlying hardware has an on-chip blink timer, selecting timer or a similar trigger offloads the blinking entirely to hardware, so the CPU is never interrupted just to flip an LED.

Building a Small LED Control Utility

Let’s write an original demo, ep_led_blink, that takes an LED name and a period in milliseconds and blinks it from userspace using the brightness file directly — useful when you want application-level control rather than a kernel trigger.

/* ep_led_blink.c
 * Usage: ep_led_blink <led-name> <period-ms> <count>
 * Example: ep_led_blink board:green:status 300 10
 */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>

static int write_attr(const char *led, const char *attr, const char *val)
{
    char path[256];
    snprintf(path, sizeof(path), "/sys/class/leds/%s/%s", led, attr);

    FILE *fp = fopen(path, "w");
    if (!fp) {
        perror(path);
        return -1;
    }
    fputs(val, fp);
    fclose(fp);
    return 0;
}

int main(int argc, char **argv)
{
    if (argc != 4) {
        fprintf(stderr, "usage: %s <led-name> <period-ms> <count>\n", argv[0]);
        return 1;
    }

    const char *led = argv[1];
    long period_ms  = strtol(argv[2], NULL, 10);
    int count       = atoi(argv[3]);

    /* Make sure no trigger is fighting us for control of brightness */
    if (write_attr(led, "trigger", "none") != 0)
        return 1;

    for (int i = 0; i < count; i++) {
        write_attr(led, "brightness", "255");
        usleep(period_ms * 1000 / 2);
        write_attr(led, "brightness", "0");
        usleep(period_ms * 1000 / 2);
    }

    return 0;
}

Build and run it against a real LED on your board:

$ gcc -o ep_led_blink ep_led_blink.c
$ sudo ./ep_led_blink board:green:status 300 10

Expected result: the selected LED blinks ten times at a 300 ms period, then the program exits leaving brightness at 0. Watching trigger in another terminal confirms the switch:

$ watch -n0.2 cat /sys/class/leds/board:green:status/trigger
[none] mmc0 timer oneshot heartbeat panic gpio default-on

GPIO Sysfs vs LED Class

Common Mistakes

Best Practices

• Prefer built-in triggers over polling loops in userspace whenever the behaviour you need already exists (heartbeat, mmc activity, disk activity).
• Always check max_brightness instead of assuming an 8-bit range.
• Grant LED sysfs access through udev rules rather than running control daemons as root.
• When writing systemd services that blink status LEDs, restore the LED’s original trigger on service stop so you don’t leave the board in a confusing state after a crash.

Summary and Key Takeaways

The LED class turns “toggle a pin” into a proper abstraction: consistent naming, brightness scaling where hardware supports it, and a library of kernel-side triggers that offload blinking away from userspace entirely. For simple manual control, sysfs writes to brightness are all you need — just remember to clear the active trigger first. For anything event-driven, check the trigger list before writing a single line of polling code; there’s a good chance the kernel already does what you’re about to reimplement.

Frequently Asked Questions