# CapOneButton

**Repository Path**: chiyoooo/cap-one-button

## Basic Information

- **Project Name**: CapOneButton
- **Description**: **CapOneButton** 基于 [OneButton](https://github.com/mathertel/OneButton) 库，将 ESP32 的电容触摸引脚（Touch Sensor）封装为可识别单击、双击、长按的“单按键”对象。内部使用 `touchRead(pin)` 与可配置阈值判断触摸状态，并沿用 OneButton 的去抖、时间参数与回调接口。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CapOneButton — ESP32 电容触摸按键库

## 简介

**CapOneButton** 基于 [OneButton](https://github.com/mathertel/OneButton) 库，将 ESP32 的电容触摸引脚（Touch Sensor）封装为可识别单击、双击、长按的“单按键”对象。内部使用 `touchRead(pin)` 与可配置阈值判断触摸状态，并沿用 OneButton 的去抖、时间参数与回调接口。

**仓库**：[https://gitee.com/chiyoooo/cap-one-button](https://gitee.com/chiyoooo/cap-one-button)  
克隆：`git clone git@gitee.com:chiyoooo/cap-one-button.git`

## 特性

- 继承 **OneButton**：支持 `attachClick`、`attachDoubleClick`、`attachLongPressStart`、`attachLongPressStop`、`attachDuringLongPress`
- 电容触摸驱动：通过 `touchRead(pin)` 与阈值判断按下/释放，无需外接物理按键
- 可调参数：构造时传入引脚与触发阈值；去抖、单击、长按时间使用库内默认（可改宏定义）

## 硬件

- **平台**：ESP32（使用内置 Touch Sensor 的引脚，如 GPIO33 等）
- **引脚**：需为支持 `touchRead()` 的 Touch 引脚

## 安装

**Arduino IDE**

通过「项目」→「加载库」→「添加 .ZIP 库」选择本库目录，或放入 `libraries/CapOneButton`。

**PlatformIO**

```ini
lib_deps =
    mathertel/OneButton@^2.0.4
```

将本库放入项目 `lib` 或通过 `lib_deps` 引用。

## 快速开始

```cpp
#include "CapOneButton.h"

#define touch_pin 33
#define touch_threshold 9

CapOneButton button1(touch_pin, touch_threshold);

void onClick()   { Serial.println("Click"); }
void onDouble()  { Serial.println("Double click"); }
void onLongStart(){ Serial.println("Long press start"); }
void onLongStop() { Serial.println("Long press stop"); }

void setup() {
  Serial.begin(115200);
  button1.attachClick(onClick);
  button1.attachDoubleClick(onDouble);
  button1.attachLongPressStart(onLongStart);
  button1.attachLongPressStop(onLongStop);
}

void loop() {
  button1.tick();
  delay(10);
}
```

## API 概要

- **构造**：`CapOneButton(int pin, uint32_t threshold, bool activeLow = false)`  
  参数：触摸引脚、触发阈值（大于该值视为“按下”）、是否低有效（默认 false）。
- **轮询**：在 `loop()` 中反复调用 `button.tick()`。
- **回调**：与 OneButton 一致 — `attachClick`、`attachDoubleClick`、`attachLongPressStart`、`attachLongPressStop`、`attachDuringLongPress`。
- **时间常量**（在头文件中可改）：`debounceTicks`（去抖）、`clickTicks`（单击判定）、`pressTicks`（长按判定）。

## 依赖

- Arduino ESP32 Core
- [OneButton](https://github.com/mathertel/OneButton)

## 示例

| 示例                     | 说明                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| **simpleExample**        | 单路电容触摸：单击、双击、长按回调演示                                                       |
| **thresholdCalibration** | 串口持续打印 touchRead 原始值与最小/最大值，手动观察后自选阈值                               |
| **autoThresholdMeasure** | 按提示「不触摸→触摸」各采集 10 次，自动给出建议阈值与 activeLow，并持续显示当前按下/释放状态 |

编译并烧录「自动阈值测量」示例（PlatformIO）：`pio run -e autoThresholdMeasure -t upload`。

## 许可证

MIT License

## 作者

CHIYoooo