nes-proj/os/dev/button-hal.h
2018-08-31 11:04:45 +02:00

272 lines
9.7 KiB
C

/*
* 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 "sys/process.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}; \
const uint8_t button_hal_button_count = \
(sizeof(button_hal_buttons) / sizeof(button_hal_buttons[0])) - 1;
/*---------------------------------------------------------------------------*/
/**
* \brief The number of buttons on a device
*/
extern const uint8_t button_hal_button_count;
/*---------------------------------------------------------------------------*/
/**
* \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);
/**
* \brief Retrieve a button by its index
* \param index The button's index (0, 1, ... button_hal_button_count - 1)
* \return A pointer to the button or NULL if not found
*/
button_hal_button_t *button_hal_get_by_index(uint8_t index);
/**
* \brief Get the state of a button (pressed / released)
* \param button A pointer to the button
* \retval BUTTON_HAL_STATE_RELEASED The button is currently released
* \retval BUTTON_HAL_STATE_PRESSED The button is currently pressed
*/
uint8_t button_hal_get_state(button_hal_button_t *button);
/*---------------------------------------------------------------------------*/
#endif /* BUTTON_HAL_H_ */
/*---------------------------------------------------------------------------*/
/**
* @}
* @}
*/