先说一个 bring-up 花絮:原理图/BOM 上曾把它标成 RX8025T。两者都是爱普生的 I2C RTC,名字像双胞胎,寄存器布局却完全不同(RX8010 的时间寄存器从 0x10 开始,RX8025T 从 0x00 开始)。驱动落地前一定要按实际芯片的手册来——最终 确认板上丝印对应的是 RX8010SJ。

挂在别人的总线上

RX8010SJ 和加速度计 SC7A20 共享同一条 I2C 总线。ESP-IDF 新版 i2c_master 驱动的模型是「总线」和「设备」两级:总线创建一次,设备各自往上挂。项目里 让 SC7A20 的驱动负责创建总线,RTC 驱动通过一个访问器拿现成的总线句柄:

esp_err_t rx8010_init(void)
{
    if (s_ok) return ESP_OK;
    // 总线由 sc7a20_init() 创建,必须先跑
    i2c_master_bus_handle_t bus = sc7a20_get_i2c_bus();
    if (bus == NULL) return ESP_ERR_INVALID_STATE;

    i2c_device_config_t cfg = {
        .dev_addr_length = I2C_ADDR_BIT_LEN_7,
        .device_address = 0x32,
        .scl_speed_hz = 100000,
    };
    // 挂设备 → 读一次 CTRL 确认应答 → 清 FLAG
}

「RTC 组件依赖加速度计组件」看着有点怪,但在这块板上总线的上拉配置、 深睡眠 hold 都是加速度计 bring-up 时一并处理的,让总线只有一个创建者, 比两个组件各自抢着建总线干净。代价是初始化顺序有了隐式约定: sc7a20_init() 必须先于 rx8010_init()。

时间寄存器:BCD 码

时间落在 7 个连续寄存器里,数值全是 BCD 码(每半个字节一位十进制数):

转换只需要两个宏:

#define BCD_TO_DEC(x)  (((x) >> 4) * 10 + ((x) & 0x0F))
#define DEC_TO_BCD(x)  ((((x) / 10) << 4) | ((x) % 10))

读取时还要按位掩码剥离标志位:秒寄存器的 bit7 是 VL 位(下文主角), 小时的 bit7 是 12/24 制标记。掩码忘了剥,时间就会偶尔「跳」出一个怪值。

读时间:burst 读消除撕裂

第一直觉是逐个寄存器读 7 次。但这有时间撕裂问题:读秒和读分之间如果 恰好发生进位(59 秒跳下一分),拼出来的就是一个从未存在过的时间。 解法是把 7 个字节压缩进一条 I2C 事务连续读出,进位无法再插进读取 过程的中间:

uint8_t reg = REG_SEC, buf[7];
i2c_master_transmit_receive(s_dev, &reg, 1, buf, 7, 100);   // 一次读 0x10-0x16
time->vl     = (buf[0] >> 7) & 1;
time->second = BCD_TO_DEC(buf[0] & 0x7F);
// ...

写时间同理用 burst 写,并且前后要包一层 RESET 保护(下一节)。

写时间:RESET 位 + burst 写

更新时间不能对着正在走数的寄存器直接写。RX8010 的流程是:

wr(REG_CTRL, 0x40);          // 1. CTRL 的 RESET 位置 1,暂停走时
// 2. 一条事务 burst 写 7 个时间寄存器,VL 位顺手写 0(清除)
uint8_t buf[8] = { REG_SEC, bcd_sec, bcd_min, bcd_hour,
                   weekday & 0x07, bcd_day, bcd_mon, bcd_year };
i2c_master_transmit(s_dev, buf, 8, 100);
wr(REG_CTRL, 0x00);          // 3. RESET 清零,时钟恢复走动

set_time 入口还做了参数范围校验(秒 0–59、月 1–12……),非法值直接 拒绝——BCD 码写进一个 70 的「分钟」,芯片不会替你报错。

VL 位:时间可不可信,芯片自己知道

RX8010 的妙处是 VL(Voltage Low)标志:一旦芯片电源跌破维持走时的下限, 它把秒寄存器 bit7 置 1,并一直保留到软件主动写时间清除。也就是说, 时间是否经历过掉电,芯片比你清楚:

bool rx8010_is_valid(void)
{
    rx8010_time_t t;
    if (rx8010_get_time(&t) != ESP_OK) return false;
    return !t.vl;   // VL=0 才可信
}

主流程每次唤醒都检查一遍:

if (!rx8010_is_valid()) {
    ESP_LOGW(TAG, "RTC time invalid (VL set) — battery may have been disconnected");
}

