1 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #pragma once
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 #include "esp_err.h"
21 
22 /**
23 * @brief LED Strip Type
24 *
25 */
26 typedef struct led_strip_s led_strip_t;
27 
28 /**
29 * @brief LED Strip Device Type
30 *
31 */
32 typedef void *led_strip_dev_t;
33 
34 /**
35 * @brief Declare of LED Strip Type
36 *
37 */
38 struct led_strip_s {
39     /**
40     * @brief Set RGB for a specific pixel
41     *
42     * @param strip: LED strip
43     * @param index: index of pixel to set
44     * @param red: red part of color
45     * @param green: green part of color
46     * @param blue: blue part of color
47     *
48     * @return
49     *      - ESP_OK: Set RGB for a specific pixel successfully
50     *      - ESP_ERR_INVALID_ARG: Set RGB for a specific pixel failed because of invalid parameters
51     *      - ESP_FAIL: Set RGB for a specific pixel failed because other error occurred
52     */
53     esp_err_t (*set_pixel)(led_strip_t *strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue);
54 
55     /**
56     * @brief Refresh memory colors to LEDs
57     *
58     * @param strip: LED strip
59     * @param timeout_ms: timeout value for refreshing task
60     *
61     * @return
62     *      - ESP_OK: Refresh successfully
63     *      - ESP_ERR_TIMEOUT: Refresh failed because of timeout
64     *      - ESP_FAIL: Refresh failed because some other error occurred
65     *
66     * @note:
67     *      After updating the LED colors in the memory, a following invocation of this API is needed to flush colors to strip.
68     */
69     esp_err_t (*refresh)(led_strip_t *strip, uint32_t timeout_ms);
70 
71     /**
72     * @brief Clear LED strip (turn off all LEDs)
73     *
74     * @param strip: LED strip
75     * @param timeout_ms: timeout value for clearing task
76     *
77     * @return
78     *      - ESP_OK: Clear LEDs successfully
79     *      - ESP_ERR_TIMEOUT: Clear LEDs failed because of timeout
80     *      - ESP_FAIL: Clear LEDs failed because some other error occurred
81     */
82     esp_err_t (*clear)(led_strip_t *strip, uint32_t timeout_ms);
83 
84     /**
85     * @brief Free LED strip resources
86     *
87     * @param strip: LED strip
88     *
89     * @return
90     *      - ESP_OK: Free resources successfully
91     *      - ESP_FAIL: Free resources failed because error occurred
92     */
93     esp_err_t (*del)(led_strip_t *strip);
94 };
95 
96 /**
97 * @brief LED Strip Configuration Type
98 *
99 */
100 typedef struct {
101     uint32_t max_leds;   /*!< Maximum LEDs in a single strip */
102     led_strip_dev_t dev; /*!< LED strip device (e.g. RMT channel, PWM channel, etc) */
103 } led_strip_config_t;
104 
105 /**
106  * @brief Default configuration for LED strip
107  *
108  */
109 #define LED_STRIP_DEFAULT_CONFIG(number, dev_hdl) \
110     {                                             \
111         .max_leds = number,                       \
112         .dev = dev_hdl,                           \
113     }
114 
115 /**
116 * @brief Install a new ws2812 driver (based on RMT peripheral)
117 *
118 * @param config: LED strip configuration
119 * @return
120 *      LED strip instance or NULL
121 */
122 led_strip_t *led_strip_new_rmt_ws2812(const led_strip_config_t *config);
123 
124 /**
125  * @brief Init the RMT peripheral and LED strip configuration.
126  *
127  * @param[in] channel: RMT peripheral channel number.
128  * @param[in] gpio: GPIO number for the RMT data output.
129  * @param[in] led_num: number of addressable LEDs.
130  * @return
131  *      LED strip instance or NULL
132  */
133 led_strip_t * led_strip_init(uint8_t channel, uint8_t gpio, uint16_t led_num);
134 
135 /**
136  * @brief Denit the RMT peripheral.
137  *
138  * @param[in] strip: LED strip
139  * @return
140  *     - ESP_OK
141  *     - ESP_FAIL
142  */
143 esp_err_t led_strip_denit(led_strip_t *strip);
144 
145 #ifdef __cplusplus
146 }
147 #endif
148