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 */
159typedef uint8_t leds_num_t;
160
161/**
162 * \brief An OR mask datatype to represents multiple LEDs.
163 */
164typedef 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/*---------------------------------------------------------------------------*/
174void leds_blink(void);
175
176/* Legacy LED API arch-specific functions */
177void leds_arch_init(void);
178leds_mask_t leds_arch_get(void);
179void 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 */
219typedef 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;
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 */
240void 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 */
251void 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 */
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 */
285void 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 */
297void 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 */
309void 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 */
322void 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 */
332/*---------------------------------------------------------------------------*/
333#endif /* LEDS_H_ */
334/*---------------------------------------------------------------------------*/
335/**
336 * @}
337 * @}
338 */
Header file for the GPIO HAL.
leds_mask_t leds_get(void)
Get the status of LEDs.
Definition: leds.c:224
void leds_single_on(leds_num_t led)
Turn a single LED on.
Definition: leds.c:125
void leds_single_toggle(leds_num_t led)
Toggle a single LED.
Definition: leds.c:157
void leds_init(void)
Initialise the LED HAL.
Definition: minileds.c:44
void leds_on(leds_mask_t leds)
Turn on multiple LEDs.
Definition: leds.c:168
void leds_single_off(leds_num_t led)
Turn a single LED off.
Definition: leds.c:141
uint8_t leds_mask_t
An OR mask datatype to represents multiple LEDs.
Definition: leds.h:164
void leds_off(leds_mask_t leds)
Turn off multiple LEDs.
Definition: leds.c:186
void leds_toggle(leds_mask_t leds)
Toggle multiple LEDs.
Definition: leds.c:204
uint8_t leds_num_t
The LED number.
Definition: leds.h:159
void leds_set(leds_mask_t leds)
Set all LEDs to a specific state.
Definition: leds.c:217
struct leds_s leds_t
A LED logical representation.
uint8_t gpio_hal_port_t
A data structure that represents ports.
Definition: gpio-hal.h:110
uint8_t gpio_hal_pin_t
GPIO pin number representation.
Definition: gpio-hal.h:103
A LED logical representation.
Definition: leds.h:219