button.h

Go to the documentation of this file.

// ---------------------------------------------------------------------------+
//                  This file is part of SLS AVR Library
//              https://github.com/SimonLitt/sls-avr-lib
// ---------------------------------------------------------------------------+
// Copyright (C) 2025 Simon Litt <simon@1itt.net> https://coding.1itt.net,
//                                                https://github.com/SimonLitt
//
// This program is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation, version 3.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License along
// with this program. If not, see <https://www.gnu.org/licenses/>.
// ---------------------------------------------------------------------------+
#ifndef SLS_AVR_SINGLE_BUTTON_H_
#define SLS_AVR_SINGLE_BUTTON_H_
 
#include <string.h>
#include <stdint.h>
#include <util/atomic.h>
#include <sls-avr/avr.h>
 
#define BTN_MAX_SCAN_COUNT 254U 
 
#ifndef BTN_LONG_COUNT
#   define BTN_LONG_COUNT 40U 
#   if (BTN_LONG_COUNT > BTN_MAX_SCAN_COUNT)
#       error "Long Pressed state counter should be less or equal to 254!"
#   endif
#   if (BTN_LONG_COUNT <= BTN_DOWN_COUNT)
#       error "Long Pressed state counter should be more then #BTN_DOWN_COUNT!"
#   endif
#endif // BTN_LONG_COUNT
 
#ifndef BTN_ALLOW_LONG
#   define BTN_ALLOW_LONG 0 
#endif // BTN_ALLOW_LONG
 
#ifndef BTN_RESET_UNUSED_COUNT
#   define BTN_RESET_UNUSED_COUNT 0 
#endif // BTN_RESET_UNUSED_COUNT
#if (BTN_RESET_UNUSED_COUNT < 0) || (BTN_RESET_UNUSED_COUNT > BTN_MAX_SCAN_COUNT)
#   error "Reset counter should be in range 0-254!"
#endif
 
#ifndef BTN_DOWN_COUNT
#define BTN_DOWN_COUNT 3U 
#endif // BTN_DOWN_COUNT
 
#if (BTN_DOWN_COUNT < 1) || (BTN_DOWN_COUNT > BTN_MAX_SCAN_COUNT)
#   error "Pressed state counter should be in range 2-254!"
#endif
 
#ifndef BTN_UP_COUNT
#   define BTN_UP_COUNT 2U 
#endif // BTN_UP_COUNT
#if (BTN_UP_COUNT < 0) || (BTN_UP_COUNT > BTN_MAX_SCAN_COUNT)
#   error "Released state counter should be in range 1-254!"
#endif

#if !BTN_UP_COUNT
#   if BTN_ALLOW_LONG
#       error "Long presses are incompatible with fast processing!"
#   endif
#   define __BTN_ALLOW_FAST_SCAN
#endif
 
#ifndef BTN_FAST_SOME_CODE
#   define BTN_FAST_SOME_CODE 0 
#endif // BTN_FAST_SOME_CODE

#if BTN_FAST_SOME_CODE && (defined(__BTN_ALLOW_FAST_SCAN) || !BTN_ALLOW_LONG)
#   define  __BTN_LONG_DEFINITIONS
#endif

// ---------------------------------------------------------------------------+
// state flags
// ---------------------------------------------------------------------------+
#define __BTN_STAGE_MAY_SHORT_BIT           0
#if BTN_ALLOW_LONG
#   define  __BTN_STAGE_MAY_LONG_BIT        1
#endif // BTN_ALLOW_LONG
#define __BTN_STAGE_PROCESSED_BIT           2
//#define   __BTN_STAGE_UNUSED_BIT          3
#define __BTN_STATE_SHORT_CLICK_BIT         4
#if BTN_ALLOW_LONG
#   define  __BTN_STATE_LONG_CLICK_BIT      5
#endif // BTN_ALLOW_LONG
//#define   __BTN_STAGE_UNUSED_BIT          6
//#define   __BTN_STAGE_UNUSED_BIT          7
 
// Stages of click processing
#define _BTN_STAGE_MAY_SHORT                (_BV(__BTN_STAGE_MAY_SHORT_BIT)) 
#define _BTN_STAGE_MAY_LONG                 (_BV(__BTN_STAGE_MAY_LONG_BIT)) 
#define _BTN_STAGE_PROCESSED                (_BV(__BTN_STAGE_PROCESSED_BIT)) 
 
// States of a button
#define _BTN_STATE_SHORT_CLICK              (_BV(__BTN_STATE_SHORT_CLICK_BIT)) 
#if BTN_ALLOW_LONG
#   define _BTN_STATE_LONG_CLICK            (_BV(__BTN_STATE_LONG_CLICK_BIT)) 
#endif // BTN_ALLOW_LONG
 
#if BTN_ALLOW_LONG
#   define __BTN_IS_CLICKED                 (_BTN_STATE_SHORT_CLICK | _BTN_STATE_LONG_CLICK)
#   define __BTN_IS_HOLDED                  (_BTN_STAGE_MAY_SHORT | _BTN_STAGE_MAY_LONG)
#else
#   define __BTN_IS_CLICKED                 _BTN_STATE_SHORT_CLICK
#   define __BTN_IS_HOLDED                  _BTN_STAGE_MAY_SHORT
#endif // BTN_ALLOW_LONG