没有 VL 位之前,「设备换过电池、时间回到了默认值」这种事只能靠猜 (比如判断年份是不是 2000);有了它,一句话就能把不可信时间拦在门外。 开机自检(selftest)也把 rx8010_init → get_time → is_valid 串成一项 检查,连时间值一起打到串口日志里,pytest 直接拿这些行做断言。

初始化顺手做的两件事

• 读一次 CTRL 寄存器当「在不在」探测——总线通、芯片应答才算初始化成功;
• 清 FLAG 寄存器(AF/TF/UF,报警/定时器/更新标志),保证从干净状态开始。

小结

外部 RTC 驱动的代码量很小(200 行以内),真正花心思的是三件事:按实际 芯片手册核对寄存器表(别信 BOM 上的名字)、burst 读写保证一致性、用 VL 位回答「这时间敢不敢用」。对一个每天醒几次的深度睡眠设备来说,这颗 几毛钱的芯片就是它与世界时间唯一的连线。

硬件:一条分压支路 + 一个开漏指示脚

• 电池电压采样:Li-ion 电池经 1MΩ / 2.2MΩ 电阻分压接到 GPIO4 (ADC1_CH4)。分压比 0.6875,反算电池电压要乘 32/22;
• 充电检测:TP4054 的 CHRG 脚是开漏输出,充电时拉低,接在 GPIO21 (内部上拉),读电平即知状态;
• 充电芯片自带过充保护,满电 4.2V。

GPIO21 有个坑要记在本子上:它是 UART0 的 TX 脚,带电池烧录固件时, 如果电池恰好正在充电,CHRG 的电平和串口 TX 驱动会打架。烧录前拔电池, 或者充完电再烧。

测量:中位数 + 曲线拟合校准

ESP32-C3 的 ADC 以不准出名,直接单次采样的读数能抖出一百多毫伏,反映到 电量百分比上就是好几个点的跳动。驱动用了三层降噪:

int battery_measure_mv(void)
{
    // 1. 建 ADC 单元,12bit + 12dB 衰减
    // 2. eFuse 曲线拟合校准(raw → 节点 mV,芯片出厂曲线烧在 eFuse 里)
    // 3. 连采 16 次 → 插入排序 → 取中位数(第 7/8 个的平均)
    int node_mv = mid_raw * 3300 / 4095;        // 校准不可用时的退化公式
    if (cali) adc_cali_raw_to_voltage(cali, mid_raw, &node_mv);
    int bat_mv = node_mv * 32 / 22;             // 还原分压前的电池侧电压
    if (bat_mv > 4200) bat_mv = 4200;           // 钳到 Li-ion 满电
    return bat_mv;
}

• 16 点中位数:比平均值稳——毛刺样本被排序挤到两头,影响不到中位数;
• 曲线拟合校准:C3 的 eFuse 里烧了出厂 ADC 曲线, adc_cali_create_scheme_curve_fitting 一行接入;校准方案创建失败时 退化回线性换算,日志里会告警;
• 分压支路的另一个细节:12dB 衰减下节点侧量程 0–3.6V,折算电池侧约 5.2V——4.2V 的满电锂电池离削顶还很远。(板卡注释里曾有一句「3.6V 以上 会削顶」,是理解错了量程主体,已纠正。)

还有一个深度睡眠设备特有的风格:battery_measure_mv() 每次调用都新建 ADC 单元、用完即删。因为每次唤醒都是一次重启,不存在「复用上次的句柄」, 无状态反而是对的。

电量估算:OCV 表 + 线性插值

从电压算百分比,正经办法是库仑计,但那需要额外芯片和采样电阻。对这台 「99% 时间在深度睡眠、醒来量一次」的设备,开路电压(OCV)查表就够了—— 测量时刻设备几乎不带负载,端电压极接近开路电压:

static const struct { int mv; int pct; } SOC_TABLE[] = {
    {3000, 0}, {3300, 5}, {3500, 10}, {3600, 20},
    {3730, 40}, {3850, 60}, {3970, 80}, {4100, 100},
};

int battery_soc(int mv)   // 表内线性插值,两端钳位 0..100

锚点取自 Li-ion 放电曲线的拐点:3.5–3.7V 之间电压掉得慢,3.5V 以下 断崖。插值让百分比不至于一格一格跳。

代码组织上有个刻意的设计:battery_soc() / battery_level() 所在的 battery_core.c 零 ESP-IDF 依赖,在 PC 上直接被 tools/test_battery_core.py 跑断言,不用为改一行插值逻辑就烧一次板子。

充电检测:一个脚,两个坑

