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