Photonicat Wiki - 最近更改 [zh-cn]

Photonicat 2 固件USB线刷更新教程

Monstercat — Mon, 27 Jul 2026 07:59:12 GMT

←上一版本		2026年7月27日 (一) 15:59的版本
第8行：		第8行：
	[[File:burn-usb-line-wiki.png\|500px]]		[[File:burn-usb-line-wiki.png\|500px]]
	*下载最新烧录工具版本最新烧录工具		*下载最新烧录工具版本最新烧录工具
	::*[https://dl.photonicat.com/tools/~~RKDevTool_Release_v2~~.86.zip ~~RKDevTool_Release_v2~~.86]		::*[https://dl.photonicat.com/tools/RKDevTool_Release_v3.36.zip RKDevTool_Release_v3.36]
	::*[https://dl.photonicat.com/tools/DriverAssitant_v5.1.1.zip 驱动]		::*[https://dl.photonicat.com/tools/DriverAssitant_v5.1.1.zip 驱动]
	*下载下载RK3576的MiniLoaderAll.bin文件		*下载下载RK3576的MiniLoaderAll.bin文件

Photonicat 2 SOC Calculation

C2h2 — Sun, 26 Jul 2026 12:03:35 GMT

Tighten prose: state how each stage works rather than motivating it; note k(T) is a piecewise-linear NCA approximation clamped outside -20..40C; link the MCU protocol page

显示更改

Photonicat 2 SOC 计算

C2h2 — Sun, 26 Jul 2026 12:01:56 GMT

Tighten prose: state how each stage works rather than motivating it; note k(T) is a piecewise-linear NCA approximation clamped outside -20..40C; link the MCU protocol page

显示更改

Main Page

C2h2 — Sun, 26 Jul 2026 11:55:53 GMT

Photonicat 2代用户手册 User Manual

←上一版本		2026年7月26日 (日) 19:55的版本
（未显示同一用户的2个中间版本）
第78行：		第78行：
	===入门 Getting Started===		===入门 Getting Started===
	{\|width="90%"		{\|width="90%"
	\|[[Photonicat 2 新手入门指南]]		\|align="left" width="25%"\|[[Photonicat 2 新手入门指南]]
	\|[[Photonicat 2 LED 指示灯]]（[[Photonicat 2 LED Indicator\|EN]]）		\|align="left" width="25%"\|[[Photonicat 2 LED 指示灯]]（[[Photonicat 2 LED Indicator\|EN]]）
	\|[[Photonicat 2 提示音说明]]（[[Photonicat 2 Sound Guide\|EN]]）		\|align="left" width="25%"\|[[Photonicat 2 提示音说明]]（[[Photonicat 2 Sound Guide\|EN]]）
	\|[[Photonicat 2 小屏幕自定义]]		\|align="left" width="25%"\|[[Photonicat 2 小屏幕自定义]]
			\|-
			\|align="left" width="25%"\|
			\|align="left" width="25%"\|
			\|align="left" width="25%"\|
			\|align="left" width="25%"\|
	\|}		\|}

	===固件更新 Firmware Update===		===固件更新 Firmware Update===
	{\|width="90%"		{\|width="90%"
	\|[[Photonicat 2 固件在线升级更新]]		\|align="left" width="25%"\|[[Photonicat 2 固件在线升级更新]]
	\|[[Photonicat 2 OTA更新]]		\|align="left" width="25%"\|[[Photonicat 2 OTA更新]]
	\|[[Photonicat 2 固件USB线刷更新教程]]		\|align="left" width="25%"\|[[Photonicat 2 固件USB线刷更新教程]]
			\|align="left" width="25%"\|[[Photonicat 2 MCU 手动更新]]
	\|-		\|-
	\|~~[[Photonicat 2 MCU 手动更新]]~~		\|align="left" width="25%"\|[[Photoincat 2 第三方固件更新]]
	\|[[Photoincat 2 第三方固件更新]]		\|align="left" width="25%"\|[[Photonicat 2 固件 Changelog]]
	\|[[Photonicat 2 固件 Changelog]]		\|align="left" width="25%"\|
			\|align="left" width="25%"\|
	\|}		\|}

	===网络功能 Networking===		===网络功能 Networking===
	{\|width="90%"		{\|width="90%"
	\|[[Photonicat 2 Smart WAN 智能上网]]		\|align="left" width="25%"\|[[Photonicat 2 Smart WAN 智能上网]]
	\|[[Photonicat 2 多出口与故障切换]]		\|align="left" width="25%"\|[[Photonicat 2 多出口与故障切换]]
	\|[[Photonicat 2 访客门户 Captive Portal]]		\|align="left" width="25%"\|[[Photonicat 2 访客门户 Captive Portal]]
			\|align="left" width="25%"\|[[Photoincat 2 IPv6 PPPoE]]
	\|-		\|-
	\|~~[[Photoincat 2 IPv6 PPPoE]]~~		\|align="left" width="25%"\|[[Photonicat2 无线桥接]]
	\|[[Photonicat2 无线桥接]]		\|align="left" width="25%"\|[[Photonicat 2 管理界面新功能 (2026)]]
	\|[[Photonicat 2 管理界面新功能 (2026)]]		\|align="left" width="25%"\|
			\|align="left" width="25%"\|
	\|}		\|}

	===硬件扩展 Hardware===		===硬件扩展 Hardware===
	{\|width="90%"		{\|width="90%"
	\|[[Photonicat 2 Wifi/WWAN/NVME M2 兼容模块]]		\|align="left" width="25%"\|[[Photonicat 2 Wifi/WWAN/NVME M2 兼容模块]]
	\|[[Photonicat 2 spec\|Photonicat 2 规格]]		\|align="left" width="25%"\|[[Photonicat 2 spec\|Photonicat 2 规格]]
			\|align="left" width="25%"\|
			\|align="left" width="25%"\|
	\|}		\|}

	===开发者 Developers===		===开发者 Developers===
	{\|width="90%"		{\|width="90%"
	\|[[Photonicat 2 开发者 API]]		\|align="left" width="25%"\|[[Photonicat 2 开发者 API]]
	\|[[Photonicat 2 sysfs]]		\|align="left" width="25%"\|[[Photonicat 2 sysfs]]
	\|[[Photonicat 2 Docker 使用指南]]		\|align="left" width="25%"\|[[Photonicat 2 Docker 使用指南]]
			\|align="left" width="25%"\|[[Build system image for photonicat2]]
	\|-		\|-
	\|[[~~Build system image for photonicat2~~]]		\|align="left" width="25%"\|[[Photonicat 2 MCU 通讯协议]]
	\|[[~~MCU 控制协议~~]]		\|align="left" width="25%"\|[[Photonicat 2 SOC 计算]]（[[Photonicat 2 SOC Calculation\|EN]]）
	\|[[~~PMU Protocol~~]]		\|align="left" width="25%"\|
			\|align="left" width="25%"\|
	\|}		\|}

Photonicat MCU 通讯协议

C2h2 — Sun, 26 Jul 2026 09:42:53 GMT

Template:Note does not exist on this wiki; use plain bold

@@ 第1行： / 第1行： @@
-===物理层协议===
+'''注意：'''本页内容已迁移。Photonicat 2（RK3576）与一代的完整 MCU 通讯协议现在统一
-*通过串口通讯，115200波特率，校验位无，数据位8位，停止位1位
+维护在 '''[[Photonicat 2 MCU 通讯协议]]'''，包含状态帧完整字段表、电池信息查询、
-===帧格式表===
+请前往 '''[[Photonicat 2 MCU 通讯协议]]'''。
-====数据位表====
+相关：[[Photonicat 2 sysfs]] · [[Photonicat 2 SOC 计算]] · [[Photonicat 2 开发者 API]]

Photonicat 2 MCU 通讯协议

C2h2 — Sun, 26 Jul 2026 09:42:04 GMT

Create: full Photonicat 2 MCU UART protocol (frame format, status frame field table, battery info v9, charge limit, fan/thermal, beep, OTA)

新页面

本页描述 '''Photonicat 2''' 主机（RK3576）与电源管理 MCU（Renesas RA2E1）之间的
串口通讯协议。协议同样适用于一代（RK3568），但一代的电压阈值是单节锂电语义，
详见下方"与一代的差异"。

相关页面：[[Photonicat 2 sysfs]]（内核已经把电源/RTC 数据导出成标准接口，
一般应用'''不需要'''自己解析本协议）、[[Photonicat 2 SOC 计算]]（状态帧里的
电量是怎么算出来的）、[[Photonicat 2 LED 指示灯]]、[[Photonicat 2 提示音说明]]。

== 先读这里：你可能不需要这个协议 ==

绝大多数应用不应该直接收发本协议。主机侧已经有两层封装：

{| class="wikitable"
! 你想做的事 !! 推荐用法
|-
| 读电量/电压/电流/充电器状态 || <code>/sys/class/power_supply/*</code>，见 [[Photonicat 2 sysfs]]
|-
| 读写时间 || <code>hwclock</code> / <code>/dev/rtc</code>（MCU 就是硬件 RTC）
|-
| 风扇转速、温度 || <code>/sys/class/hwmon/*</code>、<code>/sys/class/thermal/*</code>
|-
| 网页界面里的各种设置 || pcat-manager 的 REST API，见 [[Photonicat 2 开发者 API]]
|-
| 上面都覆盖不到的功能 || 才需要本页的协议
|}

串口本身由内核驱动 <code>photonicat-pm</code> 和用户态守护进程
'''pcat-manager''' 占用。第三方程序直接抢串口会和它们冲突。

== 物理层 ==

* 串口，'''115200''' 波特率，8 数据位，无校验，1 停止位（8N1）
* 主机侧设备：一代为 <code>/dev/ttyS4</code>；二代由设备树绑定给
<code>photonicat-pm</code> 驱动（serdev），不再以裸 tty 暴露

== 帧格式 ==

{| class="wikitable"
! 字节 !! 字段 !! 说明
|-
| 0 || 起始位 || 固定 '''0xA5'''
|-
| 1 || 源地址 || 见地址表
|-
| 2 || 目的地址 || 见地址表
|-
| 3–4 || 帧序号 || 小端 uint16，主动发送方每发一帧加一，溢出回零；应答沿用请求的帧序号
|-
| 5–6 || 数据长度 || 小端 uint16，指"命令号 + 命令内容 + 是否需要回复"三段的总字节数
|-
| 7–8 || 命令号 || 小端 uint16
|-
| 9… || 命令内容 || 变长，见各命令说明
|-
| 倒数第 4 || 是否需要回复 || 1 = 需要应答，0 = 不需要
|-
| 倒数第 3、2 || CRC16 || 对'''从字节 1 到"是否需要回复"为止'''的所有字节计算，小端
|-
| 最后 1 || 结束位 || 固定 '''0x5A'''
|}

一帧总长 = 数据长度 + 10。接收方据此校验，长度对不上直接丢弃。

=== 地址表 ===

{| class="wikitable"
! 值 !! 含义
|-
| 0x01 || 第一块 CPU 板（目前只有一块，主机固定用 0x01）
|-
| 0x02 / 0x03 || 第二、三块 CPU 板（预留）
|-
| 0x80 || 广播给所有 CPU 板
|-
| 0x81 || 电源管理 MCU（RA2E1）
|-
| 0xFE || 广播给所有 RA2E1
|-
| 0xFF || 广播给系统内所有设备
|}

=== 命令号约定 ===

'''奇数 = 请求，偶数 = 对应的应答'''（应答号 = 请求号 + 1）。这条规则贯穿整个
协议，MCU 内部就是按 <code>命令号 % 2</code> 来分发的。

== 命令一览 ==

=== 基础与版本 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''1''' / 2 || CPU → MCU || 无 || 心跳。超过 1 分钟没有收到任何数据，MCU 会重启主机
|-
| '''3''' / 4 || CPU → MCU || 应答含 8 字节字符串 || 读硬件版本，例如 <code>NT2421A4</code>
|-
| '''5''' / 6 || CPU → MCU || 应答含 14 字节字符串 || 读软件版本，例如 <code>RA2E1260726005</code>
|-
| '''139''' / 140 || CPU → MCU || —— || 读硬件 ID
|-
| '''159''' / 160 || CPU → MCU || —— || 读 bootloader 版本号
|}

=== 状态上报（7） ===

'''MCU → CPU'''，周期性主动上报，是整个协议里最重要的一帧。数据长度 56。
下表偏移量以'''命令内容'''首字节为 0（即整帧的字节 9）：

{| class="wikitable"
! 偏移 !! 长度 !! 字段 !! 单位 / 说明
|-
| 0 || 2 || 电池电压 || mV，小端
|-
| 2 || 2 || 充电器接口电压 || mV，小端
|-
| 4 || 2 || 输入 GPIO 状态 || 位域
|-
| 6 || 2 || 输出 GPIO 状态 || 位域
|-
| 8 || 8 || 系统时间 || 年(2) 月日时分秒星期，各 1 字节
|-
| 16 || 1 || RTC 状态 || 0 正常，1 初始化异常，2 无秒中断，3 无分钟中断
|-
| 17 || 1 || 板子温度 || '''实际温度 = 本字节 − 100'''（℃）
|-
| 18 || 2 || 电池电流 || mA，'''有符号'''小端。正 = 放电，负 = 充电
|-
| 20 || 2 || 剩余容量 || mAh
|-
| 22 || 1 || 电量 || %（1–100，算法见 [[Photonicat 2 SOC 计算]]）
|-
| 23 || 4 || 当前能量 || mWh，小端
|-
| 27 || 4 || 满电能量 || mWh，小端（学习值，可与标称对比看老化）
|-
| 31 || 4 || 累计开机时长 || 秒，小端
|-
| 35 || 4 || 加速度 X || 1/16384 g，有符号小端
|-
| 39 || 4 || 加速度 Y || 同上
|-
| 43 || 4 || 加速度 Z || 同上
|-
| 47 || 1 || 加速度数据就绪 || 非 0 表示有效
|-
| 48 || 4 || 风扇转速 || RPM，小端
|-
| 52 || 1 || 充电状态 || 0 未充电，1 小电流充电，2 大电流充电，3 已充满
|}

'''向后兼容''':这一帧只在尾部追加字段，从不改动已有偏移。解析时应按
"长度至少为 N 才读第 N 个字段"的方式写，不要假设固定总长。

=== 时间与定时开机 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''9''' / 10 || CPU → MCU || 年(2) 月日时分秒，共 7 字节 || 设置 MCU 时间
|-
| '''11''' / 12 || CPU → MCU || 见下 || 设置定时开机
|}

定时开机每条 8 字节：年(2) 月日时分星期，再加 1 字节匹配掩码。
掩码 bit0 年、bit1 月、bit2 日、bit3 时、bit4 分、bit5 星期，
置 1 表示该项参与匹配。'''分匹配必须为 1'''，否则该条被忽略。
星期按位匹配，例如 <code>0b00000101</code> 表示周日和周二。
一次最多 6 条，覆盖之前的设置，故该段最长 48 字节。

=== 关机与复位 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''13''' / 14 || MCU → CPU || 1 字节关机事件 || MCU 通知主机即将关机
|-
| '''15''' / 16 || CPU → MCU || 无 || 主机请求关机
|-
| '''17''' / 18 || MCU → CPU || 无 || MCU 通知主机复位
|}

关机事件取值：0 按键强制关机，1 电池低电压关机，2 升级前关机，3 其他。

=== 开机原因（27） ===

CPU → MCU 查询，应答 1 字节：

{| class="wikitable"
! 值 !! 含义
|-
| 1 || 按键开机
|-
| 2 || 定时开机
|-
| 3 || 车载模式：插入充电器开机
|-
| 4 || 低电压关机后，插入充电器且电压满足条件开机
|-
| 5 || 无电池开机
|-
| 6 || 家庭模式：充电器电压满足条件开机
|}

=== 看门狗与电源策略 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''19''' / 20 || CPU → MCU || 3 字节：开机超时、关机超时、喂狗超时（秒） || 设置软件看门狗时间
|-
| '''21''' / 22 || CPU → MCU || 1 字节 || 0 = 插充电器不自动开机，1 = 插充电器开机。（低电压关机的机器即使设 0 也会开机）
|-
| '''157''' / 158 || CPU → MCU || 1 字节 || 硬件看门狗开关
|-
| '''161''' / 162 || CPU → MCU || 1 字节 || 设置设备模式（车载 / 家庭等）
|}

=== 电压阈值（23） ===

CPU → MCU，'''18 字节'''，9 个 uint16 小端。二代为 2S 电池组，单位 mV，
数值是'''整包'''电压：

# 电压高指示阈值
# 电压中指示阈值
# 电压低指示阈值
# 插充电器开机电压
# 充电器在位判定电压
# 充电器不在时关机电池阈值
# 工作中低电压提示阈值
# 大电流充电电压阈值
# 开机后持续 15 分钟判定满电的电压阈值

超出默认值 ±1000 mV 的设置视为无效，MCU 会退回默认值。

'''注意''':一代文档里的 3850 / 3700 / 3600 等是'''单节'''数值。二代是 2S，
默认值不同（例如低电告警 6500、强制关机 6300），不要照搬一代的数字。
各阈值的实际效果见 [[Photonicat 2 LED 指示灯]]。

=== 温度阈值（145） ===

CPU → MCU，2 字节：

* 第 1 字节：主机断电温度（℃），有效范围 '''55–80'''，默认 75
* 第 2 字节：充电指示灯关闭温度（℃），有效范围 '''50–60'''，默认 53

超范围返回错误，不生效。温度过高触发断电时会播放提示音，
见 [[Photonicat 2 提示音说明]]。

=== 风扇 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''147''' / 148 || CPU → MCU || 1 字节占空比（0–100） || 主机直接接管风扇。'''一旦下发，MCU 内部的温控 PID 不再控制风扇'''；超过 100 返回错误
|-
| '''151''' / 152 || CPU → MCU || 目标温度 || 设置风扇 PID 的目标温度，默认 47 ℃
|-
| '''153''' / 154 || CPU → MCU || —— || 读取当前目标温度
|}

未被主机接管时，MCU 用增量式 PID 控制风扇：目标温度 47 ℃，
充电时占空比上限 85 %，纯电池运行时上限 40 %。

=== 指示灯与声音 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''25''' / 26 || CPU → MCU || 6 字节 || 设置网络指示灯：高电平时长(2)、低电平时长(2)、变换次数(2)，时长单位 10 ms，次数 0 表示一直闪
|-
| '''155''' / 156 || CPU → MCU || 1 字节 || 声光模式：0x00 全关，0x01 关声音开灯光，0x02 开声音关灯光，0x03 全开；传 '''0xFF''' 为查询当前值
|-
| '''163''' / 164 || CPU → MCU || 见下 || 播放自定义蜂鸣器序列
|}

'''自定义蜂鸣器序列（163）'''载荷格式：

[步进 1][步进 2]…[步进 N][循环模式 1 字节]

每个步进 4 字节：频率 uint16 小端（Hz，0 = 休止）+ 时长 uint16 小端（ms）。
循环模式 0 = 播放一次，1 = 循环。时长为 0 会被当作 1 ms。
声音被关闭时该命令不执行。内置提示音见 [[Photonicat 2 提示音说明]]。

=== 电池与充电 ===

{| class="wikitable"
! 命令 !! 方向 !! 内容 !! 说明
|-
| '''165''' / 166 || CPU → MCU || 1 字节百分比 || 设置充电上限，有效范围 '''50–100'''，100 = 不限制。超范围返回错误
|-
| '''167''' / 168 || CPU → MCU || 应答 1 字节 || 读取当前充电上限
|-
| '''169''' / 170 || CPU → MCU || 应答见下 || 读取电池详细信息
|-
| '''141''' / 142 || CPU → MCU || 1 字节 || '''已废弃'''，保留解析以兼容老主机，行为等同空操作
|}

充电上限自固件 '''RA2E1260726005''' 起持久化在 MCU 侧，复位和 OTA 后不丢失。
到达上限后 MCU 断开充电 MOSFET，回落约 2 % 后恢复充电。

==== 电池信息（169）应答格式 ====

应答是'''逐版本向尾部追加'''的结构，当前长度 59 字节。偏移以应答的命令内容
首字节为 0，全部小端：

{| class="wikitable"
! 偏移 !! 长度 !! 字段 !! 说明
|-
| 0 || 2 || 学习到的满容量 || mAh
|-
| 2 || 2 || 循环次数 || ——
|-
| 4 || 2 || 标称满容量 || mAh
|-
| 6 || 1 || 标志位 || bit0 = 容量为学习值，bit1 = 学习窗口进行中
|-
| 7 || 2 || 内阻 || mΩ，整包串联值，归一到 25 ℃
|-
| 9 || 4 || 累计开机秒数 || ——
|-
| 13 || 2 || 电池中点电压 || mV（2P2S 中心抽头）
|-
| 15 || 2 || 内部 SOC || ×10，显示修饰前
|-
| 17 || 1 || 学习到的显示空点 || %，0 = 未学习
|-
| 18 || 2 || 显示变换 a || ×1000
|-
| 20 || 2 || 显示变换 b || ×100，有符号
|-
| 22 || 2 || 充电电流增益 || ×1000
|-
| 24 || 2 || 电流微调 a || ×1000
|-
| 26 || 2 || 电流微调 b || mA，有符号
|-
| 28 || 2 || 估算剩余容量 || mAh
|-
| 30 || 4 || 累计消耗能量 || mWh
|-
| 34 || 4 || 累计充入能量 || mWh
|-
| 38 || 1 || '''协议版本号''' || 当前 9
|-
| 39 || 1 || 电池健康度 || %，0xFF = 尚未学习
|-
| 40 || 2 || 预计可用时间 || 分钟，0xFFFF = 非稳定放电
|-
| 42 || 2 || 预计充满时间 || 分钟，0xFFFF = 非稳定充电
|-
| 44 || 1 || 库仑计在用温度 || ℃，有符号
|-
| 45 || 1 || 低温空点上移 || ×10 %，常温 = 0
|-
| 46 || 2 || 内阻温度倍率 k(T) || ×1000，25 ℃ = 1000
|-
| 48 || 1 || 回路寄生电阻 || mΩ（线缆+接插件+MOSFET）。电芯本体内阻 = 偏移 7 的值 − 本值
|-
| 49 || 4 || MCU 总运行秒数 || 自 MCU 复位起，看门狗/异常复位会清零
|-
| 53 || 4 || 距上次休眠唤醒秒数 || 从未休眠则等于总运行秒数
|-
| 57 || 2 || 进入待机次数 || 饱和计数
|}

偏移 38 之前的版本靠'''应答长度'''区分（≥7、≥13、≥15、≥28、≥38…）；
从版本 9 起有显式版本号字段，建议新代码优先读它。这些字段的物理含义见
[[Photonicat 2 SOC 计算]]。

=== 抬腕唤醒（149） ===

MCU → CPU 主动上报抬腕/移动事件。对应 sysfs 的
<code>/sys/kernel/photonicat-pm/movement_trigger</code>。

=== MCU 固件升级 ===

这一组命令由 pcat-manager 的升级工具使用，'''不建议手工调用'''——
中断升级流程可能使 MCU 无法启动。正常升级方式见
[[Photonicat 2 MCU 手动更新]]。

{| class="wikitable"
! 命令 !! 说明
|-
| '''129''' / 130 || 请求进入升级模式
|-
| '''203''' / 204 || 开始 OTA
|-
| '''205''' / 206 || 传送版本号
|-
| '''207''' / 208 || OTA 结束
|-
| '''209''' / 210 || 回报"已收到结束"
|-
| '''211''' / 212 || 传输 OTA 数据
|-
| '''213''' / 214 || 接收就绪
|-
| '''215''' / 216 || 长度校验正确
|-
| '''217''' / 218、'''219''' / 220 || 新区域拷贝到备份区 / 拷贝完成
|-
| '''221''' / 222、'''223''' / 224 || 擦除 SPI 最新区 / 备份区
|}

=== 错误上报（201） ===

MCU → CPU，用于上报解析或执行错误。

== 与一代的差异 ==

* 一代主机是 RK3568，二代是 RK3576
* 一代是单节锂电，命令 23 的阈值是单节电压（3850 / 3700 / 3600 等）；
二代是 2S 电池组，同样的字段是整包电压（约为一代的两倍）
* 一代只有命令 1–28；二代在 129 以上扩展了 ID、风扇、温度、声光、
电池信息、充电上限等
* 一代靠 pcat-manager 的 socket 对外提供数据；二代已集成进内核，
推荐直接读 sysfs，见 [[Photonicat 2 sysfs]]

== 参考实现 ==

* 主机侧用户态：pcat-manager <code>src/pmu-manager.c</code>
* 主机侧内核：<code>photonicat-pm</code>（power_supply + RTC）
* 一代参考：[https://github.com/photonicat/rockchip_rk3568_pcat_manager/blob/master/src/pmu-manager.c rockchip_rk3568_pcat_manager]

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 09:25:27 GMT

Point cross-links at the renamed SOC pages directly instead of via redirects

←上一版本		2026年7月26日 (日) 17:25的版本
第111行：		第111行：
	* 🔴 红色仅用于低电量提示，会持续闪烁直到电压回升或接入充电器。		* 🔴 红色仅用于低电量提示，会持续闪烁直到电压回升或接入充电器。
	* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。		* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。
	* 指示灯依据的电量是怎么算出来的，见 [[~~光影猫2 是如何计算电量的~~]]。		* 指示灯依据的电量是怎么算出来的，见 [[Photonicat 2 SOC 计算]]。

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]

Photonicat 2 LED Indicator

C2h2 — Sun, 26 Jul 2026 09:25:25 GMT

Point cross-links at the renamed SOC pages directly instead of via redirects

←上一版本		2026年7月26日 (日) 17:25的版本
第111行：		第111行：
	* 🔴 Red is only ever used for low battery, and keeps flashing until the voltage recovers or a charger is connected.		* 🔴 Red is only ever used for low battery, and keeps flashing until the voltage recovers or a charger is connected.
	* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.		* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.
	* For how the charge level behind these indications is computed, see [[~~How~~ Photonicat 2 ~~Calculates~~ SOC]].		* For how the charge level behind these indications is computed, see [[Photonicat 2 SOC Calculation]].

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]

Photonicat 2 sysfs

C2h2 — Sun, 26 Jul 2026 09:25:23 GMT

Point cross-links at the renamed SOC pages directly instead of via redirects

←上一版本		2026年7月26日 (日) 17:25的版本
第75行：		第75行：
	* 写操作（风扇档位、背光）需 root；接口是否存在取决于驱动与机型。		* 写操作（风扇档位、背光）需 root；接口是否存在取决于驱动与机型。
	* 从一代迁移到二代：优先改为读取上述 sysfs 路径，原 socket 方案仅作为兼容保留。		* 从一代迁移到二代：优先改为读取上述 sysfs 路径，原 socket 方案仅作为兼容保留。
	* '''capacity 这个数字是怎么来的''' —— 库仑计的完整原理（硬件测量、积分、OCV 融合、自学习、温度补偿）见 [[~~光影猫2 是如何计算电量的~~]]（English: [[~~How~~ Photonicat 2 ~~Calculates~~ SOC]]）。		* '''capacity 这个数字是怎么来的''' —— 库仑计的完整原理（硬件测量、积分、OCV 融合、自学习、温度补偿）见 [[Photonicat 2 SOC 计算]]（English: [[Photonicat 2 SOC Calculation]]）。

Photonicat 2 SOC Calculation

C2h2 — Sun, 26 Jul 2026 09:25:21 GMT

Point cross-links at the renamed SOC pages directly instead of via redirects

←上一版本		2026年7月26日 (日) 17:25的版本
第8行：		第8行：

	For the indicator see [[Photonicat 2 LED Indicator]]; for sysfs paths see		For the indicator see [[Photonicat 2 LED Indicator]]; for sysfs paths see
	[[Photonicat 2 sysfs]]. 中文版见 [[~~光影猫2 是如何计算电量的~~]]。		[[Photonicat 2 sysfs]]. 中文版见 [[Photonicat 2 SOC 计算]]。

	== Why voltage alone is not enough ==		== Why voltage alone is not enough ==

Photonicat 2 SOC 计算

C2h2 — Sun, 26 Jul 2026 09:25:18 GMT

Point cross-links at the renamed SOC pages directly instead of via redirects

←上一版本		2026年7月26日 (日) 17:25的版本
第7行：		第7行：

	指示灯说明见 [[Photonicat 2 LED 指示灯]]，sysfs 路径见 [[Photonicat 2 sysfs]]。		指示灯说明见 [[Photonicat 2 LED 指示灯]]，sysfs 路径见 [[Photonicat 2 sysfs]]。
	English: [[~~How~~ Photonicat 2 ~~Calculates~~ SOC]]。		English: [[Photonicat 2 SOC Calculation]]。

	== 为什么不能只看电压 ==		== 为什么不能只看电压 ==

How Photonicat 2 Calculates SOC

C2h2 — Sun, 26 Jul 2026 09:24:51 GMT

C2h2移动页面How Photonicat 2 Calculates SOC至Photonicat 2 SOC Calculation Align with the Photonicat 2 topic prefix used by sibling pages

新页面

'''Photonicat 2''' does not guess the battery level from voltage. It runs a
proper '''coulomb counter''' (also called a fuel gauge): think of it as a water
meter on the battery, accounting for every milliamp-second in and out.

This page explains how that system works — from the measuring hardware, through
the firmware's integration, self-learning and temperature compensation, to the
Linux kernel driver that turns it all into ordinary sysfs files.

For the indicator see [[Photonicat 2 LED Indicator]]; for sysfs paths see
[[Photonicat 2 sysfs]]. 中文版见 [[光影猫2 是如何计算电量的]]。

== Why voltage alone is not enough ==

This is the first problem every fuel gauge has to solve. A lithium cell's
voltage-vs-charge curve is remarkably flat in the middle. The figures below come
from the firmware's '''discharge OCV table''' (IR-compensated pack voltage):

{| class="wikitable"
! Pack OCV (open-circuit voltage) !! Charge level
|-
| 7.58 V || 70 %
|-
| 7.50 V || 60 %
|-
| 7.44 V || 50 %
|-
| 7.36 V || 40 %
|-
| 7.28 V || 30 %
|}

Going from 70 % down to 30 % moves the voltage by just '''0.30 V''' — roughly
'''6 mV per percent'''. Put a load on the battery and the IR drop across its
internal resistance easily amounts to tens of millivolts. In other words,
'''voltage alone can be off by more than 10 %''', and it gets worse the heavier
the load.

The two ends, by contrast, are steep: in this table 8.34 V is 100 % and 6.34 V is
0 %. So the right approach is to '''anchor at the ends with voltage and advance
through the middle by integration''' — which is exactly what the system below
does.

== The idea in one line ==

charge = starting charge − ∫(discharge current)dt + ∫(charge current)dt

The integral itself is accurate, provided the current measurement is. But it has
two weaknesses: '''where does the starting point come from''', and '''error
accumulates'''. So a real fuel gauge is integration ''plus'' a set of correction
mechanisms. Photonicat 2 layers them like this:

{| class="wikitable"
! Layer !! Job
|-
| Measurement hardware || TPA626 samples voltage/current every 100 ms
|-
| Coulomb integration || Accumulates current into a µAs ledger every 200 ms
|-
| OCV fusion || At rest, looks up charge from voltage and gently pulls the integral back
|-
| Anchors || At full/empty, pins the value directly to 100 % / 0 %
|-
| Self-learning || Capacity, resistance, empty point and charge gain — learned per unit
|-
| Temperature || Cold raises resistance and shrinks usable capacity; both corrected
|-
| Display layer || Maps internal charge to the 1–100 % the user sees
|}

== 1. Hardware: how it measures ==

The measuring chip is a '''TPA626''' (an I²C current/voltage monitor, in the same
family as the INA226). It sits across a milliohm-class shunt resistor in the
battery path, deriving current from the voltage drop while also measuring bus
voltage.

* '''Sampling''': roughly every 100 ms (<code>VD1_Collect</code>)
* '''Median filtering''': voltage and current each pass through a median filter
that rejects occasional I²C glitches and load spikes
* '''Raw values kept separately''': the median filter lags by about 3 s, which
would smear out the voltage step when a charger is plugged or unplugged — and
the internal-resistance learning depends on exactly that step, so the firmware
keeps unfiltered raw values alongside

=== Current calibration ===

The shunt and amplifier have unit-to-unit variation, so each board is calibrated
against a precision multimeter and fitted to a quadratic:

I_true(mA) = C2·x² + C1·x + C0

Current coefficients (second calibration round, 2026-07-24; residuals ≤3 mA
across four points):

{| class="wikitable"
! Term !! Value !! Purpose
|-
| C2 || −4.444×10⁻⁵ || Quadratic term, corrects high-current nonlinearity
|-
| C1 || 1.0411 || Linear term (gain)
|-
| C0 || +20 mA (discharge) / 0 mA (charge) || Zero offset, per direction
|}

A few engineering details worth calling out:

* '''Clamp before evaluating''': outside the calibrated range the parabola bends
back on itself (vertex near +11.7 A), so the input is clamped to ±3 A and
extended linearly by the endpoint slope beyond that.
* '''64-bit arithmetic''': x² reaches 9×10⁶, which overflows int32 once scaled.
* '''55 mA dead band''': anything smaller counts as zero, so idle noise cannot
slowly skew the ledger.

== 2. Coulomb integration: the ledger ==

<code>coulomb_counter_update()</code> runs every '''200 ms''', multiplying current
by elapsed time into a 64-bit '''µAs (microamp-second)''' ledger. µAs rather than
mAh avoids fixed-point rounding error piling up over long runs.

* Discharge subtracts, charge adds
* Currents under '''30 mA''' in magnitude are ignored (dead band, anti-drift)
* The charge direction carries its own learned '''gain''' — charging is not 100 %
efficient

== 3. OCV fusion: pulling the drift back ==

Integration error accumulates, so whenever the battery is '''near rest''' the
firmware looks up charge from voltage and applies a gentle correction.

The entry conditions are strict, because misjudging "at rest" would drag a
perfectly good integral off course:

{| class="wikitable"
! Condition !! Threshold !! Why
|-
| Current small enough || |I| ≤ 340 mA (~0.05C) || IR-model error is amplified at higher current
|-
| Held long enough || ≥ 30 s || Lets polarisation and surface charge relax
|-
| Voltage slew || ≤ 20 mV/s || Still in a transient, so not really at rest
|-
| Current slew || ≤ 2000 mA/s || Likewise
|-
| Plug/unplug grace || 10 s || Voltage has not settled after a charger event
|}

Even then it does not overwrite — it '''blends''':

* Weight capped at '''α = 0.07''' (OCV contributes at most 7 %), ramping linearly
from 0 over 8 s
* Any single correction is limited to '''0.20 %'''

So OCV nudges the integral back rather than yanking it, and the user never sees
the reading jump.

=== Three OCV tables ===

Lithium cells show '''hysteresis''': at the same charge level, terminal voltage
reads higher while charging and lower while discharging (about 30 mV per cell,
so roughly ±60 mV for a 2S pack). The firmware therefore carries three tables:

* '''Discharge table''' — used in discharge mode (|I| > 900 mA)
* '''Charge table''' — used in charge mode
* '''Rest table''' — the average of the two, used at low current (|I| ≤ 600 mA)

Mode switching is '''hysteretic''' (enter at 900 mA, leave at 600 mA) so it does
not chatter around the threshold.

Before any lookup the reading is '''IR-compensated''': OCV = terminal voltage −
I×R_pack, using the learned resistance described below.

== 4. Anchors: getting the ends right ==

The middle is carried by integration; the two ends are pinned directly:

* '''Full anchor''': charger present, vbus ≥ 8 V, and current has fallen low →
charge = 100 %. Requiring the charger is deliberate: '''resting OCV at 95 % is
about 8.16 V''', so a high but resting pack is easy to mistake for full. A poor
or under-voltage charger cannot push the pack to true full, and is refused.
* '''Empty anchor''': discharged to the cutoff point → charge = 0 %, which also
triggers empty-point learning.

== 5. Self-learning: every unit is different ==

This is the most interesting part of the system. Even within one batch of cells
and boards, unit-to-unit variation can exceed 10 %. So the firmware '''learns
four quantities per unit''' and stores them in data flash, where they survive
power loss.

=== 5.1 Full-capacity learning (ageing) ===

A cell rated 6800 mAh may be down to 5500 mAh after two years. With capacity
hard-coded, an aged pack reads optimistically — the display still shows charge
remaining when the device is about to cut out.

How it learns:

# The full anchor opens a window and zeroes the discharge accumulator
# The pack discharges all the way to the low-voltage cutoff
# Full capacity = accumulated discharge + '''700 mAh'''
# Detecting any charging mid-window voids that attempt

That '''700 mAh''' matters: the device never runs the pack down to a true 0 V, so
at the cutoff (around 6.3–6.45 V) roughly 700 mAh is still left inside and must
be added back.

The learned value also yields '''health''':

health = learned capacity / 6800 mAh

Health is folded in slowly via an EMA (Apple-style gradual change), so a single
measurement never makes it plunge.

=== 5.2 Internal-resistance learning (voltage-step method) ===

IR compensation needs a resistance value. The firmware gets it neatly: at the
'''instant a charger is plugged or unplugged''', current steps by ΔI and voltage
steps by ΔV, so

R = ΔV / ΔI

Conditions: voltage > 7.8 V (near full, otherwise OCV itself drifts with charge
and spoils the measurement), current step ≥ 300 mA, voltage step ≥ 15 mV. Results
fold in by EMA at 3/10 weight, clamped to 10–200 mΩ, defaulting to 50 mΩ.

Note this measures the '''whole loop''': cell body + wiring/connectors (20 mΩ) +
protection-board MOSFET (15 mΩ). IR compensation wants exactly that series total,
so nothing is subtracted; only when the host wants to display "cell internal
resistance" does it subtract the 35 mΩ of board parasitics.

=== 5.3 Empty-point learning ===

A problem found in the field: '''the device cut out while still showing 20 %'''.
Each unit's current-sense gain and true capacity differ slightly, so the moment
internal SOC reaches zero and the moment the hardware actually gives up do not
line up.

The fix is not to touch the current/mAh chain — that would introduce new error —
but to apply a per-unit learned linear map at the '''display layer''':

displayed = (internal SOC − empty) × 100 / (100 − empty)

'''Empty''' is the internal SOC recorded the last time the battery genuinely ran
out. Learning events: a low-voltage shutdown command, an unexpected host death
while discharging at low voltage, or the empty anchor.

There is also '''downward self-correction''': if voltage is still healthy
(> 6.8 V) during discharge but internal SOC has already fallen below the empty
point, then empty was learned too high and follows the reading down. A replaced
battery, or an overshoot, heals within one discharge cycle.

=== 5.4 Charge-gain learning ===

Charging is not 100 % efficient, so charge pushed in differs from charge actually
stored. This gain is learned at the full anchor and written to flash when it moves
by ≥1 %.

== 6. Temperature compensation ==

Lithium cells dislike the cold. An on-board NTC feeds temperature to the coulomb
counter every 200 ms, driving two corrections.

=== 6.1 Resistance temperature factor k(T) ===

Internal resistance varies strongly with temperature, which directly affects IR
compensation:

{| class="wikitable"
! Temperature !! Resistance factor k(T)
|-
| −20 °C || ×3.00
|-
| −10 °C || ×2.30
|-
| 0 °C || ×1.80
|-
| 10 °C || ×1.35
|-
| 25 °C || ×1.00 (reference)
|-
| 40 °C || ×0.85
|}

At −20 °C the resistance is '''three times''' its room-temperature value. The
learned resistance is normalised to 25 °C and multiplied by k(T) in use.

=== 6.2 Cold-weather capacity compensation ===

In the cold, usable capacity shrinks — the energy is not gone, it just cannot be
drawn out. The firmware handles this by '''raising the display empty point''', so
the reading falls earlier and nobody is misled by "15 % left" outdoors at −10 °C:

{| class="wikitable"
! Temperature !! Empty point raised by
|-
| ≥ 15 °C || 0 (no compensation)
|-
| 0 °C || about +4 %
|-
| −10 °C || about +8 %
|-
| ≤ −20 °C || +12 % (capped)
|}

An NTC reading outside −30…70 °C is treated as a fault, and the last valid
temperature is held (initially 25 °C).

== 7. The display curve, and why it is "Tesla-style" ==

The internally computed SOC is not shown directly. One more mapping sits in
between:

* '''4 % → displays 1 %'''
* '''96 % → displays 100 %'''
* Linear in between (slope 99/92), clipped at both ends

The point is that '''when the display reads 0 %, roughly 4 % is still in the
pack''' (plus the hardware margin below the empty point), giving time to save work
and shut down cleanly. Likewise 96 % shows as 100 % so nobody agonises over the
last few percent — both are standard consumer-electronics practice.

The reported percentage is also '''clamped to a minimum of 1 %''': as long as the
device is running, it will not show 0 %.

== 8. After power-off: not losing the reading ==

This is where many fuel gauges fall down. Photonicat 2 has three paths.

=== 8.1 SOC snapshot ===

While running, SOC is written to flash whenever it drifts by ≥5 %; shutdown, host
power-down, standby entry and OTA reset all force a write and refresh the
timestamp.

On boot:

* '''≤12 hours''': SOC = snapshot − 2.0 mA × Δt (standby current), and OCV
re-estimation is '''blocked''' from overriding it. This is what fixed the old
"10 % becomes 1 % after a quick reboot" behaviour.
* '''>12 hours''': the snapshot is stale, so a cold-start OCV estimate is used.

=== 8.2 Deep-sleep discharge estimation ===

In deep sleep the TPA626 is powered down and no current can be measured. The
firmware records an RTC minute stamp on the way in and, on waking, subtracts the
whole-device standby draw of about '''2.0 mA'''.

=== 8.3 Detecting a battery swap ===

Remove the battery and the RTC loses power and resets, so its time runs backwards.
The firmware treats that as a battery swap, voids the snapshot and re-estimates
from cold. (A 10-minute tolerance is allowed; without it, a valid snapshot could
be discarded after an update reboot and the SOC would visibly step.)

== 9. How the data reaches Linux ==

Once the MCU has computed everything, it sends status frames to the host
(RK3576) over '''UART'''. Two consumers sit on the host side.

=== 9.1 Kernel driver: photonicat-pm ===

This is a '''serdev''' driver (<code>990-photonicat-pm-add-driver.patch</code>,
kernel 6.12) that attaches to the serial port, parses status frames, and
registers as standard Linux devices:

* '''power_supply''' class → <code>/sys/class/power_supply/battery</code>
* '''RTC''' class → <code>/dev/rtc</code>

Because these are '''standard subsystems''', any existing Linux tool works
directly — nothing needs to know the private protocol:

<syntaxhighlight lang="bash">
# Charge level (%) — the final output of everything described above
cat /sys/class/power_supply/battery/capacity

# Voltage µV / current µA / power µW
cat /sys/class/power_supply/battery/voltage_now
cat /sys/class/power_supply/battery/current_now
cat /sys/class/power_supply/battery/power_now

# Energy µWh: energy_full is the learned capacity — compare against
# energy_full_design to see ageing
cat /sys/class/power_supply/battery/energy_now
cat /sys/class/power_supply/battery/energy_full
cat /sys/class/power_supply/battery/energy_full_design

# Charger online
cat /sys/class/power_supply/charger/online
</syntaxhighlight>

'''The MCU is the hardware RTC.''' There is no separate RTC chip on the board —
the MCU is always powered, keeps time itself, and sends it up with the status
frames. The driver registers this through <code>rtc_class_ops</code>, so standard
tools just work:

<syntaxhighlight lang="bash">
hwclock -r # read the time from the MCU
hwclock -w # write system time back to the MCU
</syntaxhighlight>

This is why '''the clock is still right after days unplugged and offline''' — and
it is also the mechanism behind the battery-swap detection in 8.3, since a
battery removal resets the RTC and time runs backwards.

=== 9.2 Userspace daemon: pcat-manager ===

The kernel driver only consumes the power-related part of the status frame.
'''The rest of the UART protocol is handled by pcat-manager''': modem management,
watchdog, power on/off policy, button events, pushing the charge threshold down,
MCU firmware updates and so on.

The division of labour:

{| class="wikitable"
! Component !! Responsibility
|-
| MCU firmware || Measurement, integration, learning, compensation — all the algorithms
|-
| photonicat-pm (kernel) || Power/RTC data → standard sysfs interfaces
|-
| pcat-manager (userspace) || Everything else: modem, watchdog, power policy, OTA
|}

A concrete example is the '''charge limit'''. Set 80 % in the web UI and
pcat-manager sends it to the MCU over UART; the MCU stores it in data flash and
drives the charging MOSFET directly. From firmware '''RA2E1260726005''' the
setting persists on the MCU side and survives resets and OTA updates, while
pcat-manager also keeps its own mirror and re-sends it if it detects an MCU
restart — belt and braces.

== 10. FAQ ==

;Why does the reading occasionally jump?
:Usually OCV fusion or an anchor correcting integration drift. A single
correction is capped at 0.20 %, so you should not see large jumps in normal use;
a large one generally means a stale snapshot led to a cold-start re-estimate.

;Why does charge drop faster in winter?
:Two effects together: the pack genuinely has less usable capacity when cold, and
the firmware deliberately raises the display empty point (about +8 % at −10 °C)
so you learn early that it needs charging. It recovers as things warm up.

;Why does 96 % show as 100 %?
:The display curve is designed that way — see section 7. By the same token, there
is still margin left when it reads 0 %.

;Does a new battery need "calibration"?
:Not deliberately. One full discharge (from full down to automatic shutdown) lets
the firmware learn true capacity and the empty point; ordinary use gets there
gradually anyway.

;How often does health update?
:It needs a complete discharge window (full anchor → cutoff), and any charging
mid-window voids it. So it updates slowly and changes gradually by EMA — that is
intentional, so one bad measurement cannot make health plunge.

光影猫2 是如何计算电量的

C2h2 — Sun, 26 Jul 2026 09:24:50 GMT

C2h2移动页面光影猫2 是如何计算电量的至Photonicat 2 SOC 计算 Align with the Photonicat 2 topic prefix used by sibling pages

新页面

'''光影猫2''' 不靠"看电压猜电量"，而是用一套完整的'''库仑计'''（Coulomb
counter，又叫电量计 / fuel gauge）来算电量：像给电池装了一个水表，
进出的每一毫安秒都记账。

本页讲清楚这套系统怎么工作——从硬件怎么测，到固件怎么积分、怎么自学习、
怎么做温度补偿，再到 Linux 内核怎么把它变成 sysfs 文件。

指示灯说明见 [[Photonicat 2 LED 指示灯]]，sysfs 路径见 [[Photonicat 2 sysfs]]。
English: [[How Photonicat 2 Calculates SOC]]。

== 为什么不能只看电压 ==

这是所有电量计要解决的第一个问题。锂电池的"电压—电量"曲线中段非常平。
下面取固件里的'''放电 OCV 表'''（去 IR 后的整包电压）：

{| class="wikitable"
! 整包 OCV（开路电压） !! 对应电量
|-
| 7.58 V || 70 %
|-
| 7.50 V || 60 %
|-
| 7.44 V || 50 %
|-
| 7.36 V || 40 %
|-
| 7.28 V || 30 %
|}

从 70 % 掉到 30 %，电压只降了 '''0.30 V'''——平均每 1 % 电量只对应约
'''6 mV'''。而电池一带负载，内阻上的压降（I×R）轻松就有几十毫伏。也就是说：
'''只看电压，误差可以轻松超过 10 %'''，而且负载越大错得越离谱。

反过来，两端却很陡：这张表里 8.34 V 是 100 %、6.34 V 是 0 %。所以正确做法是
'''两端用电压定位，中间靠积分推进'''——这正是下面这套系统在做的事。

== 一句话原理 ==

电量 = 起点电量 − ∫(放电电流)dt + ∫(充电电流)dt

积分本身很准（电流测得准的话），但有两个毛病：'''起点从哪来'''，以及
'''误差会累积'''。所以真正的电量计 = 积分 + 一套修正机制。光影猫2 的做法是：

{| class="wikitable"
! 层 !! 作用
|-
| 硬件测量 || TPA626 每 100 ms 测一次电压/电流
|-
| 库仑积分 || 每 200 ms 把电流累加进 µAs 账本
|-
| OCV 融合 || 静置时用电压表反查电量，轻轻拉回积分漂移
|-
| 锚点 || 充满 / 欠压时直接把电量钉死到 100 % / 0 %
|-
| 自学习 || 满容量、内阻、空点、充电增益，每台机器各学各的
|-
| 温度补偿 || 冷天内阻变大、可用容量变少，都要修正
|-
| 显示层 || 把内部电量映射成用户看到的 1–100 %
|}

== 一、硬件：怎么测 ==

测量芯片是 '''TPA626'''（I²C 电流/电压监测器，与 INA226 同类）。它串一个
毫欧级采样电阻在电池回路上，测电阻两端压降换算电流，同时测总线电压。

* '''采样周期'''：约 100 ms 一次（<code>VD1_Collect</code>）
* '''中值滤波'''：电压和电流各过一个中值滤波器，滤掉 I²C 偶发抖动和负载尖峰
* '''原始值另存一份'''：中值滤波有约 3 s 滞后，会把"充电器插拔的电压台阶"
抹平，而内阻自学习恰恰要看这个瞬间台阶，所以固件同时保留未滤波的原始值

=== 电流校准 ===

采样电阻和运放都有个体误差，出厂靠精密万用表实测标定，拟合成二次多项式：

I_真实(mA) = C2·x² + C1·x + C0

当前系数（2026-07-24 二轮标定，四点残差 ≤3 mA）：

{| class="wikitable"
! 项 !! 值 !! 说明
|-
| C2 || −4.444×10⁻⁵ || 二次项，修大电流段的非线性
|-
| C1 || 1.0411 || 一次项（增益）
|-
| C0 || +20 mA（放电）/ 0 mA（充电） || 零点偏移，分方向
|}

几个工程细节值得一提：

* '''先夹再算'''：抛物线在标定范围外会"反向弯"（顶点约 +11.7 A），所以先把
输入夹到 ±3 A，域外按端点斜率线性延伸，不让二次项跑飞。
* '''int64 运算'''：x² 最大到 9×10⁶，乘上系数会溢出 int32。
* '''55 mA 死区'''：小于这个值直接当 0，避免待机时账本被噪声慢慢推歪。

== 二、库仑积分：账本 ==

每 '''200 ms''' 调一次 <code>coulomb_counter_update()</code>，把电流乘以时间
累加进一个 '''µAs（微安秒）'''的 64 位账本。用 µAs 而不是 mAh 是为了避免定点
除法的舍入误差在长时间运行后累积。

* 放电减、充电加
* 电流绝对值小于 '''30 mA''' 的部分不计入（死区，防噪声漂移）
* 充电方向另有一个自学习的'''增益系数'''（充电效率不是 100 %）

== 三、OCV 融合：把漂移拉回来 ==

积分误差会累积，所以在'''电池接近静置'''时，用电压反查电量表来轻轻纠正。

触发条件很严格，因为静置判断错了反而会把正确的积分带偏：

{| class="wikitable"
! 条件 !! 阈值 !! 为什么
|-
| 电流足够小 || |I| ≤ 340 mA（约 0.05C） || 电流大时内阻压降的模型误差会放大
|-
| 持续足够久 || ≥ 30 s || 让极化电压和表面电荷弛豫掉
|-
| 电压变化率 || ≤ 20 mV/s || 还在动态过程中就不算静置
|-
| 电流变化率 || ≤ 2000 mA/s || 同上
|-
| 插拔宽限期 || 10 s || 充电器刚插拔，电压还没稳
|}

满足后也不是直接覆盖，而是'''加权融合'''：

* 权重上限 '''α = 0.07'''（OCV 最多只占 7 %），且在 8 s 内从 0 线性爬升
* 单次修正最多 '''0.20 %'''

换句话说，OCV 是"温柔地把积分往回拽"，而不是"一把拽过去"——这样用户看到的
电量不会跳变。

=== 三张 OCV 表 ===

锂电池有'''滞回'''现象：同样的电量，充电时端电压偏高、放电时偏低（约
30 mV/芯，2S 约 ±60 mV）。所以固件带三张表：

* '''放电表'''：进入放电模式（|I| > 900 mA）时用
* '''充电表'''：进入充电模式时用
* '''静置表（REST）'''：充放两表的平均，小电流（|I| ≤ 600 mA）时用

模式切换带'''滞回'''（进 900 mA / 出 600 mA），避免在阈值附近反复横跳。

查表前还要先'''去 IR'''：OCV = 端电压 − I×R_pack，用的就是下面自学习到的内阻。

== 四、锚点：两端归位 ==

中段靠积分，两端靠锚点直接钉死：

* '''满电锚点'''：充电器在位、且 vbus ≥ 8 V、且电流已经很小 → 电量 = 100 %。
要求充电器在位是有原因的：'''95 % 的静置 OCV 约 8.16 V'''，一块高电量的
电池静置着很容易被误判成满电。劣质或欠压的充电器推不到真满，也不给锚。
* '''欠压锚点'''：放到欠压关机点 → 电量 = 0 %，同时触发空点学习。

== 五、自学习：每台机器都不一样 ==

这是这套系统最有意思的部分。同一批电池、同一批板子，个体差异也能有
10 % 以上。所以固件会'''为每台机器单独学习'''四个量，学到的值存进 data flash，
掉电不丢。

=== 5.1 满容量学习（电池老化） ===

标称 6800 mAh 的电池，用两年可能只剩 5500 mAh。如果满容量写死，老化后
SOC 就会偏乐观——显示还有电，实际已经关机了。

学习方法：

# 满电锚点触发时开窗口，累计放电清零
# 一路放电到欠压关机点
# 满容量 = 累计放出的电量 + '''700 mAh'''
# 中途检测到充电 → 本次窗口作废

那个 '''700 mAh''' 是关键：整机不会把电池放到真正的 0 V，在关机点
（约 6.3–6.45 V）时电池包里还剩约 700 mAh 没放出来，必须补回去。

学到的值还会换算成'''健康度'''：

健康度 = 学习容量 / 6800 mAh

健康度采用 EMA 缓慢融入（Apple 式缓变），不会因为一次测量就跳水。

=== 5.2 内阻学习（电压台阶法） ===

去 IR 计算需要知道内阻。固件用一个很巧的办法：'''充电器插拔的瞬间'''，
电流突变 ΔI，电压随之突变 ΔV，那么

R = ΔV / ΔI

条件：电压 > 7.8 V（近满电区，否则 OCV 本身会随电量移动而测不准）、
电流台阶 ≥ 300 mA、电压台阶 ≥ 15 mV。测量结果按 3/10 的权重 EMA 融入，
范围限制在 10–200 mΩ，默认值 50 mΩ。

注意这测到的是'''整包回路电阻''' = 电芯本体 + 线缆/接插件（20 mΩ）+
保护板 MOSFET（15 mΩ）。去 IR 需要的正是这个整包串联值，不做扣减；
上位机若要显示"电芯本体内阻"，才减掉那 35 mΩ 的板级寄生。

=== 5.3 显示空点学习 ===

实测踩过的坑：'''显示还有 20 % 时整机突然断电'''。原因是每台机器的电流计
增益和实际容量都有偏差，内部 SOC 到 0 的那一刻和硬件真正撑不住的那一刻对不齐。

解法不是去改电流链路（那会引入新的误差），而是在'''显示层'''加一个
每台机器自学习的线性映射：

显示值 = (内部SOC − 空点) × 100 / (100 − 空点)

'''空点'''（empty）= 上一次"电池真的没电了"时的内部 SOC。学习事件包括：
低压关机命令、低压下主机意外死机、欠压锚点。

还有'''向下自纠'''：如果放电时电压还很健康（> 6.8 V）但内部 SOC 已经低于
空点，说明空点学高了，就让空点跟着降。这样换了新电池或学过头，都能在一个
放电周期内自愈。

=== 5.4 充电增益学习 ===

充电效率不是 100 %，充进去的电荷和实际存住的电荷有差异。这个增益在满电
锚点时学习，变化 ≥1 % 才落盘。

== 六、温度补偿 ==

锂电池怕冷。板载 NTC 每 200 ms 把温度喂给库仑计，做两件事：

=== 6.1 内阻温度倍率 k(T) ===

内阻随温度显著变化，直接影响去 IR 的准确性：

{| class="wikitable"
! 温度 !! 内阻倍率 k(T)
|-
| −20 °C || ×3.00
|-
| −10 °C || ×2.30
|-
| 0 °C || ×1.80
|-
| 10 °C || ×1.35
|-
| 25 °C || ×1.00（基准）
|-
| 40 °C || ×0.85
|}

也就是说 −20 °C 时内阻是常温的'''三倍'''。学习到的内阻归一在 25 °C 域，
用的时候再乘 k(T)。

=== 6.2 低温可用容量补偿 ===

冷天电池的可用容量会缩水——不是电"没了"，而是低温下拿不出来。固件的处理是
'''把显示空点上移'''，让显示电量提前走低，用户就不会在 −10 °C 的户外被
"还有 15 %"骗了：

{| class="wikitable"
! 温度 !! 空点上移
|-
| ≥ 15 °C || 0（不补偿）
|-
| 0 °C || 约 +4 %
|-
| −10 °C || 约 +8 %
|-
| ≤ −20 °C || +12 %（封顶）
|}

NTC 读数超出 −30…70 °C 视为故障，保持上一次有效温度（初值 25 °C）。

== 七、显示曲线：为什么是"特斯拉式" ==

内部算出来的 SOC 不会直接给用户看，中间还有一层映射：

* '''4 % → 显示 1 %'''
* '''96 % → 显示 100 %'''
* 中段线性（斜率 99/92），两端截断

这样做的意思是：'''显示到 0 % 时，电池里其实还留着约 4 % 的余量'''
（再加上空点以下的硬件余量），用户有时间保存工作、正常关机。同理，充到
96 % 就显示 100 %，避免用户盯着最后几个百分点焦虑——这些都是消费电子的
常规做法。

另外固件上报的百分比'''下限钳在 1 %'''：只要还没关机，就不显示 0 %。

== 八、关机之后：电量怎么不丢 ==

这是很多电量计做不好的地方。光影猫2 有三条路径：

=== 8.1 SOC 快照 ===

运行时 SOC 每漂移 ≥5 % 就自动落盘；关机、主机断电、进待机、OTA 复位前
强制落盘并刷新时间戳。

开机恢复策略：

* '''≤12 小时'''：SOC = 快照 − 2.0 mA × Δt（按待机电流扣减），并'''禁止'''
OCV 重估覆盖。这条修的是"短时重启后 10 % 变 1 %"的老问题。
* '''>12 小时'''：快照过期，走冷启动 OCV 重估。

=== 8.2 深睡放电估计 ===

电池深睡时 TPA626 会掉电，采不到电流。固件在进睡前记下 RTC 分钟戳，
醒来后按整机待机约 '''2.0 mA''' 恒流扣减。

=== 8.3 换电池识别 ===

电池拔掉 → RTC 掉电重置 → 时间倒退。固件据此判定"换过电池"，让快照作废，
重新冷启动估计。（这里留了 10 分钟容差，否则升级重启后一条有效快照会被误判
丢掉，SOC 就会出现台阶跳变。）

== 九、数据怎么到 Linux ==

MCU 算完，通过 '''UART''' 把状态帧发给主机（RK3576）。主机侧有两个消费者：

=== 9.1 内核驱动：photonicat-pm ===

这是一个 '''serdev''' 驱动（<code>990-photonicat-pm-add-driver.patch</code>，
内核 6.12），直接挂在串口上解析状态帧，然后注册成标准 Linux 设备：

* '''power_supply''' 类 → <code>/sys/class/power_supply/battery</code>
* '''RTC''' 类 → <code>/dev/rtc</code>

因为注册的是'''标准子系统'''，所以任何现成的 Linux 工具都能直接用，
不需要认识光影猫的私有协议：

<syntaxhighlight lang="bash">
# 电量（%），这就是上面整套算法的最终输出
cat /sys/class/power_supply/battery/capacity

# 电压 µV / 电流 µA / 功率 µW
cat /sys/class/power_supply/battery/voltage_now
cat /sys/class/power_supply/battery/current_now
cat /sys/class/power_supply/battery/power_now

# 能量 µWh：energy_full 是学习到的满容量，对比 energy_full_design 看老化
cat /sys/class/power_supply/battery/energy_now
cat /sys/class/power_supply/battery/energy_full
cat /sys/class/power_supply/battery/energy_full_design

# 充电器在线
cat /sys/class/power_supply/charger/online
</syntaxhighlight>

'''MCU 就是硬件 RTC。'''板子上没有单独的 RTC 芯片——MCU 一直有电，它自己
就在走时，时间随状态帧一起送上来。驱动把它注册成 <code>rtc_class_ops</code>，
于是标准工具直接可用：

<syntaxhighlight lang="bash">
hwclock -r # 读 MCU 里的时间
hwclock -w # 把系统时间写回 MCU
</syntaxhighlight>

这也是为什么'''断网断电放几天，开机时间还是准的'''。前面 8.3 讲的
"换电池识别"也是靠它——RTC 掉电重置，时间就会倒退。

=== 9.2 用户态守护进程：pcat-manager ===

内核驱动只认状态帧里的电源部分。'''其余的 UART 协议由 pcat-manager 处理'''：
调制解调器管理、看门狗、开关机策略、按键事件、充电阈值下发、MCU 固件升级等。

分工可以这么理解：

{| class="wikitable"
! 组件 !! 负责
|-
| MCU 固件 || 测量、积分、学习、补偿——所有算法
|-
| photonicat-pm（内核） || 电源/RTC 数据 → 标准 sysfs 接口
|-
| pcat-manager（用户态） || 其余协议：调制解调器、看门狗、电源策略、OTA
|}

一个具体例子是'''充电上限'''：你在网页里设 80 %，pcat-manager 通过 UART 下发给
MCU，MCU 把它存进 data flash 并直接控制充电 MOSFET。固件
'''RA2E1260726005''' 起这个设置在 MCU 侧持久化，MCU 复位或 OTA 之后不会丢；
同时 pcat-manager 也保留一份镜像并在检测到 MCU 重启时重新下发，双保险。

== 十、常见问题 ==

;为什么电量偶尔会"跳一下"？
:多半是 OCV 融合或锚点在纠正积分漂移。单次修正被限制在 0.20 %，所以正常情况
你不会看到大跳变；如果出现大跳变，通常是快照过期后走了冷启动重估。

;为什么冬天电量掉得快？
:两个原因叠加：低温下电池可用容量本来就少，加上固件主动把显示空点上移
（−10 °C 约 +8 %），让你提前知道该充电了。回暖后会恢复。

;为什么充到 96 % 就显示 100 %？
:显示曲线刻意这么设计的，见第七节。同理显示 0 % 时电池还有余量。

;新电池要不要"校准"？
:不用刻意做。完整放一次电（从满电放到自动关机）会让固件学到真实满容量和
空点；平时正常使用也会慢慢学到。

;健康度多久更新一次？
:需要一次完整的放电窗口（满电锚点 → 欠压），中途充电会作废。所以它更新得慢，
而且是 EMA 缓变的，这是刻意的——避免单次误测就让健康度跳水。

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 09:22:57 GMT

Move the SOC cross-link above the category tag

←上一版本		2026年7月26日 (日) 17:22的版本
第111行：		第111行：
	* 🔴 红色仅用于低电量提示，会持续闪烁直到电压回升或接入充电器。		* 🔴 红色仅用于低电量提示，会持续闪烁直到电压回升或接入充电器。
	* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。		* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。
			* 指示灯依据的电量是怎么算出来的，见 [[光影猫2 是如何计算电量的]]。

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]
	* 指示灯依据的电量是怎么算出来的，见 [[光影猫2 是如何计算电量的]]。

Photonicat 2 LED Indicator

C2h2 — Sun, 26 Jul 2026 09:22:56 GMT

Move the SOC cross-link above the category tag

←上一版本		2026年7月26日 (日) 17:22的版本
（未显示同一用户的1个中间版本）
第111行：		第111行：
	* 🔴 Red is only ever used for low battery, and keeps flashing until the voltage recovers or a charger is connected.		* 🔴 Red is only ever used for low battery, and keeps flashing until the voltage recovers or a charger is connected.
	* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.		* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.
			* For how the charge level behind these indications is computed, see [[How Photonicat 2 Calculates SOC]].

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 09:22:30 GMT

Link to the coulomb-counter/SOC explainer

←上一版本		2026年7月26日 (日) 17:22的版本
第113行：		第113行：

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]
			* 指示灯依据的电量是怎么算出来的，见 [[光影猫2 是如何计算电量的]]。

Photonicat 2 sysfs

C2h2 — Sun, 26 Jul 2026 09:22:20 GMT

Link to the new coulomb-counter/SOC explainer

←上一版本		2026年7月26日 (日) 17:22的版本
第75行：		第75行：
	* 写操作（风扇档位、背光）需 root；接口是否存在取决于驱动与机型。		* 写操作（风扇档位、背光）需 root；接口是否存在取决于驱动与机型。
	* 从一代迁移到二代：优先改为读取上述 sysfs 路径，原 socket 方案仅作为兼容保留。		* 从一代迁移到二代：优先改为读取上述 sysfs 路径，原 socket 方案仅作为兼容保留。
			* '''capacity 这个数字是怎么来的''' —— 库仑计的完整原理（硬件测量、积分、OCV 融合、自学习、温度补偿）见 [[光影猫2 是如何计算电量的]]（English: [[How Photonicat 2 Calculates SOC]]）。

How Photonicat 2 Calculates SOC

C2h2 — Sun, 26 Jul 2026 09:21:37 GMT

Fix: use | entity for absolute-value bars; backslash escapes are not MediaWiki syntax and rendered literally

←上一版本		2026年7月26日 (日) 17:21的版本
第134行：		第134行：
	! Condition !! Threshold !! Why		! Condition !! Threshold !! Why
	\|-		\|-
	\| Current small enough \|\| \\|I\\| ≤ 340 mA (~0.05C) \|\| IR-model error is amplified at higher current		\| Current small enough \|\| \|I\| ≤ 340 mA (~0.05C) \|\| IR-model error is amplified at higher current
	\|-		\|-
	\| Held long enough \|\| ≥ 30 s \|\| Lets polarisation and surface charge relax		\| Held long enough \|\| ≥ 30 s \|\| Lets polarisation and surface charge relax
第160行：		第160行：
	so roughly ±60 mV for a 2S pack). The firmware therefore carries three tables:		so roughly ±60 mV for a 2S pack). The firmware therefore carries three tables:

	* '''Discharge table''' — used in discharge mode (\\|I\\| > 900 mA)		* '''Discharge table''' — used in discharge mode (\|I\| > 900 mA)
	* '''Charge table''' — used in charge mode		* '''Charge table''' — used in charge mode
	* '''Rest table''' — the average of the two, used at low current (\\|I\\| ≤ 600 mA)		* '''Rest table''' — the average of the two, used at low current (\|I\| ≤ 600 mA)

	Mode switching is '''hysteretic''' (enter at 900 mA, leave at 600 mA) so it does		Mode switching is '''hysteretic''' (enter at 900 mA, leave at 600 mA) so it does

光影猫2 是如何计算电量的

C2h2 — Sun, 26 Jul 2026 09:21:36 GMT

Fix: use | entity for absolute-value bars; backslash escapes are not MediaWiki syntax and rendered literally

←上一版本		2026年7月26日 (日) 17:21的版本
第114行：		第114行：
	! 条件 !! 阈值 !! 为什么		! 条件 !! 阈值 !! 为什么
	\|-		\|-
	\| 电流足够小 \|\| \\|I\\| ≤ 340 mA（约 0.05C） \|\| 电流大时内阻压降的模型误差会放大		\| 电流足够小 \|\| \|I\| ≤ 340 mA（约 0.05C） \|\| 电流大时内阻压降的模型误差会放大
	\|-		\|-
	\| 持续足够久 \|\| ≥ 30 s \|\| 让极化电压和表面电荷弛豫掉		\| 持续足够久 \|\| ≥ 30 s \|\| 让极化电压和表面电荷弛豫掉
第138行：		第138行：
	30 mV/芯，2S 约 ±60 mV）。所以固件带三张表：		30 mV/芯，2S 约 ±60 mV）。所以固件带三张表：

	* '''放电表'''：进入放电模式（\\|I\\| > 900 mA）时用		* '''放电表'''：进入放电模式（\|I\| > 900 mA）时用
	* '''充电表'''：进入充电模式时用		* '''充电表'''：进入充电模式时用
	* '''静置表（REST）'''：充放两表的平均，小电流（\\|I\\| ≤ 600 mA）时用		* '''静置表（REST）'''：充放两表的平均，小电流（\|I\| ≤ 600 mA）时用

	模式切换带'''滞回'''（进 900 mA / 出 600 mA），避免在阈值附近反复横跳。		模式切换带'''滞回'''（进 900 mA / 出 600 mA），避免在阈值附近反复横跳。

How Photonicat 2 Calculates SOC

C2h2 — Sun, 26 Jul 2026 09:21:09 GMT

Create: how the coulomb counter computes SOC (hardware, integration, OCV fusion, self-learning, temperature, Linux sysfs/RTC chain)

新页面

'''Photonicat 2''' does not guess the battery level from voltage. It runs a
proper '''coulomb counter''' (also called a fuel gauge): think of it as a water
meter on the battery, accounting for every milliamp-second in and out.

This page explains how that system works — from the measuring hardware, through
the firmware's integration, self-learning and temperature compensation, to the
Linux kernel driver that turns it all into ordinary sysfs files.

For the indicator see [[Photonicat 2 LED Indicator]]; for sysfs paths see
[[Photonicat 2 sysfs]]. 中文版见 [[光影猫2 是如何计算电量的]]。

== Why voltage alone is not enough ==

This is the first problem every fuel gauge has to solve. A lithium cell's
voltage-vs-charge curve is remarkably flat in the middle. The figures below come
from the firmware's '''discharge OCV table''' (IR-compensated pack voltage):

{| class="wikitable"
! Pack OCV (open-circuit voltage) !! Charge level
|-
| 7.58 V || 70 %
|-
| 7.50 V || 60 %
|-
| 7.44 V || 50 %
|-
| 7.36 V || 40 %
|-
| 7.28 V || 30 %
|}

Going from 70 % down to 30 % moves the voltage by just '''0.30 V''' — roughly
'''6 mV per percent'''. Put a load on the battery and the IR drop across its
internal resistance easily amounts to tens of millivolts. In other words,
'''voltage alone can be off by more than 10 %''', and it gets worse the heavier
the load.

The two ends, by contrast, are steep: in this table 8.34 V is 100 % and 6.34 V is
0 %. So the right approach is to '''anchor at the ends with voltage and advance
through the middle by integration''' — which is exactly what the system below
does.

== The idea in one line ==

charge = starting charge − ∫(discharge current)dt + ∫(charge current)dt

The integral itself is accurate, provided the current measurement is. But it has
two weaknesses: '''where does the starting point come from''', and '''error
accumulates'''. So a real fuel gauge is integration ''plus'' a set of correction
mechanisms. Photonicat 2 layers them like this:

{| class="wikitable"
! Layer !! Job
|-
| Measurement hardware || TPA626 samples voltage/current every 100 ms
|-
| Coulomb integration || Accumulates current into a µAs ledger every 200 ms
|-
| OCV fusion || At rest, looks up charge from voltage and gently pulls the integral back
|-
| Anchors || At full/empty, pins the value directly to 100 % / 0 %
|-
| Self-learning || Capacity, resistance, empty point and charge gain — learned per unit
|-
| Temperature || Cold raises resistance and shrinks usable capacity; both corrected
|-
| Display layer || Maps internal charge to the 1–100 % the user sees
|}

== 1. Hardware: how it measures ==

The measuring chip is a '''TPA626''' (an I²C current/voltage monitor, in the same
family as the INA226). It sits across a milliohm-class shunt resistor in the
battery path, deriving current from the voltage drop while also measuring bus
voltage.

* '''Sampling''': roughly every 100 ms (<code>VD1_Collect</code>)
* '''Median filtering''': voltage and current each pass through a median filter
that rejects occasional I²C glitches and load spikes
* '''Raw values kept separately''': the median filter lags by about 3 s, which
would smear out the voltage step when a charger is plugged or unplugged — and
the internal-resistance learning depends on exactly that step, so the firmware
keeps unfiltered raw values alongside

=== Current calibration ===

The shunt and amplifier have unit-to-unit variation, so each board is calibrated
against a precision multimeter and fitted to a quadratic:

I_true(mA) = C2·x² + C1·x + C0

Current coefficients (second calibration round, 2026-07-24; residuals ≤3 mA
across four points):

{| class="wikitable"
! Term !! Value !! Purpose
|-
| C2 || −4.444×10⁻⁵ || Quadratic term, corrects high-current nonlinearity
|-
| C1 || 1.0411 || Linear term (gain)
|-
| C0 || +20 mA (discharge) / 0 mA (charge) || Zero offset, per direction
|}

A few engineering details worth calling out:

* '''Clamp before evaluating''': outside the calibrated range the parabola bends
back on itself (vertex near +11.7 A), so the input is clamped to ±3 A and
extended linearly by the endpoint slope beyond that.
* '''64-bit arithmetic''': x² reaches 9×10⁶, which overflows int32 once scaled.
* '''55 mA dead band''': anything smaller counts as zero, so idle noise cannot
slowly skew the ledger.

== 2. Coulomb integration: the ledger ==

<code>coulomb_counter_update()</code> runs every '''200 ms''', multiplying current
by elapsed time into a 64-bit '''µAs (microamp-second)''' ledger. µAs rather than
mAh avoids fixed-point rounding error piling up over long runs.

* Discharge subtracts, charge adds
* Currents under '''30 mA''' in magnitude are ignored (dead band, anti-drift)
* The charge direction carries its own learned '''gain''' — charging is not 100 %
efficient

== 3. OCV fusion: pulling the drift back ==

Integration error accumulates, so whenever the battery is '''near rest''' the
firmware looks up charge from voltage and applies a gentle correction.

The entry conditions are strict, because misjudging "at rest" would drag a
perfectly good integral off course:

{| class="wikitable"
! Condition !! Threshold !! Why
|-
| Current small enough || \|I\| ≤ 340 mA (~0.05C) || IR-model error is amplified at higher current
|-
| Held long enough || ≥ 30 s || Lets polarisation and surface charge relax
|-
| Voltage slew || ≤ 20 mV/s || Still in a transient, so not really at rest
|-
| Current slew || ≤ 2000 mA/s || Likewise
|-
| Plug/unplug grace || 10 s || Voltage has not settled after a charger event
|}

Even then it does not overwrite — it '''blends''':

* Weight capped at '''α = 0.07''' (OCV contributes at most 7 %), ramping linearly
from 0 over 8 s
* Any single correction is limited to '''0.20 %'''

So OCV nudges the integral back rather than yanking it, and the user never sees
the reading jump.

=== Three OCV tables ===

Lithium cells show '''hysteresis''': at the same charge level, terminal voltage
reads higher while charging and lower while discharging (about 30 mV per cell,
so roughly ±60 mV for a 2S pack). The firmware therefore carries three tables:

* '''Discharge table''' — used in discharge mode (\|I\| > 900 mA)
* '''Charge table''' — used in charge mode
* '''Rest table''' — the average of the two, used at low current (\|I\| ≤ 600 mA)

Mode switching is '''hysteretic''' (enter at 900 mA, leave at 600 mA) so it does
not chatter around the threshold.

Before any lookup the reading is '''IR-compensated''': OCV = terminal voltage −
I×R_pack, using the learned resistance described below.

== 4. Anchors: getting the ends right ==

The middle is carried by integration; the two ends are pinned directly:

* '''Full anchor''': charger present, vbus ≥ 8 V, and current has fallen low →
charge = 100 %. Requiring the charger is deliberate: '''resting OCV at 95 % is
about 8.16 V''', so a high but resting pack is easy to mistake for full. A poor
or under-voltage charger cannot push the pack to true full, and is refused.
* '''Empty anchor''': discharged to the cutoff point → charge = 0 %, which also
triggers empty-point learning.

== 5. Self-learning: every unit is different ==

This is the most interesting part of the system. Even within one batch of cells
and boards, unit-to-unit variation can exceed 10 %. So the firmware '''learns
four quantities per unit''' and stores them in data flash, where they survive
power loss.

=== 5.1 Full-capacity learning (ageing) ===

A cell rated 6800 mAh may be down to 5500 mAh after two years. With capacity
hard-coded, an aged pack reads optimistically — the display still shows charge
remaining when the device is about to cut out.

How it learns:

# The full anchor opens a window and zeroes the discharge accumulator
# The pack discharges all the way to the low-voltage cutoff
# Full capacity = accumulated discharge + '''700 mAh'''
# Detecting any charging mid-window voids that attempt

That '''700 mAh''' matters: the device never runs the pack down to a true 0 V, so
at the cutoff (around 6.3–6.45 V) roughly 700 mAh is still left inside and must
be added back.

The learned value also yields '''health''':

health = learned capacity / 6800 mAh

Health is folded in slowly via an EMA (Apple-style gradual change), so a single
measurement never makes it plunge.

=== 5.2 Internal-resistance learning (voltage-step method) ===

IR compensation needs a resistance value. The firmware gets it neatly: at the
'''instant a charger is plugged or unplugged''', current steps by ΔI and voltage
steps by ΔV, so

R = ΔV / ΔI

Conditions: voltage > 7.8 V (near full, otherwise OCV itself drifts with charge
and spoils the measurement), current step ≥ 300 mA, voltage step ≥ 15 mV. Results
fold in by EMA at 3/10 weight, clamped to 10–200 mΩ, defaulting to 50 mΩ.

Note this measures the '''whole loop''': cell body + wiring/connectors (20 mΩ) +
protection-board MOSFET (15 mΩ). IR compensation wants exactly that series total,
so nothing is subtracted; only when the host wants to display "cell internal
resistance" does it subtract the 35 mΩ of board parasitics.

=== 5.3 Empty-point learning ===

A problem found in the field: '''the device cut out while still showing 20 %'''.
Each unit's current-sense gain and true capacity differ slightly, so the moment
internal SOC reaches zero and the moment the hardware actually gives up do not
line up.

The fix is not to touch the current/mAh chain — that would introduce new error —
but to apply a per-unit learned linear map at the '''display layer''':

displayed = (internal SOC − empty) × 100 / (100 − empty)

'''Empty''' is the internal SOC recorded the last time the battery genuinely ran
out. Learning events: a low-voltage shutdown command, an unexpected host death
while discharging at low voltage, or the empty anchor.

There is also '''downward self-correction''': if voltage is still healthy
(> 6.8 V) during discharge but internal SOC has already fallen below the empty
point, then empty was learned too high and follows the reading down. A replaced
battery, or an overshoot, heals within one discharge cycle.

=== 5.4 Charge-gain learning ===

Charging is not 100 % efficient, so charge pushed in differs from charge actually
stored. This gain is learned at the full anchor and written to flash when it moves
by ≥1 %.

== 6. Temperature compensation ==

Lithium cells dislike the cold. An on-board NTC feeds temperature to the coulomb
counter every 200 ms, driving two corrections.

=== 6.1 Resistance temperature factor k(T) ===

Internal resistance varies strongly with temperature, which directly affects IR
compensation:

{| class="wikitable"
! Temperature !! Resistance factor k(T)
|-
| −20 °C || ×3.00
|-
| −10 °C || ×2.30
|-
| 0 °C || ×1.80
|-
| 10 °C || ×1.35
|-
| 25 °C || ×1.00 (reference)
|-
| 40 °C || ×0.85
|}

At −20 °C the resistance is '''three times''' its room-temperature value. The
learned resistance is normalised to 25 °C and multiplied by k(T) in use.

=== 6.2 Cold-weather capacity compensation ===

In the cold, usable capacity shrinks — the energy is not gone, it just cannot be
drawn out. The firmware handles this by '''raising the display empty point''', so
the reading falls earlier and nobody is misled by "15 % left" outdoors at −10 °C:

{| class="wikitable"
! Temperature !! Empty point raised by
|-
| ≥ 15 °C || 0 (no compensation)
|-
| 0 °C || about +4 %
|-
| −10 °C || about +8 %
|-
| ≤ −20 °C || +12 % (capped)
|}

An NTC reading outside −30…70 °C is treated as a fault, and the last valid
temperature is held (initially 25 °C).

== 7. The display curve, and why it is "Tesla-style" ==

The internally computed SOC is not shown directly. One more mapping sits in
between:

* '''4 % → displays 1 %'''
* '''96 % → displays 100 %'''
* Linear in between (slope 99/92), clipped at both ends

The point is that '''when the display reads 0 %, roughly 4 % is still in the
pack''' (plus the hardware margin below the empty point), giving time to save work
and shut down cleanly. Likewise 96 % shows as 100 % so nobody agonises over the
last few percent — both are standard consumer-electronics practice.

The reported percentage is also '''clamped to a minimum of 1 %''': as long as the
device is running, it will not show 0 %.

== 8. After power-off: not losing the reading ==

This is where many fuel gauges fall down. Photonicat 2 has three paths.

=== 8.1 SOC snapshot ===

While running, SOC is written to flash whenever it drifts by ≥5 %; shutdown, host
power-down, standby entry and OTA reset all force a write and refresh the
timestamp.

On boot:

* '''≤12 hours''': SOC = snapshot − 2.0 mA × Δt (standby current), and OCV
re-estimation is '''blocked''' from overriding it. This is what fixed the old
"10 % becomes 1 % after a quick reboot" behaviour.
* '''>12 hours''': the snapshot is stale, so a cold-start OCV estimate is used.

=== 8.2 Deep-sleep discharge estimation ===

In deep sleep the TPA626 is powered down and no current can be measured. The
firmware records an RTC minute stamp on the way in and, on waking, subtracts the
whole-device standby draw of about '''2.0 mA'''.

=== 8.3 Detecting a battery swap ===

Remove the battery and the RTC loses power and resets, so its time runs backwards.
The firmware treats that as a battery swap, voids the snapshot and re-estimates
from cold. (A 10-minute tolerance is allowed; without it, a valid snapshot could
be discarded after an update reboot and the SOC would visibly step.)

== 9. How the data reaches Linux ==

Once the MCU has computed everything, it sends status frames to the host
(RK3576) over '''UART'''. Two consumers sit on the host side.

=== 9.1 Kernel driver: photonicat-pm ===

This is a '''serdev''' driver (<code>990-photonicat-pm-add-driver.patch</code>,
kernel 6.12) that attaches to the serial port, parses status frames, and
registers as standard Linux devices:

* '''power_supply''' class → <code>/sys/class/power_supply/battery</code>
* '''RTC''' class → <code>/dev/rtc</code>

Because these are '''standard subsystems''', any existing Linux tool works
directly — nothing needs to know the private protocol:

<syntaxhighlight lang="bash">
# Charge level (%) — the final output of everything described above
cat /sys/class/power_supply/battery/capacity

# Voltage µV / current µA / power µW
cat /sys/class/power_supply/battery/voltage_now
cat /sys/class/power_supply/battery/current_now
cat /sys/class/power_supply/battery/power_now

# Energy µWh: energy_full is the learned capacity — compare against
# energy_full_design to see ageing
cat /sys/class/power_supply/battery/energy_now
cat /sys/class/power_supply/battery/energy_full
cat /sys/class/power_supply/battery/energy_full_design

# Charger online
cat /sys/class/power_supply/charger/online
</syntaxhighlight>

'''The MCU is the hardware RTC.''' There is no separate RTC chip on the board —
the MCU is always powered, keeps time itself, and sends it up with the status
frames. The driver registers this through <code>rtc_class_ops</code>, so standard
tools just work:

<syntaxhighlight lang="bash">
hwclock -r # read the time from the MCU
hwclock -w # write system time back to the MCU
</syntaxhighlight>

This is why '''the clock is still right after days unplugged and offline''' — and
it is also the mechanism behind the battery-swap detection in 8.3, since a
battery removal resets the RTC and time runs backwards.

=== 9.2 Userspace daemon: pcat-manager ===

The kernel driver only consumes the power-related part of the status frame.
'''The rest of the UART protocol is handled by pcat-manager''': modem management,
watchdog, power on/off policy, button events, pushing the charge threshold down,
MCU firmware updates and so on.

The division of labour:

{| class="wikitable"
! Component !! Responsibility
|-
| MCU firmware || Measurement, integration, learning, compensation — all the algorithms
|-
| photonicat-pm (kernel) || Power/RTC data → standard sysfs interfaces
|-
| pcat-manager (userspace) || Everything else: modem, watchdog, power policy, OTA
|}

A concrete example is the '''charge limit'''. Set 80 % in the web UI and
pcat-manager sends it to the MCU over UART; the MCU stores it in data flash and
drives the charging MOSFET directly. From firmware '''RA2E1260726005''' the
setting persists on the MCU side and survives resets and OTA updates, while
pcat-manager also keeps its own mirror and re-sends it if it detects an MCU
restart — belt and braces.

== 10. FAQ ==

;Why does the reading occasionally jump?
:Usually OCV fusion or an anchor correcting integration drift. A single
correction is capped at 0.20 %, so you should not see large jumps in normal use;
a large one generally means a stale snapshot led to a cold-start re-estimate.

;Why does charge drop faster in winter?
:Two effects together: the pack genuinely has less usable capacity when cold, and
the firmware deliberately raises the display empty point (about +8 % at −10 °C)
so you learn early that it needs charging. It recovers as things warm up.

;Why does 96 % show as 100 %?
:The display curve is designed that way — see section 7. By the same token, there
is still margin left when it reads 0 %.

;Does a new battery need "calibration"?
:Not deliberately. One full discharge (from full down to automatic shutdown) lets
the firmware learn true capacity and the empty point; ordinary use gets there
gradually anyway.

;How often does health update?
:It needs a complete discharge window (full anchor → cutoff), and any charging
mid-window voids it. So it updates slowly and changes gradually by EMA — that is
intentional, so one bad measurement cannot make health plunge.

光影猫2 是如何计算电量的

C2h2 — Sun, 26 Jul 2026 09:21:06 GMT

Create: how the coulomb counter computes SOC (hardware, integration, OCV fusion, self-learning, temperature, Linux sysfs/RTC chain)

新页面

'''光影猫2''' 不靠"看电压猜电量"，而是用一套完整的'''库仑计'''（Coulomb
counter，又叫电量计 / fuel gauge）来算电量：像给电池装了一个水表，
进出的每一毫安秒都记账。

本页讲清楚这套系统怎么工作——从硬件怎么测，到固件怎么积分、怎么自学习、
怎么做温度补偿，再到 Linux 内核怎么把它变成 sysfs 文件。

指示灯说明见 [[Photonicat 2 LED 指示灯]]，sysfs 路径见 [[Photonicat 2 sysfs]]。
English: [[How Photonicat 2 Calculates SOC]]。

== 为什么不能只看电压 ==

这是所有电量计要解决的第一个问题。锂电池的"电压—电量"曲线中段非常平。
下面取固件里的'''放电 OCV 表'''（去 IR 后的整包电压）：

{| class="wikitable"
! 整包 OCV（开路电压） !! 对应电量
|-
| 7.58 V || 70 %
|-
| 7.50 V || 60 %
|-
| 7.44 V || 50 %
|-
| 7.36 V || 40 %
|-
| 7.28 V || 30 %
|}

从 70 % 掉到 30 %，电压只降了 '''0.30 V'''——平均每 1 % 电量只对应约
'''6 mV'''。而电池一带负载，内阻上的压降（I×R）轻松就有几十毫伏。也就是说：
'''只看电压，误差可以轻松超过 10 %'''，而且负载越大错得越离谱。

反过来，两端却很陡：这张表里 8.34 V 是 100 %、6.34 V 是 0 %。所以正确做法是
'''两端用电压定位，中间靠积分推进'''——这正是下面这套系统在做的事。

== 一句话原理 ==

电量 = 起点电量 − ∫(放电电流)dt + ∫(充电电流)dt

积分本身很准（电流测得准的话），但有两个毛病：'''起点从哪来'''，以及
'''误差会累积'''。所以真正的电量计 = 积分 + 一套修正机制。光影猫2 的做法是：

{| class="wikitable"
! 层 !! 作用
|-
| 硬件测量 || TPA626 每 100 ms 测一次电压/电流
|-
| 库仑积分 || 每 200 ms 把电流累加进 µAs 账本
|-
| OCV 融合 || 静置时用电压表反查电量，轻轻拉回积分漂移
|-
| 锚点 || 充满 / 欠压时直接把电量钉死到 100 % / 0 %
|-
| 自学习 || 满容量、内阻、空点、充电增益，每台机器各学各的
|-
| 温度补偿 || 冷天内阻变大、可用容量变少，都要修正
|-
| 显示层 || 把内部电量映射成用户看到的 1–100 %
|}

== 一、硬件：怎么测 ==

测量芯片是 '''TPA626'''（I²C 电流/电压监测器，与 INA226 同类）。它串一个
毫欧级采样电阻在电池回路上，测电阻两端压降换算电流，同时测总线电压。

* '''采样周期'''：约 100 ms 一次（<code>VD1_Collect</code>）
* '''中值滤波'''：电压和电流各过一个中值滤波器，滤掉 I²C 偶发抖动和负载尖峰
* '''原始值另存一份'''：中值滤波有约 3 s 滞后，会把"充电器插拔的电压台阶"
抹平，而内阻自学习恰恰要看这个瞬间台阶，所以固件同时保留未滤波的原始值

=== 电流校准 ===

采样电阻和运放都有个体误差，出厂靠精密万用表实测标定，拟合成二次多项式：

I_真实(mA) = C2·x² + C1·x + C0

当前系数（2026-07-24 二轮标定，四点残差 ≤3 mA）：

{| class="wikitable"
! 项 !! 值 !! 说明
|-
| C2 || −4.444×10⁻⁵ || 二次项，修大电流段的非线性
|-
| C1 || 1.0411 || 一次项（增益）
|-
| C0 || +20 mA（放电）/ 0 mA（充电） || 零点偏移，分方向
|}

几个工程细节值得一提：

* '''先夹再算'''：抛物线在标定范围外会"反向弯"（顶点约 +11.7 A），所以先把
输入夹到 ±3 A，域外按端点斜率线性延伸，不让二次项跑飞。
* '''int64 运算'''：x² 最大到 9×10⁶，乘上系数会溢出 int32。
* '''55 mA 死区'''：小于这个值直接当 0，避免待机时账本被噪声慢慢推歪。

== 二、库仑积分：账本 ==

每 '''200 ms''' 调一次 <code>coulomb_counter_update()</code>，把电流乘以时间
累加进一个 '''µAs（微安秒）'''的 64 位账本。用 µAs 而不是 mAh 是为了避免定点
除法的舍入误差在长时间运行后累积。

* 放电减、充电加
* 电流绝对值小于 '''30 mA''' 的部分不计入（死区，防噪声漂移）
* 充电方向另有一个自学习的'''增益系数'''（充电效率不是 100 %）

== 三、OCV 融合：把漂移拉回来 ==

积分误差会累积，所以在'''电池接近静置'''时，用电压反查电量表来轻轻纠正。

触发条件很严格，因为静置判断错了反而会把正确的积分带偏：

{| class="wikitable"
! 条件 !! 阈值 !! 为什么
|-
| 电流足够小 || \|I\| ≤ 340 mA（约 0.05C） || 电流大时内阻压降的模型误差会放大
|-
| 持续足够久 || ≥ 30 s || 让极化电压和表面电荷弛豫掉
|-
| 电压变化率 || ≤ 20 mV/s || 还在动态过程中就不算静置
|-
| 电流变化率 || ≤ 2000 mA/s || 同上
|-
| 插拔宽限期 || 10 s || 充电器刚插拔，电压还没稳
|}

满足后也不是直接覆盖，而是'''加权融合'''：

* 权重上限 '''α = 0.07'''（OCV 最多只占 7 %），且在 8 s 内从 0 线性爬升
* 单次修正最多 '''0.20 %'''

换句话说，OCV 是"温柔地把积分往回拽"，而不是"一把拽过去"——这样用户看到的
电量不会跳变。

=== 三张 OCV 表 ===

锂电池有'''滞回'''现象：同样的电量，充电时端电压偏高、放电时偏低（约
30 mV/芯，2S 约 ±60 mV）。所以固件带三张表：

* '''放电表'''：进入放电模式（\|I\| > 900 mA）时用
* '''充电表'''：进入充电模式时用
* '''静置表（REST）'''：充放两表的平均，小电流（\|I\| ≤ 600 mA）时用

模式切换带'''滞回'''（进 900 mA / 出 600 mA），避免在阈值附近反复横跳。

查表前还要先'''去 IR'''：OCV = 端电压 − I×R_pack，用的就是下面自学习到的内阻。

== 四、锚点：两端归位 ==

中段靠积分，两端靠锚点直接钉死：

* '''满电锚点'''：充电器在位、且 vbus ≥ 8 V、且电流已经很小 → 电量 = 100 %。
要求充电器在位是有原因的：'''95 % 的静置 OCV 约 8.16 V'''，一块高电量的
电池静置着很容易被误判成满电。劣质或欠压的充电器推不到真满，也不给锚。
* '''欠压锚点'''：放到欠压关机点 → 电量 = 0 %，同时触发空点学习。

== 五、自学习：每台机器都不一样 ==

这是这套系统最有意思的部分。同一批电池、同一批板子，个体差异也能有
10 % 以上。所以固件会'''为每台机器单独学习'''四个量，学到的值存进 data flash，
掉电不丢。

=== 5.1 满容量学习（电池老化） ===

标称 6800 mAh 的电池，用两年可能只剩 5500 mAh。如果满容量写死，老化后
SOC 就会偏乐观——显示还有电，实际已经关机了。

学习方法：

# 满电锚点触发时开窗口，累计放电清零
# 一路放电到欠压关机点
# 满容量 = 累计放出的电量 + '''700 mAh'''
# 中途检测到充电 → 本次窗口作废

那个 '''700 mAh''' 是关键：整机不会把电池放到真正的 0 V，在关机点
（约 6.3–6.45 V）时电池包里还剩约 700 mAh 没放出来，必须补回去。

学到的值还会换算成'''健康度'''：

健康度 = 学习容量 / 6800 mAh

健康度采用 EMA 缓慢融入（Apple 式缓变），不会因为一次测量就跳水。

=== 5.2 内阻学习（电压台阶法） ===

去 IR 计算需要知道内阻。固件用一个很巧的办法：'''充电器插拔的瞬间'''，
电流突变 ΔI，电压随之突变 ΔV，那么

R = ΔV / ΔI

条件：电压 > 7.8 V（近满电区，否则 OCV 本身会随电量移动而测不准）、
电流台阶 ≥ 300 mA、电压台阶 ≥ 15 mV。测量结果按 3/10 的权重 EMA 融入，
范围限制在 10–200 mΩ，默认值 50 mΩ。

注意这测到的是'''整包回路电阻''' = 电芯本体 + 线缆/接插件（20 mΩ）+
保护板 MOSFET（15 mΩ）。去 IR 需要的正是这个整包串联值，不做扣减；
上位机若要显示"电芯本体内阻"，才减掉那 35 mΩ 的板级寄生。

=== 5.3 显示空点学习 ===

实测踩过的坑：'''显示还有 20 % 时整机突然断电'''。原因是每台机器的电流计
增益和实际容量都有偏差，内部 SOC 到 0 的那一刻和硬件真正撑不住的那一刻对不齐。

解法不是去改电流链路（那会引入新的误差），而是在'''显示层'''加一个
每台机器自学习的线性映射：

显示值 = (内部SOC − 空点) × 100 / (100 − 空点)

'''空点'''（empty）= 上一次"电池真的没电了"时的内部 SOC。学习事件包括：
低压关机命令、低压下主机意外死机、欠压锚点。

还有'''向下自纠'''：如果放电时电压还很健康（> 6.8 V）但内部 SOC 已经低于
空点，说明空点学高了，就让空点跟着降。这样换了新电池或学过头，都能在一个
放电周期内自愈。

=== 5.4 充电增益学习 ===

充电效率不是 100 %，充进去的电荷和实际存住的电荷有差异。这个增益在满电
锚点时学习，变化 ≥1 % 才落盘。

== 六、温度补偿 ==

锂电池怕冷。板载 NTC 每 200 ms 把温度喂给库仑计，做两件事：

=== 6.1 内阻温度倍率 k(T) ===

内阻随温度显著变化，直接影响去 IR 的准确性：

{| class="wikitable"
! 温度 !! 内阻倍率 k(T)
|-
| −20 °C || ×3.00
|-
| −10 °C || ×2.30
|-
| 0 °C || ×1.80
|-
| 10 °C || ×1.35
|-
| 25 °C || ×1.00（基准）
|-
| 40 °C || ×0.85
|}

也就是说 −20 °C 时内阻是常温的'''三倍'''。学习到的内阻归一在 25 °C 域，
用的时候再乘 k(T)。

=== 6.2 低温可用容量补偿 ===

冷天电池的可用容量会缩水——不是电"没了"，而是低温下拿不出来。固件的处理是
'''把显示空点上移'''，让显示电量提前走低，用户就不会在 −10 °C 的户外被
"还有 15 %"骗了：

{| class="wikitable"
! 温度 !! 空点上移
|-
| ≥ 15 °C || 0（不补偿）
|-
| 0 °C || 约 +4 %
|-
| −10 °C || 约 +8 %
|-
| ≤ −20 °C || +12 %（封顶）
|}

NTC 读数超出 −30…70 °C 视为故障，保持上一次有效温度（初值 25 °C）。

== 七、显示曲线：为什么是"特斯拉式" ==

内部算出来的 SOC 不会直接给用户看，中间还有一层映射：

* '''4 % → 显示 1 %'''
* '''96 % → 显示 100 %'''
* 中段线性（斜率 99/92），两端截断

这样做的意思是：'''显示到 0 % 时，电池里其实还留着约 4 % 的余量'''
（再加上空点以下的硬件余量），用户有时间保存工作、正常关机。同理，充到
96 % 就显示 100 %，避免用户盯着最后几个百分点焦虑——这些都是消费电子的
常规做法。

另外固件上报的百分比'''下限钳在 1 %'''：只要还没关机，就不显示 0 %。

== 八、关机之后：电量怎么不丢 ==

这是很多电量计做不好的地方。光影猫2 有三条路径：

=== 8.1 SOC 快照 ===

运行时 SOC 每漂移 ≥5 % 就自动落盘；关机、主机断电、进待机、OTA 复位前
强制落盘并刷新时间戳。

开机恢复策略：

* '''≤12 小时'''：SOC = 快照 − 2.0 mA × Δt（按待机电流扣减），并'''禁止'''
OCV 重估覆盖。这条修的是"短时重启后 10 % 变 1 %"的老问题。
* '''>12 小时'''：快照过期，走冷启动 OCV 重估。

=== 8.2 深睡放电估计 ===

电池深睡时 TPA626 会掉电，采不到电流。固件在进睡前记下 RTC 分钟戳，
醒来后按整机待机约 '''2.0 mA''' 恒流扣减。

=== 8.3 换电池识别 ===

电池拔掉 → RTC 掉电重置 → 时间倒退。固件据此判定"换过电池"，让快照作废，
重新冷启动估计。（这里留了 10 分钟容差，否则升级重启后一条有效快照会被误判
丢掉，SOC 就会出现台阶跳变。）

== 九、数据怎么到 Linux ==

MCU 算完，通过 '''UART''' 把状态帧发给主机（RK3576）。主机侧有两个消费者：

=== 9.1 内核驱动：photonicat-pm ===

这是一个 '''serdev''' 驱动（<code>990-photonicat-pm-add-driver.patch</code>，
内核 6.12），直接挂在串口上解析状态帧，然后注册成标准 Linux 设备：

* '''power_supply''' 类 → <code>/sys/class/power_supply/battery</code>
* '''RTC''' 类 → <code>/dev/rtc</code>

因为注册的是'''标准子系统'''，所以任何现成的 Linux 工具都能直接用，
不需要认识光影猫的私有协议：

<syntaxhighlight lang="bash">
# 电量（%），这就是上面整套算法的最终输出
cat /sys/class/power_supply/battery/capacity

# 电压 µV / 电流 µA / 功率 µW
cat /sys/class/power_supply/battery/voltage_now
cat /sys/class/power_supply/battery/current_now
cat /sys/class/power_supply/battery/power_now

# 能量 µWh：energy_full 是学习到的满容量，对比 energy_full_design 看老化
cat /sys/class/power_supply/battery/energy_now
cat /sys/class/power_supply/battery/energy_full
cat /sys/class/power_supply/battery/energy_full_design

# 充电器在线
cat /sys/class/power_supply/charger/online
</syntaxhighlight>

'''MCU 就是硬件 RTC。'''板子上没有单独的 RTC 芯片——MCU 一直有电，它自己
就在走时，时间随状态帧一起送上来。驱动把它注册成 <code>rtc_class_ops</code>，
于是标准工具直接可用：

<syntaxhighlight lang="bash">
hwclock -r # 读 MCU 里的时间
hwclock -w # 把系统时间写回 MCU
</syntaxhighlight>

这也是为什么'''断网断电放几天，开机时间还是准的'''。前面 8.3 讲的
"换电池识别"也是靠它——RTC 掉电重置，时间就会倒退。

=== 9.2 用户态守护进程：pcat-manager ===

内核驱动只认状态帧里的电源部分。'''其余的 UART 协议由 pcat-manager 处理'''：
调制解调器管理、看门狗、开关机策略、按键事件、充电阈值下发、MCU 固件升级等。

分工可以这么理解：

{| class="wikitable"
! 组件 !! 负责
|-
| MCU 固件 || 测量、积分、学习、补偿——所有算法
|-
| photonicat-pm（内核） || 电源/RTC 数据 → 标准 sysfs 接口
|-
| pcat-manager（用户态） || 其余协议：调制解调器、看门狗、电源策略、OTA
|}

一个具体例子是'''充电上限'''：你在网页里设 80 %，pcat-manager 通过 UART 下发给
MCU，MCU 把它存进 data flash 并直接控制充电 MOSFET。固件
'''RA2E1260726005''' 起这个设置在 MCU 侧持久化，MCU 复位或 OTA 之后不会丢；
同时 pcat-manager 也保留一份镜像并在检测到 MCU 重启时重新下发，双保险。

== 十、常见问题 ==

;为什么电量偶尔会"跳一下"？
:多半是 OCV 融合或锚点在纠正积分漂移。单次修正被限制在 0.20 %，所以正常情况
你不会看到大跳变；如果出现大跳变，通常是快照过期后走了冷启动重估。

;为什么冬天电量掉得快？
:两个原因叠加：低温下电池可用容量本来就少，加上固件主动把显示空点上移
（−10 °C 约 +8 %），让你提前知道该充电了。回暖后会恢复。

;为什么充到 96 % 就显示 100 %？
:显示曲线刻意这么设计的，见第七节。同理显示 0 % 时电池还有余量。

;新电池要不要"校准"？
:不用刻意做。完整放一次电（从满电放到自动关机）会让固件学到真实满容量和
空点；平时正常使用也会慢慢学到。

;健康度多久更新一次？
:需要一次完整的放电窗口（满电锚点 → 欠压），中途充电会作废。所以它更新得慢，
而且是 EMA 缓变的，这是刻意的——避免单次误测就让健康度跳水。

Photonicat 2 LED Indicator

C2h2 — Sun, 26 Jul 2026 03:50:15 GMT

Low-battery red now flashes continuously (firmware RA2E1260726003+) instead of stopping after 3 flashes

←上一版本		2026年7月26日 (日) 11:50的版本
第27行：		第27行：
	\| [[File:Pcat2-led-green-heartbeat-v2.gif\|52px\|link=]] \|\| 🟢 Green, heartbeat pulse \|\| Running on battery, charge level normal		\| [[File:Pcat2-led-green-heartbeat-v2.gif\|52px\|link=]] \|\| 🟢 Green, heartbeat pulse \|\| Running on battery, charge level normal
	\|-		\|-
	\| [[File:Pcat2-led-red-lowbatt-v2.gif\|52px\|link=]] \|\| 🔴 Red, ~~3 flashes~~ \|\| Low battery (below 6500 mV~~, 3 flashes only~~ — see [[#Low battery red light\|Low battery red light]])		\| [[File:Pcat2-led-red-lowbatt-v2.gif\|52px\|link=]] \|\| 🔴 Red, flashing \|\| Low battery (below 6500 mV — see [[#Low battery red light\|Low battery red light]])
	\|-		\|-
	\| [[File:Pcat2-led-off-v2.gif\|52px\|link=]] \|\| ⚫ Off \|\| Idle on battery, system off		\| [[File:Pcat2-led-off-v2.gif\|52px\|link=]] \|\| ⚫ Off \|\| Idle on battery, system off
第55行：		第55行：
	\| Above 6600 mV, system off \|\| None \|\| [[File:Pcat2-led-green-solid-v2.gif\|44px\|link=]] \|\| 🟢 Green \|\| Steady \|\| Constant		\| Above 6600 mV, system off \|\| None \|\| [[File:Pcat2-led-green-solid-v2.gif\|44px\|link=]] \|\| 🟢 Green \|\| Steady \|\| Constant
	\|-		\|-
	\| Below 6500 mV, system on \|\| None \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 Red \|\| ~~Flicker~~ \|\| 1 s on / 1 s off~~, 3 flashes~~, begins after 60 s		\| Below 6500 mV, system on \|\| None \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 Red \|\| Continuous flashing \|\| 1 s on / 1 s off, begins after 60 s, until the voltage recovers
	\|-		\|-
	\| Below 6500 mV, short press \|\| None \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 Red \|\| Flicker \|\| 1 s on / 1 s off, ~~3 flashes~~		\| Below 6500 mV, short press \|\| None \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 Red \|\| Flicker \|\| 1 s on / 1 s off, while held or until the voltage recovers
	\|-		\|-
	\| Charger removed, system off \|\| None \|\| [[File:Pcat2-led-off-v2.gif\|44px\|link=]] \|\| colspan="2" \| ⚫ Off		\| Charger removed, system off \|\| None \|\| [[File:Pcat2-led-off-v2.gif\|44px\|link=]] \|\| colspan="2" \| ⚫ Off
第87行：		第87行：
	\| Rhythm \|\| 1 second on / 1 second off		\| Rhythm \|\| 1 second on / 1 second off
	\|-		\|-
	\| Repeats \|\| '''~~Stops after 3 flashes~~''' ~~— it does not keep flashing~~		\| Repeats \|\| '''Flashes continuously''' until the voltage recovers or a charger is connected
	\|-		\|-
	\| While running \|\| Starts only after the voltage has stayed below the threshold for '''60 seconds'''		\| While running \|\| Starts only after the voltage has stayed below the threshold for '''60 seconds'''
	\|-		\|-
	\| Short press \|\| With a low battery, a short press of the power button ~~shows it~~ immediately (~~3 flashes~~ after a 0.5 s debounce)		\| Short press \|\| With a low battery, a short press of the power button triggers the red flashing immediately (after a 0.5 s debounce)
	\|-		\|-
	\| Effect on green \|\| The green heartbeat stops while red is active; the two never show together		\| Effect on green \|\| The green heartbeat stops while red is active; the two never show together
第98行：		第98行：
	'''⚠️ Important'''		'''⚠️ Important'''

	* The red warning '''~~stops after 3 flashes~~'''. ~~If you miss it, there is no further light warning~~ before ~~the device shuts down.~~		* The red warning '''keeps flashing until the voltage recovers or a charger is connected'''; it does not stop on its own. (Firmware before RA2E1260726003 flashed only 3 times and then went quiet.)
	* To check the level again, '''press the power button once''' to re-trigger the warning.
	* The red threshold (6500 mV) is only '''200 mV above the hard shutdown point (6300 mV)'''. That is a very steep part of the 2S li-ion discharge curve, so connect a charger promptly once you see red.		* The red threshold (6500 mV) is only '''200 mV above the hard shutdown point (6300 mV)'''. That is a very steep part of the 2S li-ion discharge curve, so connect a charger promptly once you see red.
	* The trigger is '''voltage, not a percentage'''. Under heavy load the voltage sags and the warning can appear while a useful charge remains; when the load drops the voltage recovers and the warning stops.		* The trigger is '''voltage, not a percentage'''. Under heavy load the voltage sags and the warning can appear while a useful charge remains; when the load drops the voltage recovers and the warning stops.
第110行：		第109行：

	* Breathing runs at a lower peak brightness (25 % duty) than steady (50 %), so a breathing indicator looks dimmer than a steady one of the same colour.		* Breathing runs at a lower peak brightness (25 % duty) than steady (50 %), so a breathing indicator looks dimmer than a steady one of the same colour.
	* 🔴 Red is only ever used for low battery, and ~~stops after three flashes rather than~~ flashing ~~continuously~~.		* 🔴 Red is only ever used for low battery, and keeps flashing until the voltage recovers or a charger is connected.
	* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.		* The indicator can be disabled entirely through the host protocol, in which case it stays off in all states.

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 03:50:14 GMT

低电红灯改为持续闪烁（固件 RA2E1260726003 起），不再闪 3 次即停

←上一版本		2026年7月26日 (日) 11:50的版本
第27行：		第27行：
	\| [[File:Pcat2-led-green-heartbeat-v2.gif\|52px\|link=]] \|\| 🟢 绿色心跳脉冲 \|\| 电池供电运行中，电量正常		\| [[File:Pcat2-led-green-heartbeat-v2.gif\|52px\|link=]] \|\| 🟢 绿色心跳脉冲 \|\| 电池供电运行中，电量正常
	\|-		\|-
	\| [[File:Pcat2-led-red-lowbatt-v2.gif\|52px\|link=]] \|\| 🔴 ~~红色闪 3 次~~ \|\| 电量低（低于 6500 ~~mV，仅闪 3 次，详见下方~~[[#低电量红灯\|低电量红灯]]）		\| [[File:Pcat2-led-red-lowbatt-v2.gif\|52px\|link=]] \|\| 🔴 红色持续闪烁 \|\| 电量低（低于 6500 mV，详见下方[[#低电量红灯\|低电量红灯]]）
	\|-		\|-
	\| [[File:Pcat2-led-off-v2.gif\|52px\|link=]] \|\| ⚫ 熄灭 \|\| 电池供电待机，系统已关机		\| [[File:Pcat2-led-off-v2.gif\|52px\|link=]] \|\| ⚫ 熄灭 \|\| 电池供电待机，系统已关机
第55行：		第55行：
	\| 高于 6600 mV，关机 \|\| 未插入 \|\| [[File:Pcat2-led-green-solid-v2.gif\|44px\|link=]] \|\| 🟢 绿色 \|\| 常亮 \|\| 持续		\| 高于 6600 mV，关机 \|\| 未插入 \|\| [[File:Pcat2-led-green-solid-v2.gif\|44px\|link=]] \|\| 🟢 绿色 \|\| 常亮 \|\| 持续
	\|-		\|-
	\| 低于 6500 mV，开机 \|\| 未插入 \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 红色 \|\| 闪烁 \|\| 亮 1 s / 灭 1 ~~s，共 3 次，60~~ s ~~后开始~~		\| 低于 6500 mV，开机 \|\| 未插入 \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 红色 \|\| 持续闪烁 \|\| 亮 1 s / 灭 1 s，60 s 后开始，持续到电压回升
	\|-		\|-
	\| 低于 6500 mV，短按一次 \|\| 未插入 \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 红色 \|\| 闪烁 \|\| 亮 1 s / 灭 1 ~~s，共 3 次~~		\| 低于 6500 mV，短按一次 \|\| 未插入 \|\| [[File:Pcat2-led-red-lowbatt-v2.gif\|44px\|link=]] \|\| 🔴 红色 \|\| 闪烁 \|\| 亮 1 s / 灭 1 s，持续到松开或电压回升
	\|-		\|-
	\| 拔出充电器且关机 \|\| 未插入 \|\| [[File:Pcat2-led-off-v2.gif\|44px\|link=]] \|\| colspan="2" \| ⚫ 熄灭		\| 拔出充电器且关机 \|\| 未插入 \|\| [[File:Pcat2-led-off-v2.gif\|44px\|link=]] \|\| colspan="2" \| ⚫ 熄灭
第87行：		第87行：
	\| 闪烁节奏 \|\| 亮 1 秒 / 灭 1 秒		\| 闪烁节奏 \|\| 亮 1 秒 / 灭 1 秒
	\|-		\|-
	\| 闪烁次数 \|\| '''~~仅 3 次即停止~~'''~~，不会持续闪烁~~		\| 闪烁次数 \|\| '''持续闪烁'''，直到电压回升或插上充电器
	\|-		\|-
	\| 开机状态下 \|\| 电压持续低于门限 '''60 秒'''后才开始闪		\| 开机状态下 \|\| 电压持续低于门限 '''60 秒'''后才开始闪
	\|-		\|-
	\| 短按电源键 \|\| ~~电压低时短按一下可立即查看（约~~ 0.5 ~~秒防抖后闪 3 次）~~		\| 短按电源键 \|\| 电压低时短按一下可立即触发红闪（约 0.5 秒防抖）
	\|-		\|-
	\| 绿灯会怎样 \|\| 红灯期间绿色心跳会停止，两者不会同时亮		\| 绿灯会怎样 \|\| 红灯期间绿色心跳会停止，两者不会同时亮
第98行：		第98行：
	'''⚠️ 重要提醒'''		'''⚠️ 重要提醒'''

	* 红灯'''~~闪 3 次后就不再提示~~'''~~。错过之后在关机前不会再有任何灯光警告。~~		* 红灯会'''一直闪到电压回升或接入充电器'''，不会自行停止。（RA2E1260726003 之前的固件只闪 3 次就不再提示。）
	* 若要确认当前电量，可'''短按一次电源键'''重新触发提示。
	* 红灯触发点（6500 mV）与'''强制关机点（6300 mV）只差 200 mV'''，在 2S 锂电的放电末端属于很陡的一段，看到红灯应尽快接入充电器。		* 红灯触发点（6500 mV）与'''强制关机点（6300 mV）只差 200 mV'''，在 2S 锂电的放电末端属于很陡的一段，看到红灯应尽快接入充电器。
	* 判据是'''电压不是百分比'''：大负载下电压会被拉低，可能在剩余电量还不算太少时就提前告警；负载减轻后电压回升，告警也会随之消失。		* 判据是'''电压不是百分比'''：大负载下电压会被拉低，可能在剩余电量还不算太少时就提前告警；负载减轻后电压回升，告警也会随之消失。
第110行：		第109行：

	* 呼吸的峰值亮度（25 % 占空）低于常亮（50 %），因此同色下呼吸看起来更暗。		* 呼吸的峰值亮度（25 % 占空）低于常亮（50 %），因此同色下呼吸看起来更暗。
	* 🔴 ~~红色仅用于低电量提示，闪 3 次后停止，不会持续闪烁。~~		* 🔴 红色仅用于低电量提示，会持续闪烁直到电压回升或接入充电器。
	* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。		* 指示灯可通过上位机协议整体关闭，关闭后所有状态均不亮灯。

	[[Category:Photonicat 2]]		[[Category:Photonicat 2]]

Photonicat 2 LED Indicator

C2h2 — Sun, 26 Jul 2026 03:46:11 GMT

Add 'Low battery red light' section: 6500 mV trigger, 60 s delay, stops after 3 flashes, and only 200 mV above the 6300 mV shutdown point

@@ 第27行： / 第27行： @@
 | [[File:Pcat2-led-green-heartbeat-v2.gif|52px|link=]] || 🟢 Green, heartbeat pulse || Running on battery, charge level normal
 |-
-| [[File:Pcat2-led-red-lowbatt-v2.gif|52px|link=]] || 🔴 Red, 3 flashes || Low battery
+| [[File:Pcat2-led-red-lowbatt-v2.gif|52px|link=]] || 🔴 Red, 3 flashes || Low battery (below 6500 mV, 3 flashes only — see [[#Low battery red light|Low battery red light]])
 |-
 | [[File:Pcat2-led-off-v2.gif|52px|link=]] || ⚫ Off || Idle on battery, system off
@@ 第75行： / 第75行： @@
 | Reset / factory restore mode || [[File:Pcat2-led-orange-blink-slow-v2.gif|44px|link=]] || 🟠 Yellow || Slow blink || ≈1 s period
 |}
 ==Charge limit==

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 03:45:53 GMT

新增「低电量红灯」章节：明确 6500 mV 触发点、60 秒延迟、仅闪 3 次即停止，以及与 6300 mV 关机点仅差 200 mV 的提醒

@@ 第27行： / 第27行： @@
 | [[File:Pcat2-led-green-heartbeat-v2.gif|52px|link=]] || 🟢 绿色心跳脉冲 || 电池供电运行中，电量正常
 |-
-| [[File:Pcat2-led-red-lowbatt-v2.gif|52px|link=]] || 🔴 红色闪 3 次 || 电量低
+| [[File:Pcat2-led-red-lowbatt-v2.gif|52px|link=]] || 🔴 红色闪 3 次 || 电量低（低于 6500 mV，仅闪 3 次，详见下方[[#低电量红灯|低电量红灯]]）
 |-
 | [[File:Pcat2-led-off-v2.gif|52px|link=]] || ⚫ 熄灭 || 电池供电待机，系统已关机
@@ 第75行： / 第75行： @@
 | 复位 / 恢复出厂模式 || [[File:Pcat2-led-orange-blink-slow-v2.gif|44px|link=]] || 🟠 黄色 || 慢闪 || 周期约 1 s
 |}
 ==充电上限==

Photonicat 2 LED Indicator

C2h2 — Sun, 26 Jul 2026 03:41:39 GMT

改用 -v2 文件名，绕过浏览器缓存中旧的深色背景动画

Photonicat 2 LED 指示灯

C2h2 — Sun, 26 Jul 2026 03:41:07 GMT

改用 -v2 文件名，绕过浏览器缓存中旧的深色背景动画

文件:Pcat2-led-red-lowbatt-v2.gif

C2h2 — Sun, 26 Jul 2026 03:40:56 GMT

C2h2上传文件:Pcat2-led-red-lowbatt-v2.gif Photonicat 2 LED animation, white background. New filename to bypass browser/CDN caching of the previous dark-background version.

新页面