battery_charge_t battery_charge(void)
{
    // CHRG 开漏:内部上拉,充电时被 TP4054 拉低
    gpio_config_t io = {
        .pin_bit_mask = 1ULL << PIN_CHRG,
        .mode = GPIO_MODE_INPUT,
        .pull_up_en = GPIO_PULLUP_ENABLE,
    };
    gpio_config(&io);
    return gpio_get_level(PIN_CHRG) == 0 ? BATTERY_CHARGE_YES : BATTERY_CHARGE_NO;
}

配置失败返回 UNKNOWN 而不是硬猜——调用方对 UNKNOWN 的处理是「当作没在 充电但不做低电动作」,比错误地宣称「正在充电」安全。

策略:测不准也不惩罚用户

测量值最终驱动的是几个用户看得见的行为,每条都为「传感器不可靠」留了退路:

低电时缩短巡检周期看着反直觉(不是更费电吗),但这是电量曲线的断崖区: 从 LOW 掉到 CRITICAL 可能就一两天,每小时醒来一次能保证设备在彻底断电前 把「请充电」亮出来,而不是默默死掉。这段时间总共也醒不了几十次,代价可以 忽略。

电量图标本身是构建期生成的 1bpp 位图(tools/gen_batt_icons.py 生成 icon_data.c),和字库同一套管线;「请充电」三个字则直接复用文章字库的 16px 子集。

小结

这套电源管理的总代码不到 300 行,账本逻辑却层层设防:采样靠中位数, 换算靠出厂校准,估算靠 OCV 表,策略靠「失败即宽松」。电池设备的电源 读数永远带噪声,设计时先想好每一个读数失败时的行为,比把精度再抠高 一个百分点重要得多。

先交代硬件:

• 屏幕:E0154A04-BF-S,1.54 寸黑白,UC8253 家族控制器;
• 接线:SPI 四线(SCK/MOSI/CS,没有 MISO),外加 DC(命令/数据选择)、RST、BUSY 三个控制脚;
• 主控:ESP32-C3,硬件 SPI,10 MHz。

坑一:datasheet 的分辨率是错的

A01 版 datasheet 写的是 152×152、每字节 8 像素。按这个参数画图,右半边花屏, 条纹间距也对不上。

验证方法很土:画一张「标尺图」——每隔固定数量的数据字节画一道刻度竖线,烧进屏幕 看刻度往哪儿漂。实测刻度每 8 行数据向右漂 16 像素,反推控制器显存的行距是 50 字节/行(显存是 2 bit/像素),50 × 8 ÷ 2 = 200,这才是真实的宽度。

datasheet A01:152×152,8 px/byte   ← 别信
实测 A04 玻璃:200×200            ← 显存行距 50 B/row

于是驱动里的定义是:

#define EPD_WIDTH  200
#define EPD_HEIGHT 200
#define EPD_FB_SIZE (EPD_WIDTH / 8 * EPD_HEIGHT)   // 5000 字节/平面

教训:拿到陌生玻璃,先烧标尺图量分辨率,再写渲染代码。同一块屏不同批次 (A01 → A04),关键参数都可能变。

坑二:BUSY 低电平才是忙

UC8253 的 BUSY 语义(datasheet Note 5-4,实测一致):LOW = busy,HIGH = idle。 和很多「BUSY 拉高才算忙」的习惯相反,轮询等的是高电平:

#define EPD_BUSY_IDLE_LEVEL 1

static esp_err_t wait_busy(int timeout_ms)
{
    for (int waited = 0; waited < timeout_ms; waited += 10) {
        if (gpio_get_level(PIN_EPD_BUSY) == EPD_BUSY_IDLE_LEVEL) return ESP_OK;
        vTaskDelay(pdMS_TO_TICKS(10));
    }
    ESP_LOGW(TAG, "BUSY stuck at %d after %d ms",
             gpio_get_level(PIN_EPD_BUSY), timeout_ms);
    return ESP_ERR_TIMEOUT;
}

顺带一个 FreeRTOS 细节:轮询间隔必须不小于一个 tick。CONFIG_FREERTOS_HZ=100 时 tick 恰好 10 ms,vTaskDelay(pdMS_TO_TICKS(10)) 是一次真正的让出;间隔再短 就截断成 vTaskDelay(0),等于不让出 CPU,整个超时预算在几毫秒内烧完,BUSY 还没 等到就被误报超时。

坑三:分块 SPI 传输会把命令流切碎

第一版驱动把 5000 字节的显存拆成 64 字节一段分批发(以为和别家 SPI 屏一样需要 分块),结果图案永远缺一块。原因是 ESP32 的硬件 CS 在每个事务之间自动拉高,而 UC8253 的 CS 上升沿会复位控制器内部的写入状态机——控制器以为你要开始发新命令了, 于是大块显存写一半就被「截胡」。

