【BitsButton-master】- 位域结构体

原创已于 2025-07-11 09:11:18 修改 · 662 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#开发语言

于 2025-07-10 17:47:02 首次发布

BitsButton

👋 简介

BitsButton是一款针对嵌入式系统优化的按键检测框架。通过创新的二进制位序列技术，它能高效处理单键、组合键（如Ctrl+C）和复杂按键序列（如单击→长按→双击），提供从按键按下到释放的全生命周期跟踪。独特的无锁环形缓冲设计确保多线程环境下事件不丢失，显著简化了传统按键逻辑的实现复杂度，特别适用于资源受限的嵌入式设备和复杂人机交互场景。

🌱 特性

💡1.按键事件回溯支持，创新使用位序列记录按键状态，1代表按下，0代表松开

键值	说明
0b0	未按下
0b010	单击
0b01010	双击
0b01010…n	n连击
0b011	长按开始
0b0111	长按保持
0b01110	长按结束
0b01011	短按然后长按
0b0101011	双击然后长按
0b01010…n11	n连击然后长按

“直观的二进制表示让按键逻辑一目了然”

🎯2.高级按键检测

功能	描述
组合按键	轻松定义多键组合（如Ctrl+C），智能冲突处理
序列识别	支持复杂按键序列（如单击-长按，单击-长按-双击等操作流）
事件类型	支持按下/抬起/单击/双击/连击/长按(开始/保持/结束)，完整覆盖按键生命周期

🚀3.高性能内核

typedef struct {
    bits_btn_result_t buffer[BITS_BTN_BUFFER_SIZE];
    atomic_size_t read_idx;   // 无锁原子操作
    atomic_size_t write_idx;
} bits_btn_ring_buffer_t;

SPSC(单生产者单消费者)线程安全模型;
无锁设计+原子操作;
缓冲区溢出检测与统计;
轻量化处理（RAM <20字节/按键）;

请添加图片描述

🧩4.模块化架构

模块	功能
位运算优化引擎	高效处理按键状态转换逻辑
硬件抽象层	统一接口适配各类硬件平台
调试接口	可插拔日志输出

核心数据结构

// 单按键对象
typedef struct button_obj_t {
    uint8_t  active_level : 1;
    uint8_t current_state : 3;
    uint8_t last_state : 3;
    uint16_t  key_id;
    uint16_t long_press_period_trigger_cnt;
    uint32_t state_entry_time;
    state_bits_type_t state_bits;
    const bits_btn_obj_param_t *param;
} button_obj_t;

// 组合按键对象
typedef struct {
    uint8_t key_count;              // 组合中按键数量
    uint16_t key_single_ids[BITS_BTN_MAX_COMBO_KEYS]; // 成员按键ID
    button_obj_t btn;               // 组合按键状态
    button_mask_type_t combo_mask;  // 组合掩码
    uint8_t suppress;               // 是否抑制成员按键事件
} button_obj_combo_t;

// 按键事件结果
typedef struct {
    uint16_t key_id;             // 触发按键ID
    btn_state_t event;           // 按键事件类型
    uint16_t long_press_period_trigger_cnt; // 长按周期计数
    key_value_type_t key_value;  // 按键值（序列位图）
} bits_btn_result_t;

字段	用途说明	位宽优化
`state_bits`	按键序列历史状态位图	32位（可调整为64）支持32次按键事件
`long_press_period_trigger_cnt`	长按周期触发计数	支持最大65535次触发

📋 快速开始

0）编译环境要求

⚠️ 编译器必须支持 C11 标准

核心依赖的 C11 特性：

_Atomic 类型（内核无锁设计的核心）
<stdatomic.h> 原子操作库（内存序模型基础）
匿名结构体（简化核心数据结构设计）

1）基础使用

点击展开/折叠C代码

首先将bits_button.c和bits_button.h包含进你的工程；
使用callback方式;
使用poll方式;

2）进阶调试

点击展开/折叠

bits_button_init时，注册定义你的打印函数：

int my_log_printf(const char* format, ...) {
    va_list args;
    va_start(args, format);
    int result = vprintf(format, args);
    va_end(args);
    return result;
}

bits_button_init(
    btns,
    ARRAY_SIZE(btns),
    btns_combo,
    ARRAY_SIZE(btns_combo),
    read_key_state,
    bits_btn_result_cb,
    my_log_printf
);