Merge branch 'dev'

Author: lxowalle

projects/app_thermal160_camera/README.md

@@ -1,34 +1,78 @@
-# MaixCAM Thermal 160 实时热成像监控
+# MaixCAM Thermal160 实时热成像监控
 
-  这是一个基于 MaixPy v4 框架开发的实时热成像监控程序，专门为 MaixCAM2（及后续支持型号）设计。该程序通过 UART 接收 160x120
-  分辨率的热成像原始数据，并实时渲染为具有 Ironbow（铁红） 伪彩映射的视频流。
+这是一个基于 MaixPy v4 的 MaixCAM2 Thermal160 实时热成像应用。程序通过 UART 接收 160x120 热成像帧，解析帧尾温度 telemetry，并实时渲染伪彩画面、中心点温度、最高/最低点和 NUC 状态。应用内置 24 小时历史记录模式，不再需要单独安装 history app。
 
 ## 硬件要求
 
-* 设备：MaixCAM2, 可参考该APP 代码移植到其他能够使用串口外设的平台
-* 传感器：支持 PMOD 接口或 UART 输出的 160x120 像素热成像模组。
+* 设备：MaixCAM2。
+* 传感器：Thermal160 / TN160 160x120 热成像模组。
 * 连接方式：
-  * MaixCAM2 默认使用 /dev/ttyS2。
-  * 波特率：初始 2,000,000，握手后最高可跳变至 4,000,000。
+  * UART：MaixCAM2 默认使用 `/dev/ttyS2`。
+  * 波特率：初始 `2,000,000`，发送 `0x44` 握手后切到 `4,000,000`。
+  * 复位：MaixCAM2 `A9` 配置为 `GPIOA9`，作为 Thermal160 软件复位脚。
+
+## 启动行为
+
+MaixCam2 电池供电时，Thermal160 可能不会自动上电/复位到可通信状态。应用启动 UART 前会自动执行一次 A9 软件复位：
+
+1. `pinmap.set_pin_function("A9", "GPIOA9")`
+2. `GPIOA9` 默认释放为高电平
+3. 拉低约 `120ms`
+4. 拉高释放并等待约 `400ms`
+
+当前按“低有效复位”实现。如果硬件接法是高有效，需要在代码顶部对调：
+
+```python
+THERMAL_RESET_IDLE_LEVEL = 0
+THERMAL_RESET_ACTIVE_LEVEL = 1
+```
+
+启动后前 3 秒显示 `Initializing thermal160` 和进度条；超过 3 秒仍没有合法帧，才显示 `thermal160 device not found`。
 
 ## 配置说明
 
-  在代码顶层可以根据需要调整以下常量：
+在代码顶层可以根据需要调整以下常量：
 
-* CMAP = True：设为 True 显示彩色热成像，False 则显示原始灰度图（零拷贝，性能更高）。
-* SKIP_COUNT = 10：启动时跳过的初始帧数，用于稳定传感器数据。
+* `SKIP_COUNT = 10`：启动后跳过的初始帧数。
+* `STARTUP_GRACE_SEC = 3.0`：启动等待页到 `Device not found` 的延迟。
+* `LONG_PRESS_SEC = 0.8`：长按右下角进入历史记录界面的触发时间。
+* `SAMPLE_INTERVAL_SEC = 1.0`：历史记录采样间隔。
+* `THERMAL_RESET_ASSERT_SEC = 0.12`：A9 复位保持时间。
+* `THERMAL_RESET_RELEASE_DELAY_SEC = 0.40`：释放复位后的等待时间。
 
 ## 协议简介
 