解法反而更简单:整个 payload 一次事务发完,让 DMA 去搬运:

static esp_err_t spi_tx(const uint8_t *data, int len)
{
    spi_transaction_t t = {
        .length = 8 * (size_t)len,
        .tx_buffer = data,
    };
    return spi_device_transmit(s_spi, &t);   // 一次事务,DMA 链式搬完
}

SPI 总线初始化时把 max_transfer_sz 设成 5000(一整个平面),DMA 通道用 SPI_DMA_CH_AUTO 自动分配。C3 的 DMA 一次链式搬运 5 KB 毫无压力。

刷新:DTM1/DTM2 双平面

UC8253 的全刷流程(datasheet §11.1 的「LUT from OTP」路径)每次要写两个平面:

控制器对比两个平面,为每个像素选择对应的驱动波形(白变黑、黑变白、保持不变各有 自己的脉冲序列),这就是墨水屏刷新时「闪一下」的来源。数据格式 1bpp,1=白、0=黑, MSB 在前。

驱动里用一个静态数组跟踪「玻璃上现在是什么」:

static uint8_t s_old_plane[EPD_FB_SIZE];   // 专供 DTM1

esp_err_t epd_full_refresh(const uint8_t *framebuffer)
{
    esp_err_t r = epd_cmd(0x10, s_old_plane, EPD_FB_SIZE);  // DTM1: 旧帧
    if (r == ESP_OK) r = epd_cmd(0x13, framebuffer, EPD_FB_SIZE);  // DTM2: 新图
    if (r != ESP_OK) return r;
    memcpy(s_old_plane, framebuffer, EPD_FB_SIZE);          // 记录玻璃状态

    r = epd_cmd(0x04, NULL, 0);              // PON
    if (r == ESP_OK) r = wait_busy(3000);
    if (r != ESP_OK) return r;

    r = epd_cmd(0x12, NULL, 0);              // DRF
    if (r == ESP_OK) r = wait_busy(15000);
    return r;
}

上电后玻璃是全白的,所以 epd_init 成功后把 s_old_plane 填满 0xFF(1=白), 保证第一次刷新时 DTM1 和玻璃的真实状态一致。

别覆盖 OTP 里的出厂配置

UC8253 出厂把 LUT(驱动波形)、PWR(电源时序)、CDI(驱动强度)、PLL 都烧进了 OTP, 上电自动加载。除非你比屏幕厂更懂这块玻璃,否则别发命令去覆盖它们——覆盖错了轻则 灰底、重则花屏。我们的刷新流程完全依赖 OTP 默认值,实测干净利落,一毫秒的调参 都没花。

睡觉:POF + DSLP

显示结束后两步断电,控制器功耗归零:

void epd_sleep(void)
{
    epd_cmd(0x02, NULL, 0);                  // POF: power off
    vTaskDelay(pdMS_TO_TICKS(20));
    static const uint8_t DSLP[] = {0xA5};    // 0xA5 是 datasheet 规定的魔数
    epd_cmd(0x07, DSLP, 1);                  // DSLP: deep sleep
}

墨水屏的价值在这一步兑现:断电后画面保持,屏幕和主控一起睡,下次唤醒只管画新帧。 对一个 99% 时间在睡觉的电池设备来说,「不刷新就不耗电」是选墨水屏而不是 OLED 的 根本理由。

小结

三个坑的共性是「datasheet/直觉和实物不符」:分辨率要量出来,BUSY 极性要实测确认, CS 行为要读芯片手册的注释。驱动最终不到 160 行,却是在标尺图、逻辑分析和一次一次 烧录里磨出来的。嵌入式外设 bring-up 没有捷径,但每一次踩坑都值得记下来——下一次 换屏,大概率还会用上。

换来了什么

• 部署极简:out/ 目录整个拷上服务器/OSS 就完事,不需要 PM2、 不需要容器、不需要考虑 Node 版本漂移;
• 天然抗流量:静态文件随便被 CDN 缓存,官网场景下几乎不存在 「被打挂」的概念;
• 安全面小:没有服务端运行时,攻击面收缩到静态文件本身;
• 构建期报错:所有数据获取都发生在 next build,内容错了构建直接 失败,坏内容到不了线上。

失去了什么

静态导出本质是把所有「动态」挪到构建期或客户端,以下能力直接不可用:

对品牌官网和技术博客,这个清单几乎无痛:内容发布频率低(重新构建即 「ISR」),交互都在客户端,表单可以走第三方代收再通知到企微/邮件。

常用的「伪装动态」手法

1. Route Handler + force-static 生成派生文件。 RSS、sitemap 这类「构建期可确定」的动态产物:

