Documentation/leds/uleds.txt

   1 Userspace LEDs
   2 ==============
   3
   4 The uleds driver supports userspace LEDs. This can be useful for testing
   5 triggers and can also be used to implement virtual LEDs.
   6
   7
   8 Usage
   9 =====
  10
  11 When the driver is loaded, a character device is created at /dev/uleds. To
  12 create a new LED class device, open /dev/uleds and write a uleds_user_dev
  13 structure to it (found in kernel public header file linux/uleds.h).
  14
  15     #define ULEDS_MAX_NAME_SIZE 80
  16
  17     struct uleds_user_dev {
  18         char name[ULEDS_MAX_NAME_SIZE];
  19     };
  20
  21 A new LED class device will be created with the name given. The name can be
  22 any valid file name, but consider using the LED class naming convention of
  23 "devicename:color:function".
  24
  25 The current brightness is found by reading a single byte from the character
  26 device. Values are unsigned: 0 to 255. Reading does not block and always returns
  27 the most recent brightness value. The device node can also be polled to notify
  28 when the brightness value changes.
  29
  30 The LED class device will be removed when the open file handle to /dev/uleds
  31 is closed.
  32
  33
  34 Example
  35 =======
  36
  37 /*
  38  * uledmon.c
  39  *
  40  * This program creates a new userspace LED class device and monitors it. A
  41  * timestamp and brightness value is printed each time the brightness changes.
  42  *
  43  * Usage: uledmon <device-name>
  44  *
  45  * <device-name> is the name of the LED class device to be created. Pressing
  46  * CTRL+C will exit.
  47  */
  48
  49 #include <fcntl.h>
  50 #include <poll.h>
  51 #include <stdio.h>
  52 #include <string.h>
  53 #include <time.h>
  54 #include <unistd.h>
  55
  56 #include <linux/uleds.h>
  57
  58 int main(int argc, char const *argv[])
  59 {
  60     struct uleds_user_dev uleds_dev;
  61     int fd, ret;
  62     struct pollfd pfd;
  63     unsigned char brightness;
  64     struct timespec ts;
  65
  66     if (argc != 2) {
  67         fprintf(stderr, "Requires <device-name> argument\n");
  68         return 1;
  69     }
  70
  71     strncpy(uleds_dev.name, argv[1], ULEDS_MAX_NAME_SIZE);
  72
  73     fd = open("/dev/uleds", O_RDWR);
  74     if (fd == -1) {
  75         perror("Failed to open /dev/uleds");
  76         return 1;
  77     }
  78
  79     ret = write(fd, &uleds_dev, sizeof(uleds_dev));
  80     if (ret == -1) {
  81         perror("Failed to write to /dev/uleds");
  82         close(fd);
  83         return 1;
  84     }
  85
  86     pfd.fd = fd;
  87     pfd.events = POLLIN;
  88     pfd.revents = 0;
  89
  90     while (!(pfd.revents & (POLLERR | POLLHUP | POLLNVAL))) {
  91         ret = read(fd, &brightness, 1);
  92         if (ret == -1) {
  93             perror("Failed to read from /dev/uleds");
  94             close(fd);
  95             return 1;
  96         }
  97         clock_gettime(CLOCK_MONOTONIC, &ts);
  98         printf("[%ld.%09ld] %u\n", ts.tv_sec, ts.tv_nsec, brightness);
  99         poll(&pfd, 1, -1);
 100     }
 101
 102     close(fd);
 103
 104     return 0;
 105 }