mirror of
https://github.com/vsergeev/c-periphery.git
synced 2026-02-05 22:52:35 +08:00
277 lines
6.8 KiB
Markdown
277 lines
6.8 KiB
Markdown
### 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);
|
|
int led_get_trigger(led_t *led, char *str, size_t len);
|
|
int led_get_triggers_entry(led_t *led, unsigned int index, char *str, size_t len);
|
|
int led_get_triggers_count(led_t *led, unsigned int *count);
|
|
|
|
/* Setters */
|
|
int led_set_brightness(led_t *led, unsigned int brightness);
|
|
int led_set_trigger(led_t *led, const char *trigger);
|
|
|
|
/* 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_get_trigger(led_t *led, char *str, size_t len);
|
|
```
|
|
Get the active trigger for 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_triggers_entry(led_t *led, unsigned int index, char *str, size_t len);
|
|
```
|
|
Get the trigger name at position `index` of triggers available for 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_triggers_count(led_t *led, unsigned int *count);
|
|
```
|
|
Get the count of triggers available for 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_set_trigger(led_t *led, const char *trigger);
|
|
```
|
|
Set the active trigger for the LED.
|
|
|
|
`led` should be a valid pointer to an LED handle opened with `led_open()`.
|
|
`trigger` should be a null-terminated string.
|
|
|
|
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;
|
|
}
|
|
```
|
|
|