// app/rss.xml/route.ts
export const dynamic = "force-static";

export async function GET() {
  return new Response(buildRss(), {
    headers: { "Content-Type": "application/rss+xml; charset=utf-8" },
  });
}

构建时执行一次,输出落成真正的 out/rss.xml 静态文件。

2. generateStaticParams 展开所有路径。 /posts/[slug] 这类动态路由必须在构建期穷举:

export function generateStaticParams() {
  return getAllPosts().map((post) => ({ slug: post.slug }));
}

忘了写这个函数,动态路由在静态导出下会被静默跳过——不报错,只是 产物里没有那些页面,发布后才发现 404。

3. 数据获取全部收口到构建期模块。 文件读进内存、校验、缓存,页面组件只消费纯函数结果。好处是测试 不需要起 Next,数据层单测就是普通 Node 测试。

判断 checklist

什么项目适合静态导出:

• 内容发布频率低,发新内容 = 触发一次重新构建可以接受;
• 没有按请求变化的个性化内容(登录态、A/B、地理定向);
• 搜索/评论/表单这类动态能力愿意交给第三方或客户端方案;
• 有 CI 能自动构建发布(没有的话,发布 = 手动跑命令)。

反过来,只要有任何一条硬性不满足——比如需要 SSR 做 SEO 的个性化 首页——就老实用 next start 或托管到 Vercel,别跟 output: 'export' 较劲,它的边界是设计如此,不是 bug。

一句话结论

静态导出适合「内容即产品」的站:官网、博客、文档站。它把复杂度从 运行时挪到了构建期,而构建期复杂度是靠 CI 和纪律管理的,比运行时 复杂度便宜得多。

现在的状态机长这样:

深度睡眠 ──KEY1 按下 / 定时器──▶ 醒来,抽签上屏 ──3 秒无操作──▶ 回去睡

硬件红线:只有 GPIO0-5 能做唤醒源

ESP32-C3 深度睡眠的 GPIO 唤醒只认 GPIO0–5(RTC 域引脚),其他引脚睡死过去就再也 叫不醒了。这块板子把两条路都踩了一遍:

• 旧版布线里,加速度计 INT1 在 GPIO19、一个按键在 GPIO20——运行时当 输入随便用,但不能做睡眠唤醒源;
• 唯一接进 RTC 域的是加速度计 INT2(GPIO2),它被指定为唤醒引脚——偏偏还是 个坏的(下文);

唤醒 API 是电平触发,不是边沿:

esp_deep_sleep_enable_gpio_wakeup(1ULL << PIN_KEY1, ESP_GPIO_WAKEUP_GPIO_LOW);

设计教训最终由改版落实:新版 PCB 把主按键(SW1,固件里叫 KEY1)挪到了 GPIO2,按键唤醒从此有了合法身份;摇晃只在亮屏窗口内当「换签」手势, 不再承担唤醒。

醒来第一件事:谁叫醒的我

深度睡眠醒来等于一次重启:ROM → 二级 bootloader → app_main 从头跑,RAM 内容不保留。入口先用唤醒原因分诊:

bool first_boot = esp_sleep_get_wakeup_cause() == ESP_SLEEP_WAKEUP_UNDEFINED;
if (first_boot) {
    enter_deep_sleep(SLEEP_US_12H);   // 装电池后的第一次开机:布置唤醒源,立刻回去睡
    return;
}
// 走到这里:KEY1 唤醒或定时器到点 —— 量电量、抽签、上屏

冷启动分支很关键:设备装电池那一刻开始,固件的任务就是布置好唤醒源然后立刻 消失,绝不能「亮一下屏表示开机」——现场没有人在看。

现役方案:按键电平唤醒 + 长短两档定时器

进睡前布置唤醒源:KEY1 低电平唤醒 + 一个兜底定时器——哪怕按键彻底失效, 设备也会定期醒来刷一次存在感:

void enter_deep_sleep(uint64_t sleep_us)
{
    // hold 住 I2C 引脚,让 RTC 域的 SC7A20 在睡眠中不掉电
    if (sc7a20_init() == ESP_OK) {
        gpio_hold_en(PIN_I2C_SDA);
        gpio_hold_en(PIN_I2C_SCL);
        gpio_deep_sleep_hold_en();
    }
    esp_deep_sleep_enable_gpio_wakeup(1ULL << PIN_KEY1, ESP_GPIO_WAKEUP_GPIO_LOW);
    esp_sleep_enable_timer_wakeup(sleep_us);   // 正常 12h;低电量时由上层缩短为 1h
    esp_deep_sleep_start();
}

定时器间隔现在是电源策略的入参:电量正常睡 12 小时,低电量缩短到 1 小时 巡检(见电源篇)。

