led: add led module

vsergeev · Jan 8, 2020 · 6d3f48e · 6d3f48e
1 parent 85c163f
commit 6d3f48e
Show file tree

Hide file tree

Showing 6 changed files with 725 additions and 4 deletions.
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 LIB = periphery.a
-SRCS = src/gpio.c src/spi.c src/i2c.c src/mmio.c src/serial.c src/version.c
+SRCS = src/gpio.c src/led.c src/spi.c src/i2c.c src/mmio.c src/serial.c src/version.c
 
 SRCDIR = src
 OBJDIR = obj

diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # c-periphery [![Build Status](https://travis-ci.org/vsergeev/c-periphery.svg?branch=master)](https://travis-ci.org/vsergeev/c-periphery) [![GitHub release](https://img.shields.io/github/release/vsergeev/c-periphery.svg?maxAge=7200)](https://github.com/vsergeev/c-periphery) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vsergeev/c-periphery/blob/master/LICENSE)
 
-## C Library for Linux Peripheral I/O (GPIO, SPI, I2C, MMIO, Serial)
+## C Library for Linux Peripheral I/O (GPIO, LED, SPI, I2C, MMIO, Serial)
 
-c-periphery is a small C library for GPIO, SPI, I2C, MMIO, and Serial peripheral I/O interface access in userspace Linux. c-periphery simplifies and consolidate the native Linux APIs to these interfaces. c-periphery is useful in embedded Linux environments (including Raspberry Pi, BeagleBone, etc. platforms) for interfacing with external peripherals. c-periphery is re-entrant, has no dependencies outside the standard C library and Linux, compiles into a static library for easy integration with other projects, and is MIT licensed.
+c-periphery is a small C library for GPIO, LED, SPI, I2C, MMIO, and Serial peripheral I/O interface access in userspace Linux. c-periphery simplifies and consolidate the native Linux APIs to these interfaces. c-periphery is useful in embedded Linux environments (including Raspberry Pi, BeagleBone, etc. platforms) for interfacing with external peripherals. c-periphery is re-entrant, has no dependencies outside the standard C library and Linux, compiles into a static library for easy integration with other projects, and is MIT licensed.
 
 Using Python or Lua? Check out the [python-periphery](https://github.com/vsergeev/python-periphery) and [lua-periphery](https://github.com/vsergeev/lua-periphery) projects.
 
@@ -60,6 +60,55 @@ int main(void) {
 
 [Go to GPIO documentation.](docs/gpio.md)
 
+### LED
+
+``` c
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdbool.h>
+
+#include "led.h"
+
+int main(void) {
+    led_t *led;
+    unsigned int max_brightness;
+
+    led = led_new();
+
+    /* Open LED led0 */
+    if (led_open(led, "led0") < 0) {
+        fprintf(stderr, "led_open(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Turn on LED (set max brightness) */
+    if (led_write(led, true) < 0) {
+        fprintf(stderr, "led_write(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Get max brightness */
+    if (led_get_max_brightness(led, &max_brightness) < 0) {
+        fprintf(stderr, "led_get_max_brightness(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Set half brightness */
+    if (led_set_brightness(led, max_brightness / 2) < 0) {
+        fprintf(stderr, "led_set_brightness(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    led_close(led);
+
+    led_free(led);
+
+    return 0;
+}
+```
+
+[Go to LED documentation.](docs/led.md)
+
 ### SPI
 
 ``` c
@@ -327,7 +376,7 @@ $
 
 ## Building c-periphery into another project
 
-Include the header files in `src/` (e.g. `gpio.h`, `spi.h`, `i2c.h`, `mmio.h`, `serial.h`) and link in the `periphery.a` static library.
+Include the header files in `src/` (e.g. `gpio.h`, `led.h`, `spi.h`, `i2c.h`, `mmio.h`, `serial.h`) and link in the `periphery.a` static library.
 
 ``` console
 $ gcc -I/path/to/periphery/src myprog.c /path/to/periphery/periphery.a -o myprog

diff --git a/docs/led.md b/docs/led.md
@@ -0,0 +1,227 @@
+### NAME
+
+LED wrapper functions for Linux userspace sysfs LEDs.
+
+### SYNOPSIS
+
+``` c
+#include <periphery/led.h>
+
+/* Primary Functions */
+led_t *led_new(void);
+int led_open(led_t *led, const char *name);
+int led_read(led_t *led, bool *value);
+int led_write(led_t *led, bool value);
+int led_close(led_t *led);
+void led_free(led_t *led);
+
+/* Getters */
+int led_get_brightness(led_t *led, unsigned int *brightness);
+int led_get_max_brightness(led_t *led, unsigned int *max_brightness);
+
+/* Setters */
+int led_set_brightness(led_t *led, unsigned int brightness);
+
+/* Miscellaneous */
+int led_name(led_t *led, char *str, size_t len);
+int led_tostring(led_t *led, char *str, size_t len);
+
+/* Error Handling */
+int led_errno(led_t *led);
+const char *led_errmsg(led_t *led);
+```
+
+### DESCRIPTION
+
+``` c
+led_t *led_new(void);
+```
+Allocate an LED handle.
+
+Returns a valid handle on success, or NULL on failure.
+
+------
+
+``` c
+int led_open(led_t *led, const char *name);
+```
+Open the sysfs LED with the specified name.
+
+`led` should be a valid pointer to an allocated LED handle structure.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_read(led_t *led, bool *value);
+```
+Read the state of the LED into `value`, where `true` is non-zero brightness, and `false` is zero brightness.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`. `value` should be a pointer to an allocated bool.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_write(led_t *led, bool value);
+```
+Write the state of the LED to `value`, where `true` is max brightness, and `false` is zero brightness.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_close(led_t *led);
+```
+Close the LED.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+void led_free(led_t *led);
+```
+Free an LED handle.
+
+------
+
+``` c
+int led_get_brightness(led_t *led, unsigned int *brightness);
+```
+Get the brightness of the LED.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_get_max_brightness(led_t *led, unsigned int *max_brightness);
+```
+Get the max brightness of the LED.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_set_brightness(led_t *led, unsigned int brightness);
+```
+Set the brightness of the LED.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_name(led_t *led, char *str, size_t len);
+```
+Return the name of the sysfs LED.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+Returns 0 on success, or a negative [LED error code](#return-value) on failure.
+
+------
+
+``` c
+int led_tostring(led_t *led, char *str, size_t len);
+```
+Return a string representation of the LED handle.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+This function behaves and returns like `snprintf()`.
+
+------
+
+``` c
+int led_errno(led_t *led);
+```
+Return the libc errno of the last failure that occurred.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+------
+
+``` c
+const char *led_errmsg(led_t *led);
+```
+Return a human readable error message of the last failure that occurred.
+
+`led` should be a valid pointer to an LED handle opened with `led_open()`.
+
+### RETURN VALUE
+
+The periphery LED functions return 0 on success or one of the negative error codes below on failure.
+
+The libc errno of the failure in an underlying libc library call can be obtained with the `led_errno()` helper function. A human readable error message can be obtained with the `led_errmsg()` helper function.
+
+| Error Code            | Description                       |
+|-----------------------|-----------------------------------|
+| `LED_ERROR_ARG`       | Invalid arguments                 |
+| `LED_ERROR_OPEN`      | Opening LED                       |
+| `LED_ERROR_QUERY`     | Querying LED attributes           |
+| `LED_ERROR_IO`        | Reading/writing LED brightness    |
+| `LED_ERROR_CLOSE`     | Closing LED                       |
+
+### EXAMPLE
+
+``` c
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdbool.h>
+
+#include "led.h"
+
+int main(void) {
+    led_t *led;
+    unsigned int max_brightness;
+
+    led = led_new();
+
+    /* Open LED led0 */
+    if (led_open(led, "led0") < 0) {
+        fprintf(stderr, "led_open(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Turn on LED (set max brightness) */
+    if (led_write(led, true) < 0) {
+        fprintf(stderr, "led_write(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Get max brightness */
+    if (led_get_max_brightness(led, &max_brightness) < 0) {
+        fprintf(stderr, "led_get_max_brightness(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    /* Set half brightness */
+    if (led_set_brightness(led, max_brightness / 2) < 0) {
+        fprintf(stderr, "led_set_brightness(): %s\n", led_errmsg(led));
+        exit(1);
+    }
+
+    led_close(led);
+
+    led_free(led);
+
+    return 0;
+}
+```
+