Introduce platform-independent HAL for buttons
This commit is contained in:
George Oikonomou
parent
6d57dd0e7e
commit
934856b4fd
192
os/dev/button-hal.c
Normal file
192
os/dev/button-hal.c
Normal file
@ -0,0 +1,192 @@
|
||||
/*
|
||||
* Copyright (c) 2017, George Oikonomou - http://www.spd.gr
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions
|
||||
* are met:
|
||||
*
|
||||
* 1. Redistributions of source code must retain the above copyright
|
||||
* notice, this list of conditions and the following disclaimer.
|
||||
* 2. Redistributions in binary form must reproduce the above copyright
|
||||
* notice, this list of conditions and the following disclaimer in the
|
||||
* documentation and/or other materials provided with the distribution.
|
||||
* 3. Neither the name of the copyright holder nor the names of its
|
||||
* contributors may be used to endorse or promote products derived
|
||||
* from this software without specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
||||
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
||||
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
||||
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
* OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
*/
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \addtogroup button_hal
|
||||
* @{
|
||||
*
|
||||
* \file
|
||||
* Platform-independent button driver.
|
||||
*/
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#include "contiki.h"
|
||||
#include "sys/process.h"
|
||||
#include "sys/ctimer.h"
|
||||
#include "dev/gpio-hal.h"
|
||||
#include "dev/button-hal.h"
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stdbool.h>
|
||||
#include <string.h>
|
||||
/*---------------------------------------------------------------------------*/
|
||||
process_event_t button_hal_press_event;
|
||||
process_event_t button_hal_release_event;
|
||||
process_event_t button_hal_periodic_event;
|
||||
/*---------------------------------------------------------------------------*/
|
||||
extern button_hal_button_t *button_hal_buttons[];
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Common handler for all handler events, and register it with the GPIO HAL */
|
||||
static gpio_hal_event_handler_t button_event_handler;
|
||||
/*---------------------------------------------------------------------------*/
|
||||
static uint8_t
|
||||
get_state(button_hal_button_t *button)
|
||||
{
|
||||
uint8_t pin_state = gpio_hal_arch_read_pin(button->pin);
|
||||
|
||||
if((pin_state == 0 && button->negative_logic == true) ||
|
||||
(pin_state == 1 && button->negative_logic == false)) {
|
||||
return BUTTON_HAL_STATE_PRESSED;
|
||||
}
|
||||
|
||||
return BUTTON_HAL_STATE_RELEASED;
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
static void
|
||||
duration_exceeded_callback(void *btn)
|
||||
{
|
||||
button_hal_button_t *button = (button_hal_button_t *)btn;
|
||||
|
||||
button->press_duration_seconds++;
|
||||
ctimer_set(&button->duration_ctimer, CLOCK_SECOND,
|
||||
duration_exceeded_callback, button);
|
||||
process_post(PROCESS_BROADCAST, button_hal_periodic_event, button);
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
static void
|
||||
debounce_handler(void *btn)
|
||||
{
|
||||
button_hal_button_t *button;
|
||||
int expired;
|
||||
uint8_t button_state;
|
||||
|
||||
button = (button_hal_button_t *)btn;
|
||||
|
||||
/*
|
||||
* A new debounce may have been triggered after expiration of the previous
|
||||
* one but before we got called.
|
||||
*/
|
||||
if(!ctimer_expired(&button->debounce_ctimer)) {
|
||||
return;
|
||||
}
|
||||
|
||||
expired = ctimer_expired(&button->duration_ctimer);
|
||||
|
||||
button_state = get_state(button);
|
||||
|
||||
/*
|
||||
* A debounce timer expired. Inspect the button's state. If the button's
|
||||
* state is the same as it was before, then we ignore this as noise.
|
||||
*/
|
||||
if(button_state == BUTTON_HAL_STATE_PRESSED && expired) {
|
||||
/*
|
||||
* Button is pressed and no tick counter running. Treat as new press.
|
||||
* Include the debounce duration in the first periodic, so that the
|
||||
* callback will happen 1 second after the button press, not 1 second
|
||||
* after the end of the debounce. Notify process about the press event.
|
||||
*/
|
||||
button->press_duration_seconds = 0;
|
||||
ctimer_set(&button->duration_ctimer,
|
||||
CLOCK_SECOND - BUTTON_HAL_DEBOUNCE_DURATION,
|
||||
duration_exceeded_callback, button);
|
||||
process_post(PROCESS_BROADCAST, button_hal_press_event, button);
|
||||
} else if(button_state == BUTTON_HAL_STATE_RELEASED && expired == 0) {
|
||||
/*
|
||||
* Button is released and there is a duration_ctimer running. Treat this
|
||||
* as a new release and notify processes.
|
||||
*/
|
||||
ctimer_stop(&button->duration_ctimer);
|
||||
process_post(PROCESS_BROADCAST, button_hal_release_event, button);
|
||||
}
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
static void
|
||||
press_release_handler(gpio_hal_pin_mask_t pin_mask)
|
||||
{
|
||||
button_hal_button_t **button;
|
||||
|
||||
for(button = button_hal_buttons; *button != NULL; button++) {
|
||||
if(gpio_hal_pin_to_mask((*button)->pin) & pin_mask) {
|
||||
/* Ignore all button presses/releases during its debounce */
|
||||
if(ctimer_expired(&(*button)->debounce_ctimer)) {
|
||||
/*
|
||||
* Here we merely set a debounce timer. At the end of the debounce we
|
||||
* will inspect the button's state and we will take action only if it
|
||||
* has changed.
|
||||
*
|
||||
* This is to prevent erroneous edge detections due to interference.
|
||||
*/
|
||||
ctimer_set(&(*button)->debounce_ctimer, BUTTON_HAL_DEBOUNCE_DURATION,
|
||||
debounce_handler, *button);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
button_hal_button_t *
|
||||
button_hal_get_by_id(uint8_t unique_id)
|
||||
{
|
||||
button_hal_button_t **button;
|
||||
|
||||
for(button = button_hal_buttons; *button != NULL; button++) {
|
||||
if((*button)->unique_id == unique_id) {
|
||||
return (*button);
|
||||
}
|
||||
}
|
||||
|
||||
return NULL;
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
void
|
||||
button_hal_init()
|
||||
{
|
||||
button_hal_button_t **button;
|
||||
gpio_hal_pin_cfg_t cfg;
|
||||
|
||||
button_hal_press_event = process_alloc_event();
|
||||
button_hal_release_event = process_alloc_event();
|
||||
button_hal_periodic_event = process_alloc_event();
|
||||
|
||||
button_event_handler.pin_mask = 0;
|
||||
button_event_handler.handler = press_release_handler;
|
||||
|
||||
for(button = button_hal_buttons; *button != NULL; button++) {
|
||||
cfg = GPIO_HAL_PIN_CFG_EDGE_BOTH | GPIO_HAL_PIN_CFG_INT_ENABLE |
|
||||
(*button)->pull;
|
||||
gpio_hal_arch_pin_set_input((*button)->pin);
|
||||
gpio_hal_arch_pin_cfg_set((*button)->pin, cfg);
|
||||
gpio_hal_arch_interrupt_enable((*button)->pin);
|
||||
button_event_handler.pin_mask |= gpio_hal_pin_to_mask((*button)->pin);
|
||||
}
|
||||
|
||||
gpio_hal_register_handler(&button_event_handler);
|
||||
}
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @} */
|
||||
248
os/dev/button-hal.h
Normal file
248
os/dev/button-hal.h
Normal file
@ -0,0 +1,248 @@
|
||||
/*
|
||||
* Copyright (c) 2017, George Oikonomou - http://www.spd.gr
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions
|
||||
* are met:
|
||||
*
|
||||
* 1. Redistributions of source code must retain the above copyright
|
||||
* notice, this list of conditions and the following disclaimer.
|
||||
* 2. Redistributions in binary form must reproduce the above copyright
|
||||
* notice, this list of conditions and the following disclaimer in the
|
||||
* documentation and/or other materials provided with the distribution.
|
||||
* 3. Neither the name of the copyright holder nor the names of its
|
||||
* contributors may be used to endorse or promote products derived
|
||||
* from this software without specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
||||
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
||||
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
||||
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
* OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
*/
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \addtogroup dev
|
||||
* @{
|
||||
*/
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \defgroup button_hal Button HAL
|
||||
*
|
||||
* Hardware abstraction layer for user buttons.
|
||||
*
|
||||
* This HAL enables an abstraction of general-purpose / user buttons or
|
||||
* similar peripherals (e.g. a reed relay can also be abstracted through this
|
||||
* HAL). The HAL handles software debounce timers internally, therefore the
|
||||
* platform-specific button driver does not need to worry about debouncing.
|
||||
*
|
||||
* The platform developer needs to define a variable of type
|
||||
* \c button_hal_button_t for each user button. Within this variable, the
|
||||
* developer needs to specify the GPIO pin where the button is attached,
|
||||
* whether the button uses negative logic, and whether the GPIO pin should
|
||||
* be configured with internal pullup/down. The developer also needs to provide
|
||||
* a unique index for each button, as well as a description.
|
||||
*
|
||||
* With those in place, the HAL will generate the following process events:
|
||||
*
|
||||
* - button_hal_press_event: Upon press of the button
|
||||
* - button_hal_release_event: Upon release of the button
|
||||
* - button_hal_periodic_event: Generated every second that the user button is
|
||||
* kept pressed.
|
||||
*
|
||||
* With those events in place, an application can perform an action:
|
||||
*
|
||||
* - Immediately after the button gets pressed.
|
||||
* - After the button has been pressed for N seconds.
|
||||
* - Immediately upon release of the button. This action can vary depending
|
||||
* on how long the button had been pressed for.
|
||||
*
|
||||
* A platform with user buttons can either implement this API (recommended) or
|
||||
* the older button_sensor API. Some examples will not work if this API is not
|
||||
* implemented.
|
||||
*
|
||||
* This API requires the platform to first support the GPIO HAL API.
|
||||
* @{
|
||||
*
|
||||
* \file
|
||||
* Header file for the button HAL
|
||||
*/
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#ifndef BUTTON_HAL_H_
|
||||
#define BUTTON_HAL_H_
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#include "contiki.h"
|
||||
#include "dev/gpio-hal.h"
|
||||
#include "sys/clock.h"
|
||||
#include "sys/ctimer.h"
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stdbool.h>
|
||||
#include <string.h>
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \brief Controls the software debounce timer duration.
|
||||
*
|
||||
* The platform can provide a more suitable value. This value will apply to
|
||||
* all buttons.
|
||||
*/
|
||||
#ifdef BUTTON_HAL_CONF_DEBOUNCE_DURATION
|
||||
#define BUTTON_HAL_DEBOUNCE_DURATION BUTTON_HAL_CONF_DEBOUNCE_DURATION
|
||||
#else
|
||||
#define BUTTON_HAL_DEBOUNCE_DURATION (CLOCK_SECOND >> 6)
|
||||
#endif
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \brief Controls whether buttons will have human-readable names
|
||||
*
|
||||
* Define this to zero to save code space
|
||||
*/
|
||||
#if BUTTON_HAL_CONF_WITH_DESCRIPTION
|
||||
#define BUTTON_HAL_WITH_DESCRIPTION BUTTON_HAL_CONF_WITH_DESCRIPTION
|
||||
#else
|
||||
#define BUTTON_HAL_WITH_DESCRIPTION 1
|
||||
#endif
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#define BUTTON_HAL_STATE_RELEASED 0
|
||||
#define BUTTON_HAL_STATE_PRESSED 1
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* Optional button IDs
|
||||
*/
|
||||
#define BUTTON_HAL_ID_BUTTON_ZERO 0x00
|
||||
#define BUTTON_HAL_ID_BUTTON_ONE 0x01
|
||||
#define BUTTON_HAL_ID_BUTTON_TWO 0x02
|
||||
#define BUTTON_HAL_ID_BUTTON_THREE 0x03
|
||||
#define BUTTON_HAL_ID_BUTTON_FOUR 0x04
|
||||
#define BUTTON_HAL_ID_BUTTON_FIVE 0x05
|
||||
|
||||
#define BUTTON_HAL_ID_USER_BUTTON BUTTON_HAL_ID_BUTTON_ZERO
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \brief A logical representation of a user button
|
||||
*/
|
||||
typedef struct button_hal_button_s button_hal_button_t;
|
||||
|
||||
struct button_hal_button_s {
|
||||
/** Used by the s/w debounce functionality */
|
||||
struct ctimer debounce_ctimer;
|
||||
|
||||
/** A callback timer used to count duration of button presses */
|
||||
struct ctimer duration_ctimer;
|
||||
|
||||
#if BUTTON_HAL_WITH_DESCRIPTION
|
||||
/**
|
||||
* \brief A textual description of the button
|
||||
*
|
||||
* This field may only be accessed using the BUTTON_HAL_GET_DESCRIPTION()
|
||||
* macro.
|
||||
*/
|
||||
const char *description;
|
||||
#endif
|
||||
|
||||
/** True if the button uses negative logic (active: low) */
|
||||
const bool negative_logic;
|
||||
|
||||
/** The gpio pin connected to the button */
|
||||
const gpio_hal_pin_t pin;
|
||||
|
||||
/** The pin's pull configuration */
|
||||
const gpio_hal_pin_cfg_t pull;
|
||||
|
||||
/** A counter of the duration (in seconds) of a button press */
|
||||
uint8_t press_duration_seconds;
|
||||
|
||||
/**
|
||||
* \brief A unique identifier for this button.
|
||||
*
|
||||
* The platform code is responsible of setting unique values here. This can
|
||||
* be used later to determine which button generated an event. Many examples
|
||||
* assume the existence of a button with ID == BUTTON_HAL_ID_BUTTON_ZERO,
|
||||
* so it is good idea to use this ID for one of your platform's buttons.
|
||||
*/
|
||||
const uint8_t unique_id;
|
||||
};
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#if BUTTON_HAL_WITH_DESCRIPTION
|
||||
/**
|
||||
* \brief Define a button to be used by the HAL
|
||||
* \param name The variable name for the button
|
||||
* \param descr A textual description
|
||||
* \param p The pin connected to the button
|
||||
* \param nl True if the button is connected using negative logic
|
||||
* \param u The button's pull configuration
|
||||
* \param id A unique numeric identifier
|
||||
*/
|
||||
#define BUTTON_HAL_BUTTON(name, descr, p, u, id, nl) \
|
||||
static button_hal_button_t name = { \
|
||||
.description = descr, \
|
||||
.pin = p, \
|
||||
.pull = u, \
|
||||
.unique_id = id, \
|
||||
.negative_logic = nl, \
|
||||
}
|
||||
|
||||
/**
|
||||
* \brief Retrieve the textual description of a button
|
||||
* \param b A pointer to the button button_hal_button_t
|
||||
*
|
||||
* This macro will return the value of the description field for b. If
|
||||
* BUTTON_HAL_WITH_DESCRIPTION is 0 then this macro will return ""
|
||||
*/
|
||||
#define BUTTON_HAL_GET_DESCRIPTION(b) (b)->description
|
||||
#else
|
||||
#define BUTTON_HAL_BUTTON(name, descr, p, u, id, nl) \
|
||||
static button_hal_button_t name = { \
|
||||
.pin = p, \
|
||||
.pull = u, \
|
||||
.unique_id = id, \
|
||||
.negative_logic = nl, \
|
||||
}
|
||||
|
||||
#define BUTTON_HAL_GET_DESCRIPTION(b) ""
|
||||
#endif
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#define BUTTON_HAL_BUTTONS(...) \
|
||||
button_hal_button_t *button_hal_buttons[] = {__VA_ARGS__, NULL};
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \brief A broadcast event generated when a button gets pressed
|
||||
*/
|
||||
extern process_event_t button_hal_press_event;
|
||||
|
||||
/**
|
||||
* \brief A broadcast event generated when a button gets released
|
||||
*/
|
||||
extern process_event_t button_hal_release_event;
|
||||
|
||||
/**
|
||||
* \brief A broadcast event generated every second while a button is kept pressed
|
||||
*/
|
||||
extern process_event_t button_hal_periodic_event;
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* \brief Initialise the button HAL
|
||||
*/
|
||||
void button_hal_init(void);
|
||||
|
||||
/**
|
||||
* \brief Retrieve a button by ID
|
||||
* \param unique_id The button unique ID to search for
|
||||
* \return A pointer to the button or NULL if not found
|
||||
*/
|
||||
button_hal_button_t *button_hal_get_by_id(uint8_t unique_id);
|
||||
/*---------------------------------------------------------------------------*/
|
||||
#endif /* BUTTON_HAL_H_ */
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/**
|
||||
* @}
|
||||
* @}
|
||||
*/
|
||||
Loading…
Reference in New Issue
Block a user