弯路:唯一的唤醒脚是坏的,轮询硬扛了几个版本

旧板上被寄予厚望的 INT2(GPIO2)是 stuck HIGH 的硬件缺陷——引脚被外部驱动 为高,而唤醒要等的恰恰是高电平,挂上唤醒源芯片瞬间就被自己叫醒。等改版 之前,固件切到 POLL_MODE 硬扛:

深度睡眠(3 秒定时器)
   │ 醒来
   ▼
看 INT1(GPIO19)是否 HIGH(摇晃锁存)、按键是否 LOW
   │ 都不是 → 立刻回去睡 3 秒,循环
   │ 有触发
   ▼
抽签上屏,3 秒窗口内可连着换签

• 传感器侧照常攒事件:SC7A20 靠 I2C 引脚的 gpio_hold 在睡眠中保住供电 和配置,摇晃会把 INT1 锁存成 HIGH,等着主控来读;
• 主控每 3 秒付一次「假醒」的成本:完整跑一遍 bootloader → app_main → 自检 → I2C 初始化 → 读几个电平 → 回睡,单次几百毫秒;
• 代价是响应延迟:摇晃到亮屏平均晚 1.5 秒、最差 3 秒。对一个「摇签」 设备,这个延迟反而有点像抽签的仪式感。

轮询方案撑到了改版那天,随后和摇晃唤醒一起整体退役——新版板上 INT2 不再 接线,唤醒职责完全交给 GPIO2 上的按键。

唤醒后的世界是全新的

深度睡眠唤醒等于重启,三条直接影响写代码的方式:

1. 所有外设重新初始化。SPI/I2C/GPIO 配置一个都省不掉;驱动里的 s_ready 这类「已初始化」标志是静态变量,重启后自动归零,恰好是对的。
2. gpio_hold 穿越睡眠。唤醒后先 gpio_hold_dis 释放,再重新配置引脚, I2C 总线才能正常驱动——顺序反了就是「设备第二次交互就失灵」。
3. 想跨睡眠记状态,只能走 RTC_DATA_ATTR 慢速内存或 NVS。这个项目的 签文每次随机,干脆不记,少一个状态同步问题。

小结

现在 enter_deep_sleep 缩到了十行:hold 住 I2C、挂按键唤醒、上定时器、睡。 回头看这一坑三折:GPIO0-5 的红线是布线时欠的账,轮询是给硬件缺陷打的临时 补丁,改版才是真正的还债。「硬件缺陷不可怕,可怕的是固件没有给硬件留退路」 ——退路的价值不是永远走下去,而是撑到硬件修好的那天。

上电:先确认芯片在

SC7A20 有两个可选 I2C 地址(0x19,SDO 接高;0x18,SDO 接低)。这颗板子的 SDO 悬空,电平不确定,所以驱动把两个地址各试一遍,用 WHO_AM_I(寄存器 0x0F,固定 返回 0x11)确认身份:

const uint16_t addrs[] = { 0x19, 0x18 };   // SDO 悬空,两个地址都试
for (int i = 0; i < 2; i++) {
    // 挂设备 → 读 WHO_AM_I → 等于 0x11 就找到了,否则摘掉换下一个
}

比「芯片不在」更隐蔽的是「总线上不去」。bringup 时设备怎么都扫不到,最后发现 外部 4.7k 上拉电阻根本没起作用——只有打开 ESP32 的内部上拉之后,SC7A20(0x19) 和同一条总线上的 RX8025T 时钟芯片(0x32)才有 ACK:

i2c_master_bus_config_t bus = {
    // ...
    .flags.enable_internal_pullup = true,   // 外部上拉缺失,内部上拉顶上
};

内部上拉驱动 100 kHz 的 I2C 实测稳定;想上 400 kHz 之前,还是先把外部上拉补好。

运动检测的寄存器链路

SC7A20 的运动中断是一套 AOI(方向/事件检测)逻辑,从采样到 INT 引脚要过七道 配置。最终生效的是 INT1 一路,负责亮屏窗口内的「摇一摇换签」;旧板曾把同样 的配置复用到 INT2 做深度睡眠唤醒,新板改版后这条路已随摇晃唤醒一起移除:

阈值和时长的取舍是这套配置的灵魂:

• THS = 0x30 ≈ 770 mg:放桌上敲键盘、隔壁关门这类低于 500 mg 的振动全部 过滤,用手腕摇一下(轻松超过 1 g 的变化)才触发;
• DUR = 5 @ 10 Hz:单次尖峰——比如设备掉在桌上的瞬间——不触发,持续 500 ms 的运动才被认定为「摇晃」。

