358 lines
12 KiB
Python
358 lines
12 KiB
Python
#!/usr/bin/env python3
|
||
"""读取 M5Stack Unit ADC v1.1 (U013-V11 / ADS1110) 的屏幕输入电压。
|
||
|
||
真实 I2C 读取仅支持 Linux；--self-test 不访问硬件，可在 Windows 上运行。
|
||
本脚本只使用 Python 标准库，不接入项目主服务。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import errno
|
||
import math
|
||
import os
|
||
import statistics
|
||
import sys
|
||
import time
|
||
from dataclasses import dataclass
|
||
from typing import Sequence
|
||
|
||
|
||
DEFAULT_BUS = "/dev/i2c-1"
|
||
DEFAULT_ADDRESS = 0x48
|
||
I2C_SLAVE = 0x0703
|
||
|
||
CONFIG_CONTINUOUS_15SPS_PGA1 = 0x0C
|
||
CONFIG_VALUE_MASK = 0x7F
|
||
DATA_READY_MASK = 0x80
|
||
|
||
REFERENCE_VOLTS = 2.048
|
||
ADC_CODE_SCALE = 32768
|
||
BOARD_DIVIDER_RATIO = 6.1
|
||
CONVERSION_WAIT_SECONDS = (1.0 / 15.0) + 0.010
|
||
FRESH_DATA_TIMEOUT_SECONDS = 0.75
|
||
|
||
|
||
class AdcError(RuntimeError):
|
||
"""用户可处理的 ADC 访问错误。"""
|
||
|
||
|
||
class AdcProtocolError(AdcError):
|
||
"""ADS1110 返回的数据不符合本项目固定协议。"""
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Reading:
|
||
raw_median: float
|
||
volts: float
|
||
config: int
|
||
|
||
|
||
def parse_address(value: str) -> int:
|
||
try:
|
||
address = int(value, 0)
|
||
except ValueError as exc:
|
||
raise argparse.ArgumentTypeError("I2C 地址应为 0x48 这类整数") from exc
|
||
if not 0x08 <= address <= 0x77:
|
||
raise argparse.ArgumentTypeError("7 位 I2C 地址必须在 0x08 到 0x77 之间")
|
||
return address
|
||
|
||
|
||
def positive_int(value: str) -> int:
|
||
try:
|
||
result = int(value)
|
||
except ValueError as exc:
|
||
raise argparse.ArgumentTypeError("应输入正整数") from exc
|
||
if result <= 0:
|
||
raise argparse.ArgumentTypeError("应输入大于 0 的整数")
|
||
return result
|
||
|
||
|
||
def positive_float(value: str) -> float:
|
||
try:
|
||
result = float(value)
|
||
except ValueError as exc:
|
||
raise argparse.ArgumentTypeError("应输入正数") from exc
|
||
if not math.isfinite(result) or result <= 0:
|
||
raise argparse.ArgumentTypeError("应输入大于 0 的有限数值")
|
||
return result
|
||
|
||
|
||
def voltage_from_raw(raw: int | float, calibration_factor: float = 1.0) -> float:
|
||
if not -32768 <= raw <= 32767:
|
||
raise ValueError("ADS1110 raw 必须在 -32768 到 32767 之间")
|
||
if not math.isfinite(calibration_factor) or calibration_factor <= 0:
|
||
raise ValueError("calibration_factor 必须是大于 0 的有限数值")
|
||
adc_volts = float(raw) * REFERENCE_VOLTS / ADC_CODE_SCALE
|
||
return adc_volts * BOARD_DIVIDER_RATIO * calibration_factor
|
||
|
||
|
||
def validate_config(config: int) -> None:
|
||
if not 0 <= config <= 0xFF:
|
||
raise AdcProtocolError(f"配置字节超出范围: {config!r}")
|
||
actual = config & CONFIG_VALUE_MASK
|
||
if actual != CONFIG_CONTINUOUS_15SPS_PGA1:
|
||
raise AdcProtocolError(
|
||
"ADS1110 配置不符合连续转换/15SPS/PGA=1: "
|
||
f"收到 0x{config:02X}，低 7 位应为 0x{CONFIG_CONTINUOUS_15SPS_PGA1:02X}"
|
||
)
|
||
|
||
|
||
def decode_conversion(data: bytes) -> tuple[int, int]:
|
||
if len(data) != 3:
|
||
raise AdcProtocolError(f"ADS1110 应返回 3 字节，实际收到 {len(data)} 字节")
|
||
raw = int.from_bytes(data[:2], byteorder="big", signed=True)
|
||
config = data[2]
|
||
validate_config(config)
|
||
return raw, config
|
||
|
||
|
||
def describe_os_error(action: str, exc: OSError, address: int) -> AdcError:
|
||
remote_io = getattr(errno, "EREMOTEIO", 121)
|
||
if exc.errno in (remote_io, errno.ENXIO):
|
||
return AdcError(
|
||
f"{action}失败：I2C 地址 0x{address:02X} 没有响应；"
|
||
"请检查 v1.1 型号、5V/GND、SDA/SCL，并先运行 i2cdetect -y 1"
|
||
)
|
||
if exc.errno == errno.EBUSY:
|
||
return AdcError(
|
||
f"{action}失败：I2C 地址 0x{address:02X} 已被内核驱动占用；"
|
||
"如果 i2cdetect 显示 UU，请先查明占用原因"
|
||
)
|
||
if exc.errno in (errno.EACCES, errno.EPERM):
|
||
return AdcError(
|
||
f"{action}失败：没有访问 I2C 设备的权限；请检查 /dev/i2c-1 权限和当前用户的 i2c 组"
|
||
)
|
||
return AdcError(f"{action}失败：{exc.strerror or exc} (errno={exc.errno})")
|
||
|
||
|
||
class Ads1110Device:
|
||
def __init__(self, bus_path: str, address: int) -> None:
|
||
self.bus_path = bus_path
|
||
self.address = address
|
||
self._fd: int | None = None
|
||
|
||
def __enter__(self) -> "Ads1110Device":
|
||
if os.name != "posix":
|
||
raise AdcError("真实 I2C 读取只支持 Linux；在 Windows 上请使用 --self-test")
|
||
|
||
try:
|
||
import fcntl
|
||
except ImportError as exc:
|
||
raise AdcError("当前 Python 缺少 Linux fcntl，无法访问 /dev/i2c-* 设备") from exc
|
||
|
||
try:
|
||
self._fd = os.open(self.bus_path, os.O_RDWR)
|
||
except FileNotFoundError as exc:
|
||
raise AdcError(
|
||
f"没有找到 {self.bus_path}；请确认核桃派 I2C1 设备节点和总线编号"
|
||
) from exc
|
||
except PermissionError as exc:
|
||
raise AdcError(
|
||
f"没有权限打开 {self.bus_path}；请检查设备权限和当前用户的 i2c 组"
|
||
) from exc
|
||
except OSError as exc:
|
||
raise describe_os_error(f"打开 {self.bus_path}", exc, self.address) from exc
|
||
|
||
try:
|
||
fcntl.ioctl(self._fd, I2C_SLAVE, self.address)
|
||
except OSError as exc:
|
||
self.close()
|
||
raise describe_os_error("选择 I2C 从设备", exc, self.address) from exc
|
||
return self
|
||
|
||
def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
|
||
self.close()
|
||
|
||
def close(self) -> None:
|
||
if self._fd is not None:
|
||
os.close(self._fd)
|
||
self._fd = None
|
||
|
||
def _require_fd(self) -> int:
|
||
if self._fd is None:
|
||
raise AdcError("I2C 设备尚未打开")
|
||
return self._fd
|
||
|
||
def configure(self) -> None:
|
||
fd = self._require_fd()
|
||
try:
|
||
written = os.write(fd, bytes([CONFIG_CONTINUOUS_15SPS_PGA1]))
|
||
except OSError as exc:
|
||
raise describe_os_error("写入 ADS1110 配置", exc, self.address) from exc
|
||
if written != 1:
|
||
raise AdcProtocolError(f"ADS1110 配置应写入 1 字节，实际写入 {written} 字节")
|
||
|
||
def read_fresh(self) -> tuple[int, int]:
|
||
fd = self._require_fd()
|
||
deadline = time.monotonic() + FRESH_DATA_TIMEOUT_SECONDS
|
||
|
||
while True:
|
||
time.sleep(CONVERSION_WAIT_SECONDS)
|
||
try:
|
||
data = os.read(fd, 3)
|
||
except OSError as exc:
|
||
raise describe_os_error("读取 ADS1110", exc, self.address) from exc
|
||
|
||
raw, config = decode_conversion(data)
|
||
if (config & DATA_READY_MASK) == 0:
|
||
return raw, config
|
||
if time.monotonic() >= deadline:
|
||
raise AdcProtocolError("等待 ADS1110 新转换数据超时，ST/DRDY 始终为 1")
|
||
|
||
|
||
def take_reading(
|
||
device: Ads1110Device,
|
||
sample_count: int,
|
||
calibration_factor: float,
|
||
) -> Reading:
|
||
raw_values: list[int] = []
|
||
last_config = CONFIG_CONTINUOUS_15SPS_PGA1
|
||
for _ in range(sample_count):
|
||
raw, last_config = device.read_fresh()
|
||
raw_values.append(raw)
|
||
|
||
raw_median = float(statistics.median(raw_values))
|
||
return Reading(
|
||
raw_median=raw_median,
|
||
volts=voltage_from_raw(raw_median, calibration_factor),
|
||
config=last_config,
|
||
)
|
||
|
||
|
||
def format_raw(raw: float) -> str:
|
||
if raw.is_integer():
|
||
return str(int(raw))
|
||
return f"{raw:.1f}"
|
||
|
||
|
||
def print_reading(reading: Reading) -> None:
|
||
print(
|
||
f"屏幕输入端电压: {reading.volts:.3f} V "
|
||
f"raw中位数: {format_raw(reading.raw_median)} "
|
||
f"配置: 0x{reading.config:02X}",
|
||
flush=True,
|
||
)
|
||
if reading.volts < 0 or reading.volts > 12:
|
||
print(
|
||
"警告：读数超出模块规定的 0V~12V 输入范围，请停止并检查型号、接线和测量点。",
|
||
file=sys.stderr,
|
||
flush=True,
|
||
)
|
||
|
||
|
||
def require_self_test(condition: bool, message: str) -> None:
|
||
if not condition:
|
||
raise AssertionError(message)
|
||
|
||
|
||
def run_self_test() -> None:
|
||
require_self_test(CONFIG_CONTINUOUS_15SPS_PGA1 == 0x0C, "固定配置字节不是 0x0C")
|
||
require_self_test(voltage_from_raw(0) == 0.0, "raw=0 的换算结果不是 0V")
|
||
|
||
raw_5v, config = decode_conversion(bytes([0x33, 0x3B, 0x0C]))
|
||
require_self_test(raw_5v == 13115, "5V 样例 raw 解析错误")
|
||
require_self_test(config == 0x0C, "5V 样例配置解析错误")
|
||
require_self_test(
|
||
abs(voltage_from_raw(raw_5v) - 5.0) < 0.001,
|
||
"raw=13115 没有换算为约 5.000V",
|
||
)
|
||
|
||
negative_raw, config_with_old_data = decode_conversion(bytes([0xFF, 0xFF, 0x8C]))
|
||
require_self_test(negative_raw == -1, "16 位负数符号解析错误")
|
||
require_self_test(config_with_old_data == 0x8C, "ST/DRDY 状态位解析错误")
|
||
|
||
require_self_test(
|
||
abs(voltage_from_raw(32767) - 12.49241875) < 1e-9,
|
||
"正满量程换算错误",
|
||
)
|
||
|
||
try:
|
||
decode_conversion(bytes([0x00, 0x00]))
|
||
except AdcProtocolError:
|
||
pass
|
||
else:
|
||
raise AssertionError("短读取必须触发 AdcProtocolError")
|
||
|
||
try:
|
||
validate_config(0x08)
|
||
except AdcProtocolError:
|
||
pass
|
||
else:
|
||
raise AssertionError("错误采样配置必须触发 AdcProtocolError")
|
||
|
||
print("自测通过：配置 0x0C = 连续转换 / 15SPS / PGA=1")
|
||
print(f"自测通过：raw=13115 -> {voltage_from_raw(13115):.6f}V（约 5.000V）")
|
||
print("自测通过：16 位负数符号、满量程、短读取和错误配置检查正常")
|
||
|
||
|
||
def build_parser() -> argparse.ArgumentParser:
|
||
parser = argparse.ArgumentParser(
|
||
description="读取 M5Stack Unit ADC v1.1 (ADS1110) 的屏幕输入端电压"
|
||
)
|
||
parser.add_argument("--bus", default=DEFAULT_BUS, help=f"I2C 设备路径，默认 {DEFAULT_BUS}")
|
||
parser.add_argument(
|
||
"--address",
|
||
type=parse_address,
|
||
default=DEFAULT_ADDRESS,
|
||
help="7 位 I2C 地址，默认 0x48",
|
||
)
|
||
parser.add_argument(
|
||
"--samples",
|
||
type=positive_int,
|
||
default=5,
|
||
help="每次输出使用的新样本数量，取中位数，默认 5",
|
||
)
|
||
parser.add_argument(
|
||
"--calibration-factor",
|
||
type=positive_float,
|
||
default=1.0,
|
||
help="可选比例校正系数，默认 1.0",
|
||
)
|
||
parser.add_argument("--watch", action="store_true", help="连续读取，按 Ctrl+C 停止")
|
||
parser.add_argument(
|
||
"--interval",
|
||
type=positive_float,
|
||
default=1.0,
|
||
help="--watch 两次输出之间的最短秒数，默认 1.0",
|
||
)
|
||
parser.add_argument(
|
||
"--self-test",
|
||
action="store_true",
|
||
help="只测试协议常量和换算，不访问 I2C，可在 Windows 运行",
|
||
)
|
||
return parser
|
||
|
||
|
||
def run_hardware(args: argparse.Namespace) -> None:
|
||
with Ads1110Device(args.bus, args.address) as device:
|
||
device.configure()
|
||
while True:
|
||
started = time.monotonic()
|
||
print_reading(take_reading(device, args.samples, args.calibration_factor))
|
||
if not args.watch:
|
||
return
|
||
elapsed = time.monotonic() - started
|
||
time.sleep(max(0.0, args.interval - elapsed))
|
||
|
||
|
||
def main(argv: Sequence[str] | None = None) -> int:
|
||
args = build_parser().parse_args(argv)
|
||
if args.self_test:
|
||
run_self_test()
|
||
return 0
|
||
|
||
try:
|
||
run_hardware(args)
|
||
except KeyboardInterrupt:
|
||
print("\n已停止。")
|
||
return 0
|
||
except (AdcError, ValueError) as exc:
|
||
print(f"错误：{exc}", file=sys.stderr)
|
||
return 2
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|