1 /*
2 * Copyright (c) 2017 Linaro Limited
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public API for controlling linear strips of LEDs.
10 *
11 * This library abstracts the chipset drivers for individually
12 * addressable strips of LEDs.
13 */
14
15 #ifndef ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_
16 #define ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_
17
18 /**
19 * @brief LED Strip Interface
20 * @defgroup led_strip_interface LED Strip Interface
21 * @ingroup io_interfaces
22 * @{
23 */
24
25 #include <zephyr/types.h>
26 #include <device.h>
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /**
33 * @brief Color value for a single RGB LED.
34 *
35 * Individual strip drivers may ignore lower-order bits if their
36 * resolution in any channel is less than a full byte.
37 */
38 struct led_rgb {
39 #ifdef CONFIG_LED_STRIP_RGB_SCRATCH
40 /*
41 * Pad/scratch space needed by some drivers. Users should
42 * ignore.
43 */
44 uint8_t scratch;
45 #endif
46 /** Red channel */
47 uint8_t r;
48 /** Green channel */
49 uint8_t g;
50 /** Blue channel */
51 uint8_t b;
52 };
53
54 /**
55 * @typedef led_api_update_rgb
56 * @brief Callback API for updating an RGB LED strip
57 *
58 * @see led_strip_update_rgb() for argument descriptions.
59 */
60 typedef int (*led_api_update_rgb)(const struct device *dev,
61 struct led_rgb *pixels,
62 size_t num_pixels);
63
64 /**
65 * @typedef led_api_update_channels
66 * @brief Callback API for updating channels without an RGB interpretation.
67 *
68 * @see led_strip_update_channels() for argument descriptions.
69 */
70 typedef int (*led_api_update_channels)(const struct device *dev,
71 uint8_t *channels,
72 size_t num_channels);
73
74 /**
75 * @brief LED strip driver API
76 *
77 * This is the mandatory API any LED strip driver needs to expose.
78 */
79 struct led_strip_driver_api {
80 led_api_update_rgb update_rgb;
81 led_api_update_channels update_channels;
82 };
83
84 /**
85 * @brief Update an LED strip made of RGB pixels
86 *
87 * Important:
88 * This routine may overwrite @a pixels.
89 *
90 * This routine immediately updates the strip display according to the
91 * given pixels array.
92 *
93 * @param dev LED strip device
94 * @param pixels Array of pixel data
95 * @param num_pixels Length of pixels array
96 * @return 0 on success, negative on error
97 * @warning May overwrite @a pixels
98 */
led_strip_update_rgb(const struct device * dev,struct led_rgb * pixels,size_t num_pixels)99 static inline int led_strip_update_rgb(const struct device *dev,
100 struct led_rgb *pixels,
101 size_t num_pixels) {
102 const struct led_strip_driver_api *api =
103 (const struct led_strip_driver_api *)dev->api;
104
105 return api->update_rgb(dev, pixels, num_pixels);
106 }
107
108 /**
109 * @brief Update an LED strip on a per-channel basis.
110 *
111 * Important:
112 * This routine may overwrite @a channels.
113 *
114 * This routine immediately updates the strip display according to the
115 * given channels array. Each channel byte corresponds to an
116 * individually addressable color channel or LED. Channels
117 * are updated linearly in strip order.
118 *
119 * @param dev LED strip device
120 * @param channels Array of per-channel data
121 * @param num_channels Length of channels array
122 * @return 0 on success, negative on error
123 * @warning May overwrite @a channels
124 */
led_strip_update_channels(const struct device * dev,uint8_t * channels,size_t num_channels)125 static inline int led_strip_update_channels(const struct device *dev,
126 uint8_t *channels,
127 size_t num_channels) {
128 const struct led_strip_driver_api *api =
129 (const struct led_strip_driver_api *)dev->api;
130
131 return api->update_channels(dev, channels, num_channels);
132 }
133
134 #ifdef __cplusplus
135 }
136 #endif
137
138 /**
139 * @}
140 */
141
142 #endif /* ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_ */
143