坑:重力是最大的干扰源

第一版配置没开 HPF(CTRL2 保持 0),现象很诡异:设备一进深度睡眠,INT 立刻变高; 醒来清掉锁存,下一轮又锁,永远消停不下来。

翻寄存器手册才想明白:AOI 检测的是「加速度是否超过阈值」,而静止平放时 Z 轴永远 扛着 +1 g 的重力,770 mg 的阈值根本罩不住它——事件条件恒成立,锁存清一次 立一次。

解法就一行:把高通滤波器接进 AOI 通路(CTRL2 = 0x01)。HPF 把静态重力分量滤掉, 只剩运动产生的动态变化,事件条件就只对真实的加速度变化成立了。代价是重写配置后 HPF 需要几百毫秒稳定,进睡前要留出这段时间,否则第一下是误触发。

这个坑的通用教训:加速度计的「静止」在原始数据里不是零,是 1 g。任何基于 绝对阈值的判断,都要先想清楚重力去哪儿了。

锁存与释放:LIR 机制

CTRL5 的 LIR 位决定事件的处理模型:不锁存时 INT 是内部定时的脉冲;开启 LIR 后, INT 电平保持到软件读 SRC 寄存器为止。睡眠唤醒场景必须开 LIR——芯片要在主控睡觉 期间把事件「攒住」,等主控醒来确认:

esp_err_t sc7a20_clear_irq_int1(void)
{
    uint8_t src;
    return rd(REG_INT1_SRC, &src);   // 读 SRC 即释放锁存
}

释放时机也有讲究:换签窗口里检测到 INT1 变高之后,要先清锁存再继续等下一 次,否则同一个事件会被反复读到。项目里的做法是「边沿触发 + 触发后等 INT1 回低,期间不停清锁存」,保证一次摇晃只换一张签。

睡眠时让传感器活着

深度睡眠时 ESP32-C3 的 GPIO 会掉配置,但 SC7A20 必须继续采样攒事件。做法是把 I2C 两个脚用 gpio_hold 钉在当前电平,再打开深度睡眠期间的全局 hold:

gpio_hold_en(PIN_I2C_SDA);
gpio_hold_en(PIN_I2C_SCL);
gpio_deep_sleep_hold_en();

对应的坑在唤醒侧:hold 的状态会活着穿过唤醒,重新初始化 I2C 之前必须先把两个脚 释放掉(gpio_hold_dis),否则总线被 hold 卡死,第一次唤醒之后的每次 I2C 访问 都「not responding」。这个 bug 的表象是「设备第二次摇晃就失灵」,非常误导。

小结

到这里整条链路稳定运行:摇晃 → 传感器锁存事件 → 主控在换签窗口里读到 INT1 电平,读 SRC 释放锁存 → 换一张签;设备放桌上,HPF 滤掉重力、阈值滤掉环境 振动,可以安安静静睡大觉。加速度计运动检测的配置项看着多,真正要调的只有 三个数:阈值、时长、HPF 开关——剩下的都是把它们正确地写进正确的寄存器。

目录结构

website/
├── packages/
│   ├── www.yunjuiot.com.cn/   # 公司主站(端口 3000)
│   ├── www.elinchong.com/     # 品牌站(端口 3001)
│   ├── www.xunhong168.com/    # 单页官网(端口 3002)
│   └── www.shenyifei.com/     # 这个博客(端口 3003)
├── shared/                    # 跨包共享资产(pcb3d 流水线等)
├── scripts/                   # OG 封面、PDF 等 Python 生成脚本
└── docs/plans/                # 每个功能的设计文档

每个站点是一个独立的 Next.js App Router 包,有自己的 package.json 和 next.config.ts,互不引用对方的组件。共享的只有根目录的依赖声明、 生成脚本和资产——组件级别的「复用」我刻意没做,后面说为什么。

依赖:全在根上

站点级 package.json 只声明 scripts,依赖全部挂在仓库根:

{
  "name": "www.shenyifei.com",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack -p 3003",
    "build": "next build"
  }
}

四个站共用一个 Next.js 版本,升级时一次升级全部,不存在「A 站还在 Next 14、B 站已经 Next 15」的漂移。代价是升级需要四站都回归一遍, 但静态导出站点的回归成本低(构建过 = 大概率没事)。

约定大于配置

同一件事在四个站里长得一模一样:

• output: 'export' 静态导出,images: { unoptimized: true };
• app/layout.tsx 里集中管理 SEO 元数据、OG 封面、结构化数据;
• sitemap.ts / robots.ts / not-found.tsx 三个基础设施文件齐全;
• 端口号写死在 dev script 里,3000 起,一个站一格。