-  程序期望的 UART 数据格式为：
+程序期望的 UART 数据格式为：
+
+* 帧头：`0xFF`
+* 像素：`160 * 120 = 19200` 字节，8-bit 温度线性灰度
+* telemetry：30 字节，包含 `VTEMP / t_lo / t_hi / anchor / smooth / mean_diff / NTC / NUC` 等运行状态
+* 总长度：`1 + 19200 + 30 = 19231` 字节
+
+注意：像素区允许出现合法的 `0xFF`。同步逻辑不能再用“payload 中出现 `0xFF` 就重同步”的旧方案，而是通过 telemetry 合理性和下一帧帧头位置校验。
+
+## 历史记录模式
+
+实时界面下：
+
+* 短按右下角：切换伪彩色表。
+* 长按右下角约 `0.8s`：进入历史记录界面。
+
+历史记录界面下：
+
+* 左上角 `BACK`：返回实时热成像界面。
+* 右上角 `SAVE`：保存完整历史趋势图 PNG。
+
+程序启动后会每秒后台记录一次温度到 CSV，进入 history 界面不会中断实时 UART 读取。
+
+输出目录固定在当前 app 安装目录下：
 
-* 帧头：0xFF
-* 负载：19,200 字节 (160 * 120) 的单字节灰度数据。
-* 校验：负载中不包含 0xFF。
-总计单包大小为 19201 bytes
+* MaixCam2 安装运行时目录：`/maixapp/apps/thermal160_camera/output/`
+* CSV：`/maixapp/apps/thermal160_camera/output/history_YYYYmmdd_HHMMSS.csv`
+* PNG：`/maixapp/apps/thermal160_camera/output/trend_YYYYmmdd_HHMMSS.png`
 
 ## 注意事项
 
-* MaixCAM2 兼容性：程序包含针对 MaixCAM2 的波特率切换指令 (0x44)，使用其他串口设备时请根据实际通讯协议修改 HardwareHAL 类。
-* 资源释放：程序通过 finally 块确保在退出时安全释放 UART 资源。
-* 当 MaixCam2 仅由电池供电时，如果 TN160 在 MaixCam2 上电前已连接到 MaixCam2，则 MaixCam2 上电后需要手动按下 TN160 的RST复位按键。
+* A9 只能作为复位控制信号，不要用 MaixCAM2 GPIO 直接给 Thermal160 供电。
+* 软件复位、电平有效性和等待时间需要结合实际硬件上板验证。
+* 程序通过 `finally` 释放 UART 资源。

projects/app_thermal160_camera/README_EN.md

@@ -1,33 +1,78 @@
-# MaixCAM Thermal 160 Real-time Thermal Imaging Monitoring
+# MaixCAM Thermal160 Real-time Thermal Imaging
 
-This is a real-time thermal imaging monitoring application developed based on the MaixPy v4 framework, specifically designed for MaixCAM2 (and future supported models). The application receives raw thermal imaging data at 160x120 resolution via UART and renders it as a real-time video stream with Ironbow pseudo-color mapping.
+This is a MaixPy v4 Thermal160 live-view app for MaixCAM2. It receives 160x120 thermal frames over UART, parses the tail telemetry, and renders pseudo-color live video with center temperature, min/max markers, and NUC status. The 24-hour history recorder is now built into this app, so no separate history app is required.
 
 ## Hardware Requirements
 
-* Device: MaixCAM2, code can be ported to other platforms that support UART peripherals
-* Sensor: Thermal imaging module with PMOD interface or UART output supporting 160x120 pixels.
-* Connection method:
-  * MaixCAM2 defaults to /dev/ttyS2.
-  * Baud rate: Initial 2,000,000, can jump to up to 4,000,000 after handshake.
+* Device: MaixCAM2.
+* Sensor: Thermal160 / TN160 160x120 thermal imaging module.
+* Connections:
+  * UART: MaixCAM2 uses `/dev/ttyS2` by default.
+  * Baud rate: starts at `2,000,000`, then switches to `4,000,000` after sending the `0x44` handshake.
+  * Reset: MaixCAM2 `A9` is configured as `GPIOA9` and used as the Thermal160 software reset pin.
+
+## Startup Behavior
+
+When MaixCAM2 is powered from battery, Thermal160 may not automatically enter a usable powered/reset state. Before opening UART, the app sends one A9 reset pulse:
+
+1. `pinmap.set_pin_function("A9", "GPIOA9")`
+2. Release `GPIOA9` high by default
+3. Pull it low for about `120ms`
+4. Release it high and wait about `400ms`
+
+The current implementation assumes an active-low reset. If your hardware reset is active-high, swap these constants:
+
+```python
+THERMAL_RESET_IDLE_LEVEL = 0
+THERMAL_RESET_ACTIVE_LEVEL = 1
+```
+
+During startup, the UI shows `Initializing thermal160` with a progress bar for 3 seconds. It only shows `thermal160 device not found` if no valid frame is received after that grace period.
 
 ## Configuration
 
 Adjust the following constants at the top of the code as needed:
 
