Contiki-NG
leds.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2005, Swedish Institute of Computer Science
3  * Copyright (c) 2018, George Oikonomou - http://www.spd.gr
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  * 3. Neither the name of the copyright holder nor the names of its
16  * contributors may be used to endorse or promote products derived
17  * from this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
30  * OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*---------------------------------------------------------------------------*/
33 /**
34  * \addtogroup dev
35  * @{
36  */
37 /*---------------------------------------------------------------------------*/
38 /**
39  * \defgroup leds LED Hardware Abstraction Layer
40  *
41  * The LED HAL provides a set of functions that can manipulate LEDS.
42  *
43  * Currently, the LED HAL supports two APIs:
44  *
45  * - The new, platform-independent API (recommended for all new platforms).
46  * - The legacy API (supported until all existing platforms have been ported
47  * to support the new API).
48  *
49  * The two APIs use very similar semantics and have an overlapping set of
50  * function calls. This is done so that platform-independent examples can
51  * work on all platforms, irrespective of which API each platform supports.
52  *
53  * The legacy API can be enabled by the platform code by defining
54  * LEDS_CONF_LEGACY_API 1.
55  *
56  * Once all platforms supported in contiki-ng/contiki-ng have been ported to
57  * the new API, the legacy API will be deleted without warning. For this
58  * reason, it is strongly recommended to use the new API for new platforms and
59  * for platforms hosted in external repositories.
60  *
61  * The new API provides a set of common LED manipulation functions that can be
62  * used in a platform-independent fashion. Functions exist to manipulate one
63  * LED at a time (\c leds_single_XYZ), as well as to manipulate multiple LEDs
64  * at a time (\c leds_XYZ).
65  *
66  * The assumption is that each LED is connected to a GPIO pin using either
67  * positive or negative logic.
68  *
69  * LEDs on a device are numbered incrementally, starting from 0 and counting
70  * upwards. Thus, if a device has 3 LEDs they will be numbered 0, 1 and 2.
71  * Convenience macros (LEDS_LED_n) are provided to refer to LEDs. These macros
72  * can be used as arguments to functions that manipulate a single LED, such
73  * as leds_single_on() but \e not leds_on().
74  *
75  * The legacy scheme that uses colours to refer to LEDs is maintained, without
76  * semantic changes, but with minor changes in logic:
77  *
78  * - Firstly, we now define 5 LED colours: Red, Green, Blue, Yellow, Orange.
79  * These are sufficient to cover all currently-supported platforms.
80  * - Secondly, unless a platform specifies that a LED of a specific colour
81  * exists, the HAL will assume that it does not.
82  * - Trying to manipulate a non-existent LED will not cause build errors, but
83  * will not cause any changes to LED state either.
84  * - We no longer map non-existing LED colours to existing ones.
85  *
86  * Note that, in order to avoid changes to LED colour semantics between the
87  * two APIs, references to LED by colour are bitwise OR masks and should
88  * therefore only be used as argument to functions that manipulate multiple
89  * LEDS (e.g. leds_off() and \e not leds_single_off()).
90  *
91  * In terms of porting for new platforms, developers simply have to:
92  *
93  * - Define variables of type leds_t to represent their platform's LEDs
94  * - Specify the number of LEDs on their device by defining LEDS_CONF_COUNT
95  * - Map red colours to numbers (e.g. \#define LEDS_CONF_RED 1)
96  *
97  * \file
98  * Header file for the LED HAL
99  * @{
100  */
101 /*---------------------------------------------------------------------------*/
102 #ifndef LEDS_H_
103 #define LEDS_H_
104 /*---------------------------------------------------------------------------*/
105 #include "contiki.h"
106 #include "dev/gpio-hal.h"
107 
108 #include <stdint.h>
109 #include <stdbool.h>
110 /*---------------------------------------------------------------------------*/
111 #if LEDS_CONF_LEGACY_API
112 /**
113  * \brief Define to 1 to enabled the legacy LED API.
114  */
115 #define LEDS_LEGACY_API LEDS_CONF_LEGACY_API
116 #else
117 #define LEDS_LEGACY_API 0
118 #endif
119 /*---------------------------------------------------------------------------*/
120 /**
121  * \brief A default LED colour for non-existing LEDs
122  */
123 #define LEDS_COLOUR_NONE 0x00
124 /*---------------------------------------------------------------------------*/
125 /* LED colour to number mappings. Applicable to both APIs */
126 #ifdef LEDS_CONF_RED
127 #define LEDS_RED LEDS_CONF_RED
128 #else
129 #define LEDS_RED LEDS_COLOUR_NONE
130 #endif
131 
132 #ifdef LEDS_CONF_GREEN
133 #define LEDS_GREEN LEDS_CONF_GREEN
134 #else
135 #define LEDS_GREEN LEDS_COLOUR_NONE
136 #endif
137 
138 #ifdef LEDS_CONF_BLUE
139 #define LEDS_BLUE LEDS_CONF_BLUE
140 #else
141 #define LEDS_BLUE LEDS_COLOUR_NONE
142 #endif
143 
144 #ifdef LEDS_CONF_YELLOW
145 #define LEDS_YELLOW LEDS_CONF_YELLOW
146 #else
147 #define LEDS_YELLOW LEDS_COLOUR_NONE
148 #endif
149 
150 #ifdef LEDS_CONF_ORANGE
151 #define LEDS_ORANGE LEDS_CONF_ORANGE
152 #else
153 #define LEDS_ORANGE LEDS_COLOUR_NONE
154 #endif
155 /*---------------------------------------------------------------------------*/
156 /**
157  * \brief The LED number
158  */
159 typedef uint8_t leds_num_t;
160 
161 /**
162  * \brief An OR mask datatype to represents multiple LEDs.
163  */
164 typedef uint8_t leds_mask_t;
165 /*---------------------------------------------------------------------------*/
166 #if LEDS_LEGACY_API
167 /*---------------------------------------------------------------------------*/
168 #ifdef LEDS_CONF_ALL
169 #define LEDS_ALL LEDS_CONF_ALL
170 #else
171 #define LEDS_ALL 7
172 #endif
173 /*---------------------------------------------------------------------------*/
174 void leds_blink(void);
175 
176 /* Legacy LED API arch-specific functions */
177 void leds_arch_init(void);
178 leds_mask_t leds_arch_get(void);
179 void leds_arch_set(leds_mask_t leds);
180 /*---------------------------------------------------------------------------*/
181 #else /* LEDS_LEGACY_API */
182 /*---------------------------------------------------------------------------*/
183 #ifdef LEDS_CONF_COUNT
184 #define LEDS_COUNT LEDS_CONF_COUNT
185 #else
186 /**
187  * \brief The number of LEDs present on a device
188  */
189 #define LEDS_COUNT 0
190 #endif
191 /*---------------------------------------------------------------------------*/
192 /**
193  * \brief The OR mask representation of all device LEDs
194  */
195 #define LEDS_ALL ((1 << LEDS_COUNT) - 1)
196 /*---------------------------------------------------------------------------*/
197 #endif /* LEDS_LEGACY_API */
198 /*---------------------------------------------------------------------------*/
199 #define LEDS_LED1 0x00 /**< Convenience macro to refer to the 1st LED (LED 1) */
200 #define LEDS_LED2 0x01 /**< Convenience macro to refer to the 2nd LED (LED 2) */
201 #define LEDS_LED3 0x02 /**< Convenience macro to refer to the 3rd LED (LED 3) */
202 #define LEDS_LED4 0x03 /**< Convenience macro to refer to the 4th LED (LED 4) */
203 #define LEDS_LED5 0x04 /**< Convenience macro to refer to the 5th LED (LED 5) */
204 /*---------------------------------------------------------------------------*/
205 /**
206  * \brief A LED logical representation
207  *
208  * \e pin corresponds to the GPIO pin a LED is driven by, using GPIO HAL pin
209  * representation.
210  *
211  * \e port corresponds to the GPIO port that the pin is connected to. This
212  * only makes sense if GPIO_HAL_CONF_PORT_PIN_NUMBERING is non-zero.
213  *
214  * \e negative_logic should be set to false if the LED is active low.
215  *
216  * \note Do not access the \e port member of this struct direct, use the
217  * LED_PORT() macro instead.
218  */
219 typedef struct leds_s {
220  gpio_hal_pin_t pin;
221 #if GPIO_HAL_PORT_PIN_NUMBERING
222  gpio_hal_port_t port;
223 #endif
224  bool negative_logic;
225 } leds_t;
226 /*---------------------------------------------------------------------------*/
227 /**
228  * \brief Convert a LED number to a mask representation
229  * \param l The pin number (normally a variable of type leds_num_t)
230  * \return An OR mask of type leds_mask_t
231  */
232 #define LEDS_NUM_TO_MASK(l) (1 << (l))
233 /*---------------------------------------------------------------------------*/
234 /**
235  * \brief Initialise the LED HAL
236  *
237  * This function will set corresponding LED GPIO pins to output and will also
238  * set the initial state of all LEDs to off.
239  */
240 void leds_init(void);
241 
242 /**
243  * \brief Turn a single LED on
244  * \param led The led
245  *
246  * The \e led argument should be the LED's number, in other words one of the
247  * LED_Ln macros.
248  *
249  * This function will not change the state of other LEDs.
250  */
251 void leds_single_on(leds_num_t led);
252 
253 /**
254  * \brief Turn a single LED off
255  * \param led The led
256  *
257  * The \e led argument should be the LED's number, in other words one of the
258  * LED_Ln macros.
259  *
260  * This function will not change the state of other LEDs.
261  */
262 void leds_single_off(leds_num_t led);
263 
264 /**
265  * \brief Toggle a single LED
266  * \param led The led
267  *
268  * The \e led argument should be the LED's number, in other words one of the
269  * LED_Ln macros.
270  *
271  * This function will not change the state of other LEDs.
272  */
274 
275 /**
276  * \brief Turn on multiple LEDs
277  * \param leds The leds to be turned on as an OR mask
278  *
279  * The \e led argument should be a bitwise mask of the LEDs to be changed.
280  * For example, to turn on LEDs 1 and 3, you should pass
281  * LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5
282  *
283  * This function will not change the state of other LEDs.
284  */
285 void leds_on(leds_mask_t leds);
286 
287 /**
288  * \brief Turn off multiple LEDs
289  * \param leds The leds to be turned off as an OR mask
290  *
291  * The \e led argument should be a bitwise mask of the LEDs to be changed.
292  * For example, to turn on LEDs 1 and 3, you should pass
293  * LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5
294  *
295  * This function will not change the state of other LEDs.
296  */
297 void leds_off(leds_mask_t leds);
298 
299 /**
300  * \brief Toggle multiple LEDs
301  * \param leds The leds to be toggled as an OR mask
302  *
303  * The \e led argument should be a bitwise mask of the LEDs to be changed.
304  * For example, to turn on LEDs 1 and 3, you should pass
305  * LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5
306  *
307  * This function will not change the state of other LEDs.
308  */
309 void leds_toggle(leds_mask_t leds);
310 
311 /**
312  * \brief Set all LEDs to a specific state
313  * \param leds The state of all LEDs afer this function returns
314  *
315  * The \e led argument should be a bitwise mask of the LEDs to be changed.
316  * For example, to turn on LEDs 1 and 3, you should pass
317  * LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5
318  *
319  * This function will change the state of all LEDs. LEDs not set in the \e leds
320  * mask will be turned off.
321  */
322 void leds_set(leds_mask_t leds);
323 
324 /**
325  * \brief Get the status of LEDs
326  * \return A bitwise mask indicating whether each individual LED is on or off
327  *
328  * The return value is a bitwise mask. If a bit is set then the corresponding
329  * LED is on.
330  */
331 leds_mask_t leds_get(void);
332 /*---------------------------------------------------------------------------*/
333 #endif /* LEDS_H_ */
334 /*---------------------------------------------------------------------------*/
335 /**
336  * @}
337  * @}
338  */
struct leds_s leds_t
A LED logical representation.
void leds_init(void)
Initialise the LED HAL.
Definition: minileds.c:44
void leds_set(leds_mask_t leds)
Set all LEDs to a specific state.
Definition: leds.c:217
uint8_t gpio_hal_port_t
A data structure that represents ports.
Definition: gpio-hal.h:110
void leds_on(leds_mask_t leds)
Turn on multiple LEDs.
Definition: minileds.c:63
void leds_off(leds_mask_t leds)
Turn off multiple LEDs.
Definition: minileds.c:69
uint8_t gpio_hal_pin_t
GPIO pin number representation.
Definition: gpio-hal.h:103
A LED logical representation.
Definition: leds.h:219
leds_mask_t leds_get(void)
Get the status of LEDs.
Definition: leds.c:224
void leds_single_off(leds_num_t led)
Turn a single LED off.
Definition: leds.c:141
void leds_toggle(leds_mask_t leds)
Toggle multiple LEDs.
Definition: minileds.c:75
void leds_single_toggle(leds_num_t led)
Toggle a single LED.
Definition: leds.c:157
void leds_single_on(leds_num_t led)
Turn a single LED on.
Definition: leds.c:125
Header file for the GPIO HAL.
uint8_t leds_mask_t
An OR mask datatype to represents multiple LEDs.
Definition: leds.h:164
uint8_t leds_num_t
The LED number.
Definition: leds.h:159