Files

T

2026-09-08 22:56:52 +08:00

9.1 KiB

Raw Blame History

M5Stack Unit ADC v1.1 / ADS1110 开发约定

本文供后续 Codex 或维护者读取。动手写驱动前，先确认实物是 M5Stack Unit ADC v1.1、SKU U013-V11、ADC 芯片 ADS1110。不要把旧版 Unit ADC、ADS1100 库或其他 ADS111x 芯片的寄存器接口混进来。

1. 当前项目边界

主控：WalnutPi ZeroW（H618）
目的：测量点阵屏输入端 5V 电压，作为供电压降的数字观测值
I²C 总线：/dev/i2c-1
7 位地址：0x48
GPIO：物理脚 3 / PI8/SDA1，物理脚 5 / PI7/SCL1
供电假设：系统已经提供可靠、共地的 5V/GND
当前交付：本地资料、独立脚本，以及主服务中的电压状态、校准和可选低电压亮度保护
明确不做：电流、功率、实际发光亮度识别、BMS、物理断电、充电管理或核桃派关机

测量端是并联采样。屏幕负载电流不得经过模块。v1.1 原理图中 P1 测量负端经 0Ω 电阻接模块 GND，因此不能把它当成与核桃派隔离的差分表使用。

2. 资料优先级和已知冲突

遇到资料冲突时采用以下优先级：

实物型号、v1.1 原理图和 TI ADS1110 数据手册
M5Stack Unit ADC v1.1 产品描述及管脚表
M5Stack 产品页中的规格汇总表
M5Stack 旧 Arduino 示例和 M5-ADS1100 仓库

当前 M5Stack 产品页存在混杂信息：正文把 v1.1 描述为 ADS1110，并给出 15/30/60/240 SPS；但部分规格/比较表仍显示 ADS1100 或 8/16/32/128 SPS，链接的旧 Arduino 例程也使用 M5_ADS1100.h。对 U013-V11 必须使用 ADS1110 的 15/30/60/240 SPS 位定义，不得照抄旧库常量。

本地官方文件、原始 URL、下载日期和 SHA-256 见 官方资料/来源索引.md。

3. 板级模拟换算

v1.1 原理图在测量输入端使用 510kΩ 与 100kΩ 分压，并由 LM358 缓冲后送入 ADS1110。标称分压倍率为：

(510k + 100k) / 100k = 6.1

ADS1110 在 PGA=1 时的差分满量程为 ±2.048V。选择 15 SPS 时输出为 16 位二进制补码，因此：

ADC差分电压 = signed_raw × 2.048 / 32768
屏幕输入电压 = ADC差分电压 × 6.1 × calibration_factor

默认 calibration_factor = 1.0。屏幕端每 LSB 的标称分辨率为：

2.048 / 32768 × 6.1 = 0.00038125V

快速合理性检查：

屏幕输入端标称电压	预期 raw（约）
`0V`	`0`
`4.5V`	`11803`
`5.0V`	`13115`
`5.3V`	`13902`
`12.0V`	`31475`

raw=32767 对应标称约 12.4924V，但这只是数学满量程；模块官方输入范围仍按 0V ~ 12V，不能把多出的计算余量当成允许输入范围。

4. ADS1110 配置字节

ADS1110 配置寄存器只有 1 字节：

位	名称	本项目值	含义
7	`ST/DRDY`	写入时 `0`	连续模式下写入值被忽略；读取时 `0` 表示本次结果是新数据
6:5	保留	`00`	必须为 0
4	`SC`	`0`	连续转换模式
3:2	`DR1:DR0`	`11`	15 SPS、16 位
1:0	`PGA1:PGA0`	`00`	PGA=1

因此本项目写入：

0b00001100 = 0x0C

ADS1110 上电默认配置读值通常为 0x8C；位 7 是读取状态，校验配置时只比较低 7 位是否等于 0x0C。不要把 ADS1100 的采样率名称套在相同位值上。

5. I²C 读写顺序

ADS1110 没有常见的“寄存器地址指针”步骤：

以 7 位地址 0x48 打开 I²C 从设备。
写入单个配置字节 0x0C。
至少等待一个 15 SPS 转换周期，约 66.7ms；实现可留少量余量。
一次读取 3 字节：
- 字节 0：输出寄存器高字节
- 字节 1：输出寄存器低字节
- 字节 2：配置/状态字节
将前两个字节按大端、有符号 16 位二进制补码解析。
检查配置低 7 位仍为 0x0C；位 7 为 0 时，本次结果为新数据。

不要使用会自动在事务前发送“寄存器编号”的 SMBus 便捷函数，除非确认它能发出 ADS1110 所需的原始事务。当前独立脚本直接操作 /dev/i2c-1，避免引入依赖或错误的寄存器前缀。

6. 独立脚本接口

文件：示例程序/read_unit_adc_v1_1.py

默认行为：

总线 /dev/i2c-1
地址 0x48
配置 0x0C
每次取 5 个新样本的中位数
输出屏幕输入端电压、raw 中位数和配置字节

