Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Linaro Limited
3 : * Copyright (c) 2024 Jamie McCrae
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @brief Public API for controlling linear strips of LEDs.
11 : *
12 : * This library abstracts the chipset drivers for individually
13 : * addressable strips of LEDs.
14 : */
15 :
16 : #ifndef ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_
17 : #define ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_
18 :
19 : /**
20 : * @brief LED Strip Interface
21 : * @defgroup led_strip_interface LED Strip Interface
22 : * @ingroup io_interfaces
23 : * @{
24 : */
25 :
26 : #include <errno.h>
27 : #include <zephyr/types.h>
28 : #include <zephyr/device.h>
29 :
30 : #ifdef __cplusplus
31 : extern "C" {
32 : #endif
33 :
34 : /**
35 : * @brief Color value for a single RGB LED.
36 : *
37 : * Individual strip drivers may ignore lower-order bits if their
38 : * resolution in any channel is less than a full byte.
39 : */
40 1 : struct led_rgb {
41 : #ifdef CONFIG_LED_STRIP_RGB_SCRATCH
42 : /*
43 : * Pad/scratch space needed by some drivers. Users should
44 : * ignore.
45 : */
46 : uint8_t scratch;
47 : #endif
48 : /** Red channel */
49 1 : uint8_t r;
50 : /** Green channel */
51 1 : uint8_t g;
52 : /** Blue channel */
53 1 : uint8_t b;
54 : };
55 :
56 : /**
57 : * @typedef led_api_update_rgb
58 : * @brief Callback API for updating an RGB LED strip
59 : *
60 : * @see led_strip_update_rgb() for argument descriptions.
61 : */
62 1 : typedef int (*led_api_update_rgb)(const struct device *dev,
63 : struct led_rgb *pixels,
64 : size_t num_pixels);
65 :
66 : /**
67 : * @typedef led_api_update_channels
68 : * @brief Callback API for updating channels without an RGB interpretation.
69 : *
70 : * @see led_strip_update_channels() for argument descriptions.
71 : */
72 1 : typedef int (*led_api_update_channels)(const struct device *dev,
73 : uint8_t *channels,
74 : size_t num_channels);
75 :
76 : /**
77 : * @typedef led_api_length
78 : * @brief Callback API for getting length of an LED strip.
79 : *
80 : * @see led_strip_length() for argument descriptions.
81 : */
82 1 : typedef size_t (*led_api_length)(const struct device *dev);
83 :
84 : /**
85 : * @brief LED strip driver API
86 : *
87 : * This is the mandatory API any LED strip driver needs to expose.
88 : */
89 1 : __subsystem struct led_strip_driver_api {
90 0 : led_api_update_rgb update_rgb;
91 0 : led_api_update_channels update_channels;
92 0 : led_api_length length;
93 : };
94 :
95 : /**
96 : * @brief Mandatory function to update an LED strip with the given RGB array.
97 : *
98 : * @param dev LED strip device.
99 : * @param pixels Array of pixel data.
100 : * @param num_pixels Length of pixels array.
101 : *
102 : * @retval 0 on success.
103 : * @retval -errno negative errno code on failure.
104 : *
105 : * @warning This routine may overwrite @a pixels.
106 : */
107 1 : static inline int led_strip_update_rgb(const struct device *dev,
108 : struct led_rgb *pixels,
109 : size_t num_pixels)
110 : {
111 : const struct led_strip_driver_api *api =
112 : (const struct led_strip_driver_api *)dev->api;
113 :
114 : /* Allow for out-of-tree drivers that do not have this function for 2 Zephyr releases
115 : * until making it mandatory, function added after Zephyr 3.6
116 : */
117 : if (api->length != NULL) {
118 : /* Ensure supplied pixel size is valid for this device */
119 : if (api->length(dev) < num_pixels) {
120 : return -ERANGE;
121 : }
122 : }
123 :
124 : return api->update_rgb(dev, pixels, num_pixels);
125 : }
126 :
127 : /**
128 : * @brief Optional function to update an LED strip with the given channel array
129 : * (each channel byte corresponding to an individually addressable color
130 : * channel or LED. Channels are updated linearly in strip order.
131 : *
132 : * @param dev LED strip device.
133 : * @param channels Array of per-channel data.
134 : * @param num_channels Length of channels array.
135 : *
136 : * @retval 0 on success.
137 : * @retval -ENOSYS if not implemented.
138 : * @retval -errno negative errno code on other failure.
139 : *
140 : * @warning This routine may overwrite @a channels.
141 : */
142 1 : static inline int led_strip_update_channels(const struct device *dev,
143 : uint8_t *channels,
144 : size_t num_channels)
145 : {
146 : const struct led_strip_driver_api *api =
147 : (const struct led_strip_driver_api *)dev->api;
148 :
149 : if (api->update_channels == NULL) {
150 : return -ENOSYS;
151 : }
152 :
153 : return api->update_channels(dev, channels, num_channels);
154 : }
155 :
156 : /**
157 : * @brief Mandatory function to get chain length (in pixels) of an LED strip device.
158 : *
159 : * @param dev LED strip device.
160 : *
161 : * @retval Length of LED strip device.
162 : */
163 1 : static inline size_t led_strip_length(const struct device *dev)
164 : {
165 : const struct led_strip_driver_api *api =
166 : (const struct led_strip_driver_api *)dev->api;
167 :
168 : return api->length(dev);
169 : }
170 :
171 : #ifdef __cplusplus
172 : }
173 : #endif
174 :
175 : /**
176 : * @}
177 : */
178 :
179 : #endif /* ZEPHYR_INCLUDE_DRIVERS_LED_STRIP_H_ */
|
