# DRV8316R 配置驱动 A0

原理图对应 `硬件/drill_motor/`。此目录包括芯片通信、静止初始化、故障处理、外环转速监督器和 FOC 电流环数学候选；仍不含转子观测器、启动策略、UI、目标 TIM1/ADC HAL 或可运行的电机控制 MCU 工程。

`drv8316_configure_off()` 全程保持 DRVOFF，进入睡眠复位后唤醒，读取故障，解锁、配置、逐次回读并锁定。成功只表示配置核对通过，没有自动启动电机。任何 SPI 错误、故障状态或回读不一致均保持关闭并进入睡眠。

SPI HAL 要求 16 位、MSB 优先、Mode 1，首版 500kHz；CS 高间隔至少 1us。SDO 使用开漏，与原理图中的上拉匹配。同步串行调用，不可在多个任务或中断中并发调用。驱动芯片睡眠后配置失效，恢复必须重走初始化。

配置采用六路 PWM、6x PWM 逐周期限流（ILIM 外部电阻约设 2A）、0.3V/A 采样增益、锁存过流、报告温度预警、关闭未使用降压和延迟补偿。内部过流门限不是手柄或电池允许电流，必须另有系统限流。不得跳过控制器的独立关断、母线和温度检查来接电机运行。

## 本机测试

2026-09-27，Apple Clang，C11，`-Wall -Wextra -Werror -pedantic -fsanitize=address,undefined` 编译运行通过。测试覆盖：

- 32,768 个读写/地址/数据组合的帧编码及偶校验，并核对手工给出的帧常量。
- 对初始化 22 次通信中的每一次分别注入传输失败和状态故障。
- 8 处配置回读不一致、3 个故障寄存器、无效 HAL，以及正常配置和故障轮询。
- 模拟器返回写入前的旧值，确保代码另发读取来验证写入。
- 初始化所有测试路径均未调用电机使能。

这是主机模拟测试；没有验证真实 SPI 时序、器件启动、模拟采样、功率输出或电机运行。

从本目录可执行：

```sh
clang -std=c11 -Wall -Wextra -Werror -pedantic -fsanitize=address,undefined drv8316.c test_drv8316.c -o /tmp/test_drv8316
/tmp/test_drv8316
```

寄存器依据：[TI DRV8316 Rev B，第 8.5–8.6 节](https://www.ti.com/lit/ds/symlink/drv8316.pdf)。

## 闭环转速监督器候选（2026-10-08）

`speed_supervisor.*` 是 C11 主机可测的外环候选：输入经 FOC/传感器确认的有符号转速，输出限幅的 q 轴电流请求；不生成 PWM，也不实现 FOC、启动对齐或转子观测。它把目标上限限制到链接声明的 50,000 rpm，检测转速反馈过期、超过上限、主驱动故障及服务循环超时；方向反转时先零电流滑行，只有检测到零速窗口持续满足校准时长后才切换方向。若系统没有验证过回馈能量吸收，`regen_permitted=false` 会禁止产生与当前转速相反的转矩请求。

`current_limit_ma`、PI 增益、加减速斜率、零速阈值/驻留时间及反馈来源都是待测整定值。它们不能由 2 A 候选 ILIM 或主机模拟测试证明。目标 MCU、FOC 内环、启动策略、ADC/TIM1 同步、运行温度、机械负载和与原机的转速/扭矩对比均未完成；目标硬件未通过之前禁止用此策略声称达到 50,000 rpm 稳速效果。

## 新手模式与磁吸停放自动停机（2026-10-08）

`speed_supervisor.*` 增加了两个可集成的运行行为：新手模式把目标转速和回读/显示上限约束在 30,000 rpm；该数值来自 ONAIL 公开零售商资料，Amazon 子商品只确认存在 Beginner Mode，没有给出数值，因此保留为可审查的候选上限。模式只能在停机状态切换，运行中拒绝切换。手柄放入磁吸座时，归一化后的 `handpiece_parked` 输入使监督器撤销运行许可并清零 q 轴电流请求；取下后不会自动重启，必须重新发起启动。传感器无效时锁存联锁故障。

主控原理图已有 `HANDPIECE_MAGNET_PARK` 至 J5.5 的电气网络。真实传感器极性、磁场阈值、去抖、断线诊断和 HAL 采样仍须在目标板/手柄确认；目前只是策略接口，不证明电机实际停转时间或传感器硬件已经装配。相关 host test 覆盖 30,000 rpm 限制、满速模式恢复、停放立即撤销命令、取下不自动重启和传感器失效锁定。

商品页依据：Amazon 商品页确认 50,000 rpm、3.0 mm 批头、正反转、Beginner Mode 和 Automatic Stop 标签；[O NAIL 官方规格页](https://onail.com/products/smart-nail-drill)给出 5–9 V/2 A USB-C 输入、Li-Po 2,150 mAh/23.865 Wh、11.1 V 标称和 12.6 V 充电上限；[零售商模式说明](https://www.nc-beautypro.fr/en/639-onail)将 Beginner Mode 描述为 30,000 rpm 上限。Amazon listing 和官方规格页未披露手柄电机拓扑、额定负载、BMS/NTC 和磁吸传感器电气细节。

增量决策与续航能量核算见 `../../60-打磨机磁吸停机新手模式与官方规格更新-2026-10-08.md`。

## FOC 电流环数学候选

`motor_foc.*` 提供 Clarke/Park、d/q 电流 PI、逆 Park 和中心对齐 SVPWM；实现边界、2 A 候选限值、失效行为和实际未完成项见 `../../65-打磨机FOC电流环算法候选与验证-2026-10-08.md`。它不含电角度观测器、转子启动、TIM1/ADC 配置或 DRV8316 使能；未经实际手柄和功率级校准，不能据此声称达到商品页 50,000 rpm。
