Contiki-NG
button-hal.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, George Oikonomou - http://www.spd.gr
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived
16  * from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
29  * OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31 /*---------------------------------------------------------------------------*/
32 /**
33  * \addtogroup dev
34  * @{
35  */
36 /*---------------------------------------------------------------------------*/
37 /**
38  * \defgroup button_hal Button HAL
39  *
40  * Hardware abstraction layer for user buttons.
41  *
42  * This HAL enables an abstraction of general-purpose / user buttons or
43  * similar peripherals (e.g. a reed relay can also be abstracted through this
44  * HAL). The HAL handles software debounce timers internally, therefore the
45  * platform-specific button driver does not need to worry about debouncing.
46  *
47  * The platform developer needs to define a variable of type
48  * \c button_hal_button_t for each user button. Within this variable, the
49  * developer needs to specify the GPIO pin where the button is attached,
50  * whether the button uses negative logic, and whether the GPIO pin should
51  * be configured with internal pullup/down. The developer also needs to provide
52  * a unique index for each button, as well as a description.
53  *
54  * With those in place, the HAL will generate the following process events:
55  *
56  * - button_hal_press_event: Upon press of the button
57  * - button_hal_release_event: Upon release of the button
58  * - button_hal_periodic_event: Generated every second that the user button is
59  * kept pressed.
60  *
61  * With those events in place, an application can perform an action:
62  *
63  * - Immediately after the button gets pressed.
64  * - After the button has been pressed for N seconds.
65  * - Immediately upon release of the button. This action can vary depending
66  * on how long the button had been pressed for.
67  *
68  * A platform with user buttons can either implement this API (recommended) or
69  * the older button_sensor API. Some examples will not work if this API is not
70  * implemented.
71  *
72  * This API requires the platform to first support the GPIO HAL API.
73  * @{
74  *
75  * \file
76  * Header file for the button HAL
77  */
78 /*---------------------------------------------------------------------------*/
79 #ifndef BUTTON_HAL_H_
80 #define BUTTON_HAL_H_
81 /*---------------------------------------------------------------------------*/
82 #include "contiki.h"
83 #include "dev/gpio-hal.h"
84 #include "sys/clock.h"
85 #include "sys/ctimer.h"
86 
87 #include <stdint.h>
88 #include <stdbool.h>
89 #include <string.h>
90 /*---------------------------------------------------------------------------*/
91 /**
92  * \brief Controls the software debounce timer duration.
93  *
94  * The platform can provide a more suitable value. This value will apply to
95  * all buttons.
96  */
97 #ifdef BUTTON_HAL_CONF_DEBOUNCE_DURATION
98 #define BUTTON_HAL_DEBOUNCE_DURATION BUTTON_HAL_CONF_DEBOUNCE_DURATION
99 #else
100 #define BUTTON_HAL_DEBOUNCE_DURATION (CLOCK_SECOND >> 6)
101 #endif
102 /*---------------------------------------------------------------------------*/
103 /**
104  * \brief Controls whether buttons will have human-readable names
105  *
106  * Define this to zero to save code space
107  */
108 #if BUTTON_HAL_CONF_WITH_DESCRIPTION
109 #define BUTTON_HAL_WITH_DESCRIPTION BUTTON_HAL_CONF_WITH_DESCRIPTION
110 #else
111 #define BUTTON_HAL_WITH_DESCRIPTION 1
112 #endif
113 /*---------------------------------------------------------------------------*/
114 #define BUTTON_HAL_STATE_RELEASED 0
115 #define BUTTON_HAL_STATE_PRESSED 1
116 /*---------------------------------------------------------------------------*/
117 /**
118  * Optional button IDs
119  */
120 #define BUTTON_HAL_ID_BUTTON_ZERO 0x00
121 #define BUTTON_HAL_ID_BUTTON_ONE 0x01
122 #define BUTTON_HAL_ID_BUTTON_TWO 0x02
123 #define BUTTON_HAL_ID_BUTTON_THREE 0x03
124 #define BUTTON_HAL_ID_BUTTON_FOUR 0x04
125 #define BUTTON_HAL_ID_BUTTON_FIVE 0x05
126 
127 #define BUTTON_HAL_ID_USER_BUTTON BUTTON_HAL_ID_BUTTON_ZERO
128 /*---------------------------------------------------------------------------*/
129 /**
130  * \brief A logical representation of a user button
131  */
132 typedef struct button_hal_button_s button_hal_button_t;
133 
134 struct button_hal_button_s {
135  /** Used by the s/w debounce functionality */
136  struct ctimer debounce_ctimer;
137 
138  /** A callback timer used to count duration of button presses */
139  struct ctimer duration_ctimer;
140 
141 #if BUTTON_HAL_WITH_DESCRIPTION
142  /**
143  * \brief A textual description of the button
144  *
145  * This field may only be accessed using the BUTTON_HAL_GET_DESCRIPTION()
146  * macro.
147  */
148  const char *description;
149 #endif
150 
151  /** True if the button uses negative logic (active: low) */
152  const bool negative_logic;
153 
154 #if GPIO_HAL_PORT_PIN_NUMBERING
155  /** The gpio port connected to the button */
156  gpio_hal_port_t port;
157 #endif
158 
159  /** The gpio pin connected to the button */
160  const gpio_hal_pin_t pin;
161 
162  /** The pin's pull configuration */
163  const gpio_hal_pin_cfg_t pull;
164 
165  /** A counter of the duration (in seconds) of a button press */
166  uint8_t press_duration_seconds;
167 
168  /**
169  * \brief A unique identifier for this button.
170  *
171  * The platform code is responsible of setting unique values here. This can
172  * be used later to determine which button generated an event. Many examples
173  * assume the existence of a button with ID == BUTTON_HAL_ID_BUTTON_ZERO,
174  * so it is good idea to use this ID for one of your platform's buttons.
175  */
176  const uint8_t unique_id;
177 };
178 /*---------------------------------------------------------------------------*/
179 #if BUTTON_HAL_WITH_DESCRIPTION
180 #if GPIO_HAL_PORT_PIN_NUMBERING
181 /**
182  * \brief Define a button to be used by the HAL
183  * \param name The variable name for the button
184  * \param descr A textual description
185  * \param po The port connected to the button
186  * \param pi The pin connected to the button
187  * \param nl True if the button is connected using negative logic
188  * \param u The button's pull configuration
189  * \param id A unique numeric identifier
190  */
191 #define BUTTON_HAL_BUTTON(name, descr, po, pi, u, id, nl) \
192  static button_hal_button_t name = { \
193  .description = descr, \
194  .port = po, \
195  .pin = pi, \
196  .pull = u, \
197  .unique_id = id, \
198  .negative_logic = nl, \
199  }
200 #else /* GPIO_HAL_PORT_PIN_NUMBERING */
201 #define BUTTON_HAL_BUTTON(name, descr, pi, u, id, nl) \
202  static button_hal_button_t name = { \
203  .description = descr, \
204  .pin = pi, \
205  .pull = u, \
206  .unique_id = id, \
207  .negative_logic = nl, \
208  }
209 #endif /* GPIO_HAL_PORT_PIN_NUMBERING */
210 
211 /**
212  * \brief Retrieve the textual description of a button
213  * \param b A pointer to the button button_hal_button_t
214  *
215  * This macro will return the value of the description field for b. If
216  * BUTTON_HAL_WITH_DESCRIPTION is 0 then this macro will return ""
217  */
218 #define BUTTON_HAL_GET_DESCRIPTION(b) (b)->description
219 
220 #else /* BUTTON_HAL_WITH_DESCRIPTION */
221 
222 #if GPIO_HAL_PORT_PIN_NUMBERING
223 #define BUTTON_HAL_BUTTON(name, descr, po, pi, u, id, nl) \
224  static button_hal_button_t name = { \
225  .port = po, \
226  .pin = pi, \
227  .pull = u, \
228  .unique_id = id, \
229  .negative_logic = nl, \
230  }
231 #else /* GPIO_HAL_PORT_PIN_NUMBERING */
232 #define BUTTON_HAL_BUTTON(name, descr, pi, u, id, nl) \
233  static button_hal_button_t name = { \
234  .pin = pi, \
235  .pull = u, \
236  .unique_id = id, \
237  .negative_logic = nl, \
238  }
239 #endif /* GPIO_HAL_PORT_PIN_NUMBERING */
240 
241 #define BUTTON_HAL_GET_DESCRIPTION(b) ""
242 #endif /* BUTTON_HAL_WITH_DESCRIPTION */
243 /*---------------------------------------------------------------------------*/
244 #define BUTTON_HAL_BUTTONS(...) \
245  button_hal_button_t *button_hal_buttons[] = {__VA_ARGS__, NULL}; \
246  const uint8_t button_hal_button_count = \
247  (sizeof(button_hal_buttons) / sizeof(button_hal_buttons[0])) - 1;
248 /*---------------------------------------------------------------------------*/
249 /**
250  * \brief The number of buttons on a device
251  */
252 extern const uint8_t button_hal_button_count;
253 /*---------------------------------------------------------------------------*/
254 /**
255  * \brief A broadcast event generated when a button gets pressed
256  */
257 extern process_event_t button_hal_press_event;
258 
259 /**
260  * \brief A broadcast event generated when a button gets released
261  */
262 extern process_event_t button_hal_release_event;
263 
264 /**
265  * \brief A broadcast event generated every second while a button is kept pressed
266  */
267 extern process_event_t button_hal_periodic_event;
268 /*---------------------------------------------------------------------------*/
269 /**
270  * \brief Initialise the button HAL
271  */
272 void button_hal_init(void);
273 
274 /**
275  * \brief Retrieve a button by ID
276  * \param unique_id The button unique ID to search for
277  * \return A pointer to the button or NULL if not found
278  */
279 button_hal_button_t *button_hal_get_by_id(uint8_t unique_id);
280 
281 /**
282  * \brief Retrieve a button by its index
283  * \param index The button's index (0, 1, ... button_hal_button_count - 1)
284  * \return A pointer to the button or NULL if not found
285  */
287 
288 /**
289  * \brief Get the state of a button (pressed / released)
290  * \param button A pointer to the button
291  * \retval BUTTON_HAL_STATE_RELEASED The button is currently released
292  * \retval BUTTON_HAL_STATE_PRESSED The button is currently pressed
293  */
295 /*---------------------------------------------------------------------------*/
296 #endif /* BUTTON_HAL_H_ */
297 /*---------------------------------------------------------------------------*/
298 /**
299  * @}
300  * @}
301  */
process_event_t button_hal_periodic_event
A broadcast event generated every second while a button is kept pressed.
Definition: button-hal.c:55
button_hal_button_t * button_hal_get_by_id(uint8_t unique_id)
Retrieve a button by ID.
Definition: button-hal.c:141
process_event_t button_hal_release_event
A broadcast event generated when a button gets released.
Definition: button-hal.c:54
button_hal_button_t * button_hal_get_by_index(uint8_t index)
Retrieve a button by its index.
Definition: button-hal.c:155
uint8_t gpio_hal_port_t
A data structure that represents ports.
Definition: gpio-hal.h:110
uint8_t button_hal_get_state(button_hal_button_t *button)
Get the state of a button (pressed / released)
Definition: button-hal.c:165
const uint8_t button_hal_button_count
The number of buttons on a device.
Definition: buttons.c:39
Header file for the callback timer
process_event_t button_hal_press_event
A broadcast event generated when a button gets pressed.
Definition: button-hal.c:53
uint8_t gpio_hal_pin_t
GPIO pin number representation.
Definition: gpio-hal.h:103
struct button_hal_button_s button_hal_button_t
A logical representation of a user button.
Definition: button-hal.h:132
Header file for the GPIO HAL.
void button_hal_init()
Initialise the button HAL.
Definition: button-hal.c:178
uint32_t gpio_hal_pin_cfg_t
GPIO pin configuration.
Definition: gpio-hal.h:118