约定带来的好处在改版时最明显:我知道任何一个文件的「对应物」在另外 三个站的哪个位置,AI 辅助改版时提示词都省了。

为什么不做组件级共享

最早考虑过把 Header/Footer/ShareBar 抽成 workspace 共享包,后来放弃了:

1. 四个站的品牌视觉完全不同,能共享的只有逻辑骨架,而骨架只有几十行;
2. 抽象包一旦改坏,四个站同时挂,耦合的爆炸半径反而变大;
3. 每个站代码量都不大(几百行),复用收益撑不起一层抽象的维护成本。

真正值得共享的是资产和流水线:PCB 的 STEP→GLB 转换脚本、OG 封面 生成脚本,这些放 shared/ 和 scripts/,谁用谁调,不产生运行时耦合。

一个 pnpm 特有的坑

pnpm 的 node_modules 是绝对路径 junction,某个包里有 node_modules 时 (比如 shared/pcb3d 自带依赖),webpack 的 FileSystemInfo 快照会把它 误处理,构建直接崩:

// next.config.ts — 按语义并入 managedPaths 跳过快照
config.snapshot.managedPaths = [
  ...(config.snapshot.managedPaths ?? []),
  /[\\/]scripts[\\/]pcb3d[\\/]node_modules/,
];

这类问题没有通用解,记住 pnpm 的 monorepo 里出现「莫名其妙的构建崩溃」, 先怀疑 junction 路径。

小结

monorepo 对「多个小站、一个人维护」的场景是明确的正解:依赖统一、 约定统一、部署统一。但要忍住两个冲动——不要过早抽共享组件包, 也不要为了让目录好看而引入构建复杂度。

总体链路

立创EDA STEP → step2obj.py (OCCT 三角化) → obj2glb.mjs (GLB)
            → gltf-transform 量化 → public/models/*.glb → <model-viewer>

分四步,每步一个独立脚本,串起来跑。

第一步:STEP 三角化,为什么不用 WASM

STEP 是 B-Rep 边界表示,浏览器渲染不了,先要三角化成网格。现成方案里 occt-import-js 提供 WASM 版的 OCCT,看似最省事,但实测对这种多层板 STEP 会输出空网格,问题出在它的 WASM 构建裁剪了部分几何内核能力。

最后用的本机 Python + cadquery-ocp(完整 OCCT 绑定)做三角化, 顺带解决另一个需求:按层名配色。

# step2obj.py 核心逻辑(节选)
from OCP.STEPControl import STEPControl_Reader
from OCP.BRepMesh import BRepMesh_IncrementalMesh

reader = STEPControl_Reader()
reader.ReadFile("board.step")
reader.TransferRoots()
shape = reader.OneShape()
BRepMesh_IncrementalMesh(shape, 0.3, False, 0.5, True)

PCB 的丝印层、阻焊层、基板在 STEP 里是不同颜色的实体,三角化后按颜色 拆分材质写入 OBJ,后面 glTF 转换时会自然映射成多个 primitive。

第二步:OBJ → GLB

这步没有技术含量,obj2gltf 一行命令,写成脚本只是因为要处理贴图路径和 缺省参数。GLB 比 OBJ+MTL 好在单文件、二进制、带 PBR 材质。

第三步:量化,模型从 40MB 到 4MB

原始 GLB 转出来 40MB 左右,网页加载不能接受。gltf-transform 三连:

npx gltf-transform weld board.glb t.glb
npx gltf-transform prune t.glb t2.glb
npx gltf-transform quantize t2.glb board-q.glb

quantize 使用 KHR_mesh_quantization 扩展,把顶点属性从 float32 压到 int16,配合 weld 去重和 prune 清理,体积降到 4MB,视觉上几乎无差别。 <model-viewer> 原生支持这个扩展,不需要额外解码库。

另一个经验:导出前在 EDA 里隐藏小元件(0402 电阻电容之类)的 3D 模型, 源文件体积直接砍半——这些元件在客户视角下本来也看不清。

第四步:网页端

展示组件直接用 @google/model-viewer,自托管它编译好的单文件, 不依赖运行时 CDN:

<model-viewer
  src="/models/board.glb"
  camera-controls
  auto-rotate
  shadow-intensity="1"
  style="width:100%;height:480px">
</model-viewer>

相比自己写 Three.js,model-viewer 把相机惯性、AR 入口、无障碍这些都 处理好了。如果后续要做「点击元件高亮 BOM」这类深度交互,再换 Three.js 也不迟——模型和管线都是复用的。

小结

整条管线写成三个脚本,换新板子就是「导出 STEP → 跑脚本 → 加一条记录」, 非前端同事也能自己发新版。