MAG160C/docs/linux_port_plan.md

# MAG160C Linux 移植方案（参考 LiThermal）

> 目标：把 MAG160C 热像仪（160x120，USB）移植到 Linux 嵌入式设备，
> 参考 LiThermal 项目（https://github.com/diylxy/LiThermal）的硬件与软件架构。
> 日期：2026-08-14

## 1. LiThermal 架构（参考基线）

| 项目 | LiThermal |
|---|---|
| 热像模组 | 海康 TB4117（290 元，网络/RTSP 取流，USB-NCM）|
| 主控 | 全志 T113-S3（Tina Linux）|
| 封装 | QFP128（0.3mm 引脚，手焊可行）|
| UI | LVGL |
| 动画 | rlottie（Lottie 动画）+ LVGL 内置动画 |
| 显示 | RGB 屏（86 屏/4.3 寸 TFT）|
| 2D 加速 | G2D（全志 2D 引擎）|

MAG160C 与 LiThermal 的差异：MAG160C 是 **USB 原生协议**（EP 0x81 帧流，
非 UVC/网络），数据量极小（160x120x2B = 38.4KB/帧，15fps ≈ 576KB/s）。
对主控的要求比 4117 的网络流更低。

## 2. Linux 主控芯片选型

要求：非 BGA、价格便宜、能跑图形显示和动画（LVGL/2D 加速，无 3D 需求）。

| 芯片 | 封装 | 价格 | 核心 | 显示接口 | 2D/GPU | 生态 | 结论 |
|---|---|---|---|---|---|---|---|
| **全志 T113-S3** | QFP128 | ~15-25 元 | 双 A7 1.2G + RISC-V | RGB/MIPI-DSI | G2D 2D | Tina Linux 成熟 | **首选**（LiThermal 验证）|
| 全志 V3s | QFP128 | ~12-18 元 | 单 A7 1.2G | RGB | G2D | Tina Linux | 备选（单核跑 LVGL+渲染有余）|
| 全志 F1C200s | QFP88 | ~8-12 元 | ARM926EJ-S 400M | RGB | 无 | 老 | 太弱（动画吃力）|
| 瑞芯微 RV1103/RV1106 | QFN88 | ~10-15 元 | 单 A7 + NPU | MIPI-DSI | RGA 2D | buildroot | QFN 手焊难，DSI 屏贵 |
| 君正 X2000 | LQFP176 | ~20-30 元 | 双 XBurst2 | RGB | 无 | 弱 | 生态差 |
| 瑞芯微 RK3128/3288 | BGA | — | — | — | — | — | **排除（BGA）** |

**推荐：T113-S3（QFP128）**。理由：
- LiThermal 已在同平台跑通 LVGL + rlottie 动画 + 热像显示，风险最低
- 双 A7 1.2GHz：渲染管线（NUC 查表 19200 像素 + LUT + 2x 升采样）
  每帧 <2ms（C 整数运算），15fps 毫无压力，CPU 余量给 LVGL 动画
- G2D 提供 2D 加速（blit/旋转/缩放），适合灰度帧上屏
- QFP128 手焊可行（LiThermal README 确认 0.3mm QFP）
- 价格 ~20 元，与 TB4117（290 元）对比，MAG160C 整机成本可压到很低

备选：V3s（更低成本，单核 A7 够用）；若需 MIPI 摄像头级方案再考虑 RV1106。

## 3. 显示方案

| 方案 | 接口 | 适合 |
|---|---|---|
| RGB 并口 TFT（4.3/5 寸）| RGB565/888 + 背光 | 首选，便宜，T113-S3 原生支持 |
| MIPI-DSI | DSI | 分辨率更高，屏贵 |
| HDMI | — | 桌面/工业屏 |

T113-S3 + 4.3 寸 RGB 屏（800x480）+ 电容触摸 ≈ 全套 60-80 元。

## 4. 动画渲染库选型

| 库 | 类型 | 资源占用 | 适合场景 | 结论 |
|---|---|---|---|---|
| **LVGL** | 嵌入式 UI 框架 | 极低（~100KB RAM）| UI + 基础动画（lv_anim、转场、进度环）| **主力** |
| **rlottie** | Lottie 矢量动画 | 低（渲染 json）| 开机动画、扫描动画、图标动画 | LiThermal 已用，直接参考 |
| ThorVG | 矢量图形 | 低 | rlottie 替代（更活跃）| 备选 |
| Qt/Flutter | 重型 | 高 | — | 排除（T113-S3 无 3D GPU）|