-* CMAP = True: Set to True to display color thermal imaging, False to display original grayscale (zero-copy, higher performance).
-* SKIP_COUNT = 10: Number of initial frames to skip on startup, used to stabilize sensor data.
+* `SKIP_COUNT = 10`: Initial frames skipped after startup.
+* `STARTUP_GRACE_SEC = 3.0`: Delay before showing `Device not found`.
+* `LONG_PRESS_SEC = 0.8`: Long-press time for entering the history screen from the lower-right button.
+* `SAMPLE_INTERVAL_SEC = 1.0`: History sampling interval.
+* `THERMAL_RESET_ASSERT_SEC = 0.12`: A9 reset assert time.
+* `THERMAL_RESET_RELEASE_DELAY_SEC = 0.40`: Delay after releasing reset.
 
 ## Protocol Overview
 
 The expected UART data format is:
 
-* Header: 0xFF
-* Payload: 19,200 bytes (160 * 120) of single-byte grayscale data.
-* Checksum: Payload does not contain 0xFF.
-* Total packet size: 19201 bytes
+* Header: `0xFF`
+* Pixels: `160 * 120 = 19200` bytes of 8-bit temperature-linear grayscale data
+* Telemetry: 30 bytes, including `VTEMP / t_lo / t_hi / anchor / smooth / mean_diff / NTC / NUC` runtime state
+* Total size: `1 + 19200 + 30 = 19231` bytes
 
-## Notes
+Note: valid pixel data may contain `0xFF`. The parser must not resync only because `0xFF` appears in the pixel payload. It validates frame alignment using telemetry plausibility and the next-frame header position.
+
+## History Mode
 
-* MaixCAM2 Compatibility: The program includes baud rate switching commands (0x44) specifically for MaixCAM2. When using other UART devices, please modify the HardwareHAL class according to the actual communication protocol.
-* Resource Release: The program ensures safe UART resource release on exit through the finally block.
+On the live-view screen:
+
+* Short-press the lower-right button: switch color map.
+* Long-press the lower-right button for about `0.8s`: enter the history screen.
+
+On the history screen:
+
+* `BACK` in the upper-left corner: return to live view.
+* `SAVE` in the upper-right corner: save a full-history trend PNG.
+
+The app records one sample per second to CSV in the background. Entering the history screen does not stop UART reading.
+
+Output files are stored under this installed app directory:
+
+* MaixCam2 installed app output directory: `/maixapp/apps/thermal160_camera/output/`
+* CSV: `/maixapp/apps/thermal160_camera/output/history_YYYYmmdd_HHMMSS.csv`
+* PNG: `/maixapp/apps/thermal160_camera/output/trend_YYYYmmdd_HHMMSS.png`
+
+## Notes
 
+* A9 is only a reset control signal. Do not power Thermal160 directly from a MaixCAM2 GPIO.
+* Reset polarity and timing still need validation on real hardware.
+* UART resources are released in the `finally` block on exit.

projects/app_thermal160_camera/app.yaml

@@ -4,9 +4,14 @@ name[zh]: 热成像仪160
 version: 1.0.0
 icon: assets/thermal.json
 author: Sipeed Ltd
-desc: Thermal Camera
-desc[zh]: 热成像仪
+desc: Thermal160 Camera
+desc[zh]: 热成像仪160
 include:
   - assets/thermal.json
   - app.yaml
   - main.py
+files:
+  - assets\thermal.json
+  - main.py
+  - README_EN.md
+  - README.md