# m5core2-ph

**Repository Path**: genvex/m5core2-ph

## Basic Information

- **Project Name**: m5core2-ph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# M5Core2 便携式 pH Logger

基于 M5Stack Core 2 (ESP32-D0WDQ6) 的嵌入式 pH 记录仪, 带 SD 卡存储、
BM8563 RTC 时钟、LVGL 9.5 多点触控 UI, 支持两点校准 (7.00 / 9.18) +
温度补偿。

[![Gitee](https://img.shields.io/badge/Gitee-genvex/m5core2--ph-brightgreen)](https://gitee.com/genvex/m5core2-ph)
[![MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)

---

## 特性

- **pH 实时测量** — ADC 中值滤波, 10Hz 采样, 温度补偿到 25°C
- **两点校准** — pH 7.00 + pH 9.18, 实测斜率替代理论值, 精度更高
- **校准安全** — 确认框 Yes/No 弹窗, RAM 回滚, NVS 持久化
- **SD 卡存储** — SPSC 环形缓冲 32 条, 5s 落盘, 断电不丢
- **pH 趋势图** — 从 SD 读取最后 10 条记录, lv_chart 折线展示
- **校准信息** — 实时显示 pH7/pH9 电压、实测斜率、电极效率、斜率曲线
- **BM8563 RTC** — 板载 RTC 时钟, 断电持续走时, 系统时间自动同步
- **LVGL 9.5 UI** — 4 个页面, 320×240 电容触控

## 硬件要求

| 组件 | 规格 |
|------|------|
| 开发板 | M5Stack Core 2 (ESP32-D0WDQ6) |
| Flash | 4 MB |
| PSRAM | 8 MB |
| 屏幕 | 2.8" TFT, 320×240, FT6236 触摸 |
| SD 卡 | microSD ≤32 GB (FAT32) |
| RTC | BM8563 (I2C0, 板载 32.768kHz 晶振) |
| pH 电极 | 模拟, 输出 0~3.3V (建议经分压到 ADC) |
| 电池 | 1400 mAh 锂聚合物 (板载) |

## 软件依赖

- ESP-IDF v5.5.4
- M5Stack Core 2 BSP (idf_component.yml 自动管理)
- LVGL 9.5

## 编译

```bash
# 1. 配置环境
git clone https://gitee.com/genvex/m5core2-ph.git
cd m5core2-ph

# 2. 设置 IDF 路径
export IDF_PATH=/path/to/esp-idf-v5.5.4

# 3. 安装依赖
$IDF_PATH/tools/idf.py set-target esp32
idf.py reconfigure

# 4. 编译
idf.py build

# 5. 烧录
idf.py -p /dev/ttyUSB0 flash monitor
```

固件大小约 **750 KB**, App 分区使用率约 78%。

## UI 页面

```
开机 → 主界面
      ├── CALI  → 校准页 (7.00 / 9.18, 确认框 Yes/No)
      ├── INFO  → 校准信息页 (斜率曲线 + 电极效率 + 时间校准)
      └── TREND → 趋势图页 (SD 10 点折线 + 实时数据)

[TREND] 按钮触发 SD 读取, LOG 按钮启动/停止 SD 记录
```

### 页面布局 (320×240)

```
┌─────────────────────────────────────┐
│ ← Back    pH Logger       12:34:56 │
├─────────────────────────────────────┤
│         7.42  pH                   │
│         CALIBRATED                  │
├─────────────────────────────────────┤
│ raw:2234  1710 mV  25.0°C          │
├─────────────────────────────────────┤
│ SD:●OK REC:●OFF  [CALI][INFO][TREND][LOG] │
└─────────────────────────────────────┘
```

## 校准流程

```
  主界面 → CALI 按钮
      ↓
  CAL 7.00 按钮 → 电极稳定 10s → 采样 3.5s
      → RAM 更新 (pH7, slope 保留上次)
      → 确认框弹出 "YES/NO"
          ├─ YES → NVS 写入持久化
          └─ NO  → RAM 回滚备份
      ↓
  CAL 9.18 按钮 → 稳定 10s → 采样 3.5s
      → RAM 更新 (pH9 + 两点实测斜率)
      → 确认框弹出
          ├─ YES → NVS 写入
          └─ NO  → RAM 回滚备份
```

### 校准公式

```
两点校准 (25°C 等效):

  v7_25c = V_pH7_measured × 298.15 / (T_at_pH7 + 273.15)
  v9_25c = V_pH9_measured × 298.15 / (T_at_pH9 + 273.15)
  slope  = (v9_25c − v7_25c) / (9.18 − 7.00)   /* 实测斜率 mV/pH */

  pH = 7.00 + (V_measured_25c − v7_25c) / slope
```

电极效率 = `|实测斜率| / |理论斜率| × 100%`

## BM8563 RTC 时钟

M5Core2 板载 BM8563 RTC 芯片, 32.768kHz 晶振 + 纽扣电池供电。

- 上电时通过 I2C0 (与触摸驱动共享) 读取时间, 同步到系统
- 断电后 RTC 持续走时, 下次上电自动恢复
- 校准信息页的 TIME 按钮可手动触发 SNTP 同步 (需先配置 WiFi)
- SD CSV 时间戳: Unix epoch (秒)

## SD 卡 CSV 格式

文件: `/sdcard/ph_log.csv`

```
timestamp,event,raw,voltage_mV,pH,temp_C,free_heap,uptime_ms
1704067200,read,2234,1710.00,7.42,25.0,250000,360000
```

| 字段 | 说明 |
|------|------|
| timestamp | Unix epoch (秒) |
| event | 固定 `read` |
| raw | ADC 原始值 |
| voltage_mV | 中值滤波后电压 |
| pH | 温度补偿后 pH 值 |
| temp_C | 温度 (°C) |
| free_heap | 可用堆内存 |
| uptime_ms | 系统启动时间 (毫秒) |

## 软件架构

```
main/
├── main.c                    app 入口, BSP 初始化, RTC 同步
├── CMakeLists.txt
└── ph_logger/
    ├── ph_sensor.c/h         ADC 采样 + 中值滤波 + 两点校准 + NVS
    ├── ph_sd_ring.c/h        SPSC 环形缓冲 (32 条)
    ├── ph_sd_logger.c/h      SD 卡 CSV 写入
    ├── ph_ui.c/h             主界面 (pH 显示 + 4 按钮 + 顶部状态栏)
    ├── ph_calibration.c/h    校准页面 (7.00/9.18 + 确认框)
    ├── ph_calibration_info.c/h  校准信息页 (斜率曲线 + TIME)
    ├── ph_trend_chart.c/h    pH 趋势图页 (SD 10 点折线 + 实时)
    ├── ph_logger_demo.c/h    demo_enter 主循环 (LVGL tick + SD 日志)
    ├── bm8563_rtc.c/h        BM8563 RTC I2C 驱动
    └── ph_config.h           配置 (NVS key, 滤波参数, 文件名)
```

## 线程模型

| 线程 | 周期 | 职责 |
|------|------|------|
| Sensor Task | 100 ms | ADC 采样 + 中值滤波, 写共享 buffer |
| LVGL Display Task | 5 ms | UI 刷新, 从 buffer 读最新值 |
| SD Logger Task | 5 s | 从环形缓冲取数据写 SD 卡 |

数据共享通过 mutex 保护, 环形缓冲用 SPSC + memw 屏障。

## 已知限制

- 温度目前由用户设置 (`ph_sensor_set_temperature`), 暂未接 NTC 传感器
- WiFi 未启用, 时间校准页的 SNTP 功能需手动配置 WiFi 后激活
- 无 OTA 升级支持, 更新固件需 USB 烧录
- 校准确认框期间不可再触发校准操作
- 单次上电最多保存最近一组校准参数, 不保留历史

## 许可证

MIT