typedef struct {
    uint8_t _counter;   
    #ifndef __BTN_ALLOW_FAST_SCAN
    uint8_t _up_counter; 
    #endif // __BTN_ALLOW_FAST_SCAN
    byte_t state;        
} btn_info_struct;
 
typedef volatile btn_info_struct btn_info_t; 
 
#define BTN_INFO_STATE_DEFAULT 0 
 
#ifndef __BTN_ALLOW_FAST_SCAN
#   define BTN_INFO_STRUCT_DEFAULT {._counter = 0, ._up_counter = 0, .state = BTN_INFO_STATE_DEFAULT} 
#else
#   define BTN_INFO_STRUCT_DEFAULT {._counter = 0, .state = BTN_INFO_STATE_DEFAULT}
#endif // __BTN_ALLOW_FAST_SCAN
#define btn_is_holded(_state) ((_state) & (__BTN_IS_HOLDED))

#define btn_is_ready(_state) ((_state) & (__BTN_IS_CLICKED))
#define btn_is_clicked(_state) (flag_is_set((_state), __BTN_STATE_SHORT_CLICK_BIT))
 
#if defined(__DOXYGEN__)
#   define btn_is_long_clicked(_state)
#endif // __DOXYGEN__
 
#if BTN_ALLOW_LONG
#   define btn_is_long_clicked(_state) (flag_is_set((_state), __BTN_STATE_LONG_CLICK_BIT))
#elifdef __BTN_LONG_DEFINITIONS
#   define btn_is_long_clicked(_state) false
#endif // BTN_ALLOW_LONG
#define btn_set_processed(_state) ((_state) = ((_state) & ~(__BTN_IS_CLICKED)) | _BTN_STAGE_PROCESSED)
 
#ifndef BTN_ATOMIC_FUNCTIONS
#   define BTN_ATOMIC_FUNCTIONS 0 
#endif // BTN_ATOMIC_FUNCTIONS

static inline void _btn_reset(btn_info_t *const btn_info) {
    static const btn_info_struct _def_btn_info_struct = BTN_INFO_STRUCT_DEFAULT;
    (*btn_info) = _def_btn_info_struct;
}

static inline void btn_reset(btn_info_t *const btn_info) {
    #if defined(__BTN_ALLOW_FAST_SCAN) && BTN_FAST_SOME_CODE
    btn_set_processed(btn_info->state);
    #else
    _btn_reset(btn_info);
    #endif // __BTN_ALLOW_FAST_SCAN
}

void btn_proc(btn_info_t *const btn_info, const bool is_now_hold);
 
#if defined(__DOXYGEN__)

static inline void btn_reset_atomic(btn_info_t *const btn_info);

static inline void btn_reset_atomic_fegi(btn_info_t *const btn_info);

static inline void btn_proc_atomic(btn_info_t *const btn_info, const bool is_now_hold);

static inline void btn_proc_atomic_fegi(btn_info_t *const btn_info, const bool is_now_hold);

static inline btn_info_struct btn_get_info(btn_info_t *const btn_info);

static inline btn_info_struct btn_get_info_fegi(btn_info_t *const btn_info);
#endif // __DOXYGEN__
 
#if BTN_ATOMIC_FUNCTIONS
static inline void btn_reset_atomic(btn_info_t *const btn_info) {
    #if defined(__BTN_ALLOW_FAST_SCAN) && BTN_FAST_SOME_CODE
    btn_set_processed(btn_info->state); //8-bit - no atomic
    #else
    ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
        _btn_reset(btn_info);
    }
    #endif // __BTN_ALLOW_FAST_SCAN
}
 
static inline void btn_reset_atomic_fegi(btn_info_t *const btn_info) {
    #if defined(__BTN_ALLOW_FAST_SCAN) && BTN_FAST_SOME_CODE
    btn_set_processed(btn_info->state); //8-bit - no atomic
    #else
    ATOMIC_BLOCK(ATOMIC_FORCEON) {
        _btn_reset(btn_info);
    }
    #endif // __BTN_ALLOW_FAST_SCAN
}
 
static inline void btn_proc_atomic(btn_info_t *const btn_info, const bool is_now_hold) {
    ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
        btn_proc(btn_info, is_now_hold);
    }
}
 
static inline void btn_proc_atomic_fegi(btn_info_t *const btn_info, const bool is_now_hold) {
    ATOMIC_BLOCK(ATOMIC_FORCEON) {
        btn_proc(btn_info, is_now_hold);
    }
}
 
static inline btn_info_struct btn_get_info(btn_info_t *const btn_info) {
    btn_info_struct info_struct;
    ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
        info_struct = *btn_info;
    }
    return info_struct;
}
 
static inline btn_info_struct btn_get_info_fegi(btn_info_t *const btn_info) {
    btn_info_struct info_struct;
    ATOMIC_BLOCK(ATOMIC_FORCEON) {
        info_struct = *btn_info;
    }
    return info_struct;
}
#endif // BTN_ATOMIC_FUNCTIONS
 
#endif /* SLS_AVR_SINGLE_BUTTON_H_ */