**推荐组合：LVGL（UI/交互动画）+ rlottie（Lottie 特效动画）**，
与 LiThermal 完全一致。热像显示用 LVGL image 对象每帧 flush RGB
帧（G2D blit 加速），帧率独立于 UI 动画。

## 5. 现有 csdk 的 Linux 适配点

### 5.1 平台无关（直接可用）
- `mag160c_ir.c`：libusb-1.0 本身就是跨平台（Linux 原生支持）✓
- 帧解析/流组装、温度换算、TCM：纯 C 无平台依赖 ✓
- **渲染管线（NUC/窗口/LUT/gray/2x/调色板/FFC 状态机）**：demo3 内实现，
  目前与 Win32 窗口耦合 → **需要抽取为平台无关模块（见 §6）**

### 5.2 需要适配
| 项目 | Windows（demo3）| Linux |
|---|---|---|
| USB 传输 | libusb bulk_transfer（单线程轮询）| 同 API；建议改用 libusb 异步/线程 + condvar |
| 帧线程 | 主循环轮询 | 独立线程 + 条件变量（csdk 已有线程模型）|
| 显示后端 | Win32 GDI + HALFTONE | fbdev / DRM-KMS / LVGL image |
| 输入 | Win32 消息 | touch（LVGL input device）|
| 日志 | demo3_diag.txt | syslog / stdout |

### 5.3 FFC 调度器
`mag160c_ffc_scheduler_t`（mag160c_display.h）已平台无关 ✓，Linux 侧
接线程 tick 即可。

## 6. 接口抽象设计（渲染管线抽取）

目标：`mag160c_render.h` —— 输入 raw 帧 + 设备状态，输出 RGB 帧，
零平台依赖，Windows/Linux 共用。

```c
/* mag160c_render.h（新） */
typedef struct mag160c_render_t mag160c_render_t;

/* 初始化：加载 DDT 表（路径），分配缓冲 */
mag160c_error_t mag160c_render_init(mag160c_render_t **out, const char *ddt_path,
                                    uint16_t width, uint16_t height);

/* 每帧驱动（等价官方 0x9ee0 + 0xca30）：
 *   frame   : USB 原始帧（0x1c 头 + 像素，或裸像素）
 *   has_hdr : 1=带帧头（自动提取快门/类型），0=裸像素（需外部给 shutter）
 *   out_rgb : 输出 320x240x3 RGB24（调色板着色后）
 * 内部完成：快门提取→FFC 状态机→ref 采集→表重建→NUC→盲元→
 *           窗口→LUT→gray→2x→palette */
mag160c_error_t mag160c_render_frame(mag160c_render_t *r,
                                     const uint8_t *frame, int has_hdr,
                                     uint8_t *out_rgb);

/* 查询（供 UI 显示） */
void mag160c_render_get_stats(mag160c_render_t *r, int *win_lo, int *win_hi,
                              int *mean, int *max, int *min);
int  mag160c_render_get_shutter(mag160c_render_t *r);
int  mag160c_render_get_ffc_pending(mag160c_render_t *r);  /* 供 FFC 调度 */

void mag160c_render_destroy(mag160c_render_t *r);
```

迁移步骤：
1. 把 demo3 的管线函数（load_ddt/select_endpoint/interp/ref_push/
   nuc_and_blind/stats_window/lut_rebuild/gray_map/upscale2x/palette/
   ffc 状态机）迁入 `csdk/src/mag160c_render.c`
2. demo3.c 改为调用 render API（Win32 侧只保留取帧 + 显示）
3. Linux 侧：`mag160c_render_frame()` + LVGL image flush

## 7. Linux 参考实现（最终形态）

```
[USB 帧线程] → mag160c_ir（libusb）
        ↓ raw 帧
[mag160c_render_frame] → 320x240 RGB
        ↓
[LVGL image 对象 + G2D blit] → 屏幕
        ↑
[LVGL UI：菜单/温度显示/FFC 按钮 + rlottie 开机动画]
```

整机成本估算（MAG160C 模组 ~200-300 元 + T113-S3 板 ~60-80 元）远低于
LiThermal（4117 290 元 + 板卡）。

## 8. 行动项

- [ ] 抽取 mag160c_render 模块（§6 接口）
- [ ] demo3 迁移到 render API（验证无回归）
- [ ] 编写 Linux 示例：fbdev 后端 + LVGL 集成（后续在 T113-S3 上验证）
- [ ] 文档：csdk/README 增加 Linux 移植章节