OneButton library

Platform-portable button detection library with multi-click and long-press support. More...

Topics
	Platform Selection
	Define ONE of these macros to select target platform.
	Platform-Specific Macros
	GPIO and timing macros adapted per platform.
	Callback Function Types
	Function pointer types for button event callbacks.
	State Machine Types
	Enumerations and structures for button state management.
	Public API Functions
	Initialization, configuration, and task functions.
	Timer Configuration Functions
	Functions to configure timing parameters.
	Callback Registration Functions
	Functions to register event callback handlers.

Detailed Description

Platform-portable button detection library with multi-click and long-press support.

Overview

OneButton is a button event detection library originally inspired by Arduino OneButton, ported to bare-metal embedded systems (STM32, ESP32).

Features:

• Single-click detection
• Double-click detection
• Long-press detection with start/stop events
• Hardware debouncing
• Configurable timing parameters
• Non-blocking, poll-based operation
• Multi-button support

Platform Selection

Select your target platform by defining ONE of the following:

• STM_PLATFORM - For STM32 microcontrollers with HAL
• ESP_PLATFORM - For ESP32 microcontrollers with ESP-IDF

Example:

// For STM32:
#define STM_PLATFORM
 
// For ESP32:
#define ESP_PLATFORM

Warning

Define ONLY ONE platform macro at a time

Platform-Specific Configuration

STM32 Platform (HAL-based)

Macros:

• OB_READ_PIN() → HAL_GPIO_ReadPin(Btn->GpioPort, Btn->GpioPin)
• OB_GET_TICK() → HAL_GetTick() (1ms SysTick)
• OB_BUTTON_PRESSED → GPIO_PIN_RESET (0 - active low)
• OB_BUTTON_NOT_PRESSED → GPIO_PIN_SET (1 - pull-up)

Initialization:

OneButton_t myButton;
OneButtonInit(&myButton, GPIOA, GPIO_PIN_0);  // PA0 with GPIO port

GPIO Configuration Requirements:

GPIO_InitTypeDef GPIO_InitStruct = {0};
GPIO_InitStruct.Pin = GPIO_PIN_0;
GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
GPIO_InitStruct.Pull = GPIO_PULLUP;  // For active-low buttons
HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

ESP32 Platform (ESP-IDF)

Required Headers:

• xtimers.h - Custom timer wrapper
• ot_app.h - Application header

Macros:

• OB_READ_PIN() → gpio_get_level(Btn->GpioPin)
• OB_GET_TICK() → xTim_getTick() (custom millisecond timer)
• OB_BUTTON_PRESSED → 0 (active low)
• OB_BUTTON_NOT_PRESSED → 1 (pull-up)

Initialization:

OneButton_t myButton;
OneButtonInit(&myButton, GPIO_NUM_9);  // GPIO 9 (no port needed)

GPIO Configuration Requirements:

gpio_config_t io_conf = {
    .pin_bit_mask = (1ULL << GPIO_NUM_9),
    .mode = GPIO_MODE_INPUT,
    .pull_up_en = GPIO_PULLUP_ENABLE,  // Enable pull-up for active-low
    .pull_down_en = GPIO_PULLDOWN_DISABLE,
    .intr_type = GPIO_INTR_DISABLE
};
gpio_config(&io_conf);

Usage Example

#include "OneButton.h"
 
// Define button instance
OneButton_t button1;
 
// Callback functions
void onSingleClick(uint16_t btnNum) {
    printf("Button %d: Single click\n", btnNum);
}
 
void onDoubleClick(uint16_t btnNum) {
    printf("Button %d: Double click\n", btnNum);
}
 
void onLongPressStart(uint16_t btnNum) {
    printf("Button %d: Long press started\n", btnNum);
}
 
void onLongPressStop(uint16_t btnNum) {
    printf("Button %d: Long press stopped\n", btnNum);
}
 
void setup() {
    // Initialize button
    #ifdef STM_PLATFORM
        OneButtonInit(&button1, GPIOA, GPIO_PIN_0);
    #endif
    #ifdef ESP_PLATFORM
        OneButtonInit(&button1, GPIO_NUM_9);
    #endif
    
    // Optional: Configure custom timing
    OneButtonSetTimerDebounce(&button1, 10);        // 10ms debounce
    OneButtonSetTimerDoubleClick(&button1, 350);    // 350ms double-click window
    OneButtonSetTimerLongPressStart(&button1, 700); // 700ms for long-press
    OneButtonSetTimerLongPressTick(&button1, 500);  // 500ms long-press repeat
    
    // Register callbacks
    OneButtonCallbackOneClick(&button1, onSingleClick);
    OneButtonCallbackDoubleClick(&button1, onDoubleClick);
    OneButtonCallbackLongPressStart(&button1, onLongPressStart);
    OneButtonCallbackLongPressStop(&button1, onLongPressStop);
}
 
void loop() {
    OneButtonTask(&button1);  // Call periodically (every 10-50ms recommended)
}

Porting to New Platforms

To add support for a new platform:

1. Add platform definition at top of OneButton.h:

   #define OB_MYPLATFORM

2. Add platform-specific macros block:

   #ifdef OB_MYPLATFORM
   #define OB_READ_PIN()            my_gpio_read(Btn->GpioPin)
   #define OB_GET_TICK()            my_get_millis()
   #define OB_BUTTON_PRESSED        0
   #define OB_BUTTON_NOT_PRESSED    1
   #endif

3. Update OneButton_t structure if needed (e.g., add port field)
4. Add platform-specific initialization in OneButton.c:

   #ifdef OB_MYPLATFORM
   void OneButtonInit(OneButton_t *Btn, uint16_t GpioPin) {
       // Initialization code
   }
   #endif

See also

OneButton.c for implementation details

ad_button.h for integration with OpenThread application

Version

1.0

Date

Nov 19, 2022

Author

Jan Łukaszewicz (plhar.nosp@m.eo@g.nosp@m.mail..nosp@m.com)

Copyright

© 2025 MIT LICENCE