常用命令：

# 本机纯计算/协议自测，不访问 I²C，Windows 也可以运行
python "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --self-test

# 核桃派单次读数
python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py"

# 连续读数
python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --watch

# 使用一次比例校正
python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --calibration-factor 1.00604 --watch

额外参数通过 --help 查看。独立工具必须保持 Python 标准库实现并与主服务监测器分开；不能把独立无限循环直接放进 FastAPI 进程，也不能与主服务同时长期读取同一地址。

7. 错误与排障语义

后续修改脚本时必须保留可区分的错误：

/dev/i2c-1 不存在：I²C 未启用或设备节点不同。
权限不足：用户没有访问 I²C 设备的权限。
地址无响应：0x48 没有 ACK，优先查接线、供电和型号。
地址被占用：内核驱动已经 claim 该地址。
短读取：没有取得完整 3 字节，结果不可用。
配置低 7 位不是 0x0C：设备/协议不符或配置被改变，不能继续按 15 SPS/PGA=1 换算。
负 raw：按二进制补码保留并报告，不要在协议层静默截成 0；对本项目的正电压输入，持续负值应视为接线或偏置异常。
读数超出 0V ~ 12V：报告异常并检查硬件，不能用软件裁剪后假装正常。

i2cdetect 只用于首次诊断，不要在长期读取过程中反复扫描总线。

8. 主服务集成约束

主服务已经按 WEB-SCREEN-VOLTAGE / CONFIG-SCREEN-VOLTAGE 接入网页电压显示和每台设备独立的软件校准，并按 WEB-LOW-VOLTAGE-PROTECTION、CONFIG-LOW-VOLTAGE-PROTECTION、DISPLAY-LOW-VOLTAGE-PROTECTION 接入可选保护。实现必须继续满足：

ADC 缺失或读取失败不能拖垮显示服务。
只有一个组件负责持续读取设备，其他组件读取缓存值，避免并发争用 I²C。
原始电压、校正系数、采样时间和错误状态要可区分，不能把读取失败伪装成 0V。
低电压保护阈值来自本项目真实屏幕和供电试验：校准后、未舍入的组中位数严格大于 4.8V 不限制，4.5..4.8V 使用 floor(50 + 50 × (V-4.5)/0.3) 限制实际亮度，严格低于 4.5V 进入 35% 低电图标；不能从 ADC 量程另行推导或改写边界。35% 来自覆盖保护膜后的红色可视性复测。
电压正常不等于屏幕状态正常；界面文案必须称为“屏幕输入电压”，不能称为“屏幕亮度传感器”。
正常轮询与校准专用采样都必须经过同一个监测组件，不能让 API 请求和后台线程并发打开设备。
校准使用同一测量点的可靠万用表参考值，只做单点比例修正；更换 ADC、接线或测量点后恢复 1.0 并重新校准。
每组继续取 5 个 15 SPS 新样本中位数。保护关闭或稳定高于 4.8V 时组起始间隔为 5s；高于阈值但持续下降时按预计到达阈值缩短为 1..5s；限亮为 1s；首次临界为 0.5s，之后按 clamp(0.5, 2.0, 0.02/max(|dV/dt|, 0.01)) 自适应，放慢每轮最多增加 0.5s、加速立即生效；错误按 1/2/5s 退避。
每次 I²C 尝试使用单调序号并拒绝晚到旧结果。更严格保护一组立即发布，任何放宽需连续两组成功样本；失败取消待放宽，首次尚无样本不锁屏，已有成功样本后保持最后保护并标记 stale。
保护回调必须在监测锁和 I²C 锁外执行；回调错误与 ADC 状态分开，不能污染样本或解除保护，并要在后续周期重试。完整网页、配置和显示契约以 WEB-LOW-VOLTAGE-PROTECTION、CONFIG-LOW-VOLTAGE-PROTECTION、DISPLAY-LOW-VOLTAGE-PROTECTION 为准。

9. 浏览器救援条件

以下情况才进入浏览器：

实物不是 U013-V11 或 PCB 修订发生变化。
地址不是 0x48。
本地 PDF 损坏或与实物丝印冲突。
需要确认 ADS1110 电气极限、时序或未在本文覆盖的模式。

优先访问官方来源：

M5Stack：https://docs.m5stack.com/zh_CN/unit/Unit-ADC_V1.1
v1.1 原理图：https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/576/Sch_UNIT_ADC_v1.1.pdf
TI ADS1110：https://www.ti.com/lit/ds/symlink/ads1110.pdf
核桃派项目约定：使用系统已有的 /dev/i2c-1，不运行其他开发板专用配置工具

浏览时使用 U013-V11 ADS1110 作为组合关键词，并记录所用来源和日期。论坛、商家详情和旧 M5-ADS1100 代码只能作为线索，不能覆盖原理图与 TI 数据手册。

9.1 KiB Raw Blame History Unescape Escape