MLX90640ESF-BAA / BAB 热成像阵列模块
接线与 ESP32 实测

/*
  ESP32-2432S028R(2.8寸黄屏CYD) + MLX90640 热成像阵列 触摸UI演示（中文版）v2

  接线：模块 VIN->3V3，GND->GND，SDA->IO27，SCL->IO22
       (跟 0911 ATECC608A / BMM150 / DPS310 / SCD41 项目同一路 CN1 I2C排针)
       ⚠ 别把SDA接到GPIO21——CYD板上21是屏幕背光(TFT_BL=21)，接SDA会跟背光打架。
  屏幕/触摸引脚沿用本系列已验证过的配置(TFT_eSPI + U8g2_for_TFT_eSPI中文点阵字体)。

  ✓ 已实机烧录验证(2026-08-01)：真实读到传感器序列号、屏幕正确显示热成像画面
  （手掌靠近能看到画面变化）。这一版是根据实机测试反馈的两个问题改的：

  1. "翻页点不了/不够灵敏"：根因是v1版把 mlx.getFrame() 直接放在 loop() 里调用——
     这个调用是阻塞的，内部要等两个subpage都读到才返回，在4Hz刷新率下每次可能
     卡住大几十到几百毫秒。loop()里触摸检测代码排在它后面，阻塞期间发生的点按
     完全检测不到，只有阻塞结束那一瞬间去看引脚状态，手指多半已经松开了。
     v2把MLX90640的读取搬到FreeRTOS的独立任务(sensorTask)，钉在core 0上跑，
     跟主循环(loop()，在core 1)用互斥锁交换数据；主循环不再被I2C等待卡住，
     触摸检测能一直按20ms间隔跑，翻页恢复正常灵敏度。
  2. "热图太小、手是蓝色看不清"：v1的调色板只有黑->紫->红->橙->白5个锚点，
     冷端的"紫"(90,0,120)偏蓝紫色，跟真正想要的"冷=蓝、热=黄白"对比不够强烈，
     容易把偏暖的手误读成"看不清的蓝紫色"。v2换成7锚点的经典热像仪配色
     (黑->深蓝->品红->红->橙->黄->白)，冷热两端对比更清楚；同时把热图从
     192x144放大到256x192(HM_CELL从6提到8)，标题栏改窄、底部统计行和翻页
     提示合并成一行，腾出空间让热图尽量占满屏幕。

  ⚠ 本项目实际焊的是 MLX90640ESF-BAB（55°x35°窄角），BAA（110°x75°广角）只在
  资料页整理规格，没有实物验证。BAA/BAB 的差别是镜头视场角，芯片本身没法通过
  I2C读出FOV是多少，MODULE_VARIANT_NAME 只是给"传感器信息"页显示用的编译期
  说明文字，换成BAA模块时改这一行就行，代码逻辑完全不用动。

  交互：
    - 单击：翻页（热成像画面 -> 数值统计 -> 传感器信息 -> 原理说明 -> 回热成像画面）
    - 长按2秒：重新初始化传感器（软复位，等效重启整块板子）
*/

#include <SPI.h>
#include <TFT_eSPI.h>
#include <U8g2_for_TFT_eSPI.h>
#include <Wire.h>
#include <Adafruit_MLX90640.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"

#define I2C_SDA 27
#define I2C_SCL 22

#define TOUCH_CS  33
#define TOUCH_IRQ 36

#define HOLD_MS 2000UL

#define SCREEN_W 320
#define SCREEN_H 240

#define COL_BG      TFT_BLACK
#define COL_TEXT    TFT_WHITE
#define COL_DIM     TFT_DARKGREY
#define COL_OK      TFT_GREEN
#define COL_WARN    TFT_RED
#define COL_ACCENT  TFT_YELLOW
#define COL_CYAN    TFT_CYAN

// 本店实际焊的模块型号，只影响信息页显示文字，不影响任何通信逻辑
#define MODULE_VARIANT_NAME "MLX90640ESF-BAB (55x35 窄角，本项目实测型号)"

TFT_eSPI tft = TFT_eSPI();
U8g2_for_TFT_eSPI u8f;
Adafruit_MLX90640 mlx;

// ---------------- 热成像共享数据 ----------------
// sensorTask(core 0)写、loop()(core 1)读，用互斥锁保护，避免主循环被I2C等待卡住。
static SemaphoreHandle_t frameMutex;
static float    frame[32 * 24];
static bool     haveFrame = false;
static float    frameMin = 0, frameMax = 0, frameCenter = 0, frameAmbient = 0;
static float    fps = 0;
static uint32_t frameVersion = 0;     // 每成功拿到一帧+1，主循环靠这个判断"要不要重画"
static uint8_t  sensorFailStreak = 0; // 连续失败次数，用来判定"传感器掉线"

// 热图显示区：8px一格，32x24 -> 256x192，标题栏改窄、底部统计+提示合并成一行，
// 尽量把屏幕让给热图本身（实机反馈v1版192x144"感觉太小"）。
#define HM_CELL 8
#define HM_W (32 * HM_CELL)   // 256
#define HM_H (24 * HM_CELL)   // 192
#define HM_X ((SCREEN_W - HM_W) / 2)  // 32
#define HM_Y 26

// ---------------- 应用状态 ----------------
enum AppState {
  STATE_DETECT,
  STATE_ERROR,
  STATE_THERMAL,   // 热成像画面（主页）
  STATE_STATS,     // 数值统计：最低/最高/中心/环境温度、FPS
  STATE_INFO,      // 传感器信息
  STATE_ABOUT,     // 原理说明：subpage/EEPROM校准
};

static AppState state = STATE_DETECT;

// ---------------- 伪彩色（经典热像仪配色 ironbow v2） ----------------
// 7个锚点：黑 -> 深蓝 -> 品红 -> 红 -> 橙 -> 黄 -> 白，冷端明确是蓝、热端明确是黄白，
// 比v1版(黑->紫->红->橙->白，紫偏蓝紫容易跟"暖但不够热"的目标混在一起看不清)
// 对比度更清楚——手掌这类27~34℃目标应该在橙黄段，跟背景的蓝/品红拉开差距。
static uint16_t heatColor(float t) {
  if (t < 0) t = 0;
  if (t > 1) t = 1;
  static const uint8_t stops[7][3] = {
    {0, 0, 0}, {20, 0, 110}, {140, 0, 130}, {230, 20, 20},
    {250, 140, 0}, {255, 215, 0}, {255, 255, 255}
  };
  float pos = t * 6.0f;          // 0..6之间，对应7个锚点
  int idx = (int)pos;
  if (idx > 5) idx = 5;
  float frac = pos - idx;
  uint8_t r = stops[idx][0] + (uint8_t)((stops[idx + 1][0] - stops[idx][0]) * frac);
  uint8_t g = stops[idx][1] + (uint8_t)((stops[idx + 1][1] - stops[idx][1]) * frac);
  uint8_t b = stops[idx][2] + (uint8_t)((stops[idx + 1][2] - stops[idx][2]) * frac);
  return tft.color565(r, g, b);
}

// ---------------- 触摸：只用IRQ判断"有没有摁下"，不做坐标映射 ----------------
static void touchInit() {
  pinMode(TOUCH_CS, OUTPUT);
  digitalWrite(TOUCH_CS, LOW);
  pinMode(TOUCH_IRQ, INPUT);
}

static bool isTouchedNow() {
  return digitalRead(TOUCH_IRQ) == LOW;
}

// ---------------- 绘制小工具 ----------------
static int cursorY;
static void resetCursor(int y) { cursorY = y; }
static void setPrimaryFont()   { u8f.setFont(u8g2_font_wqy16_t_gb2312); }   // 16px
static void setSecondaryFont() { u8f.setFont(u8g2_font_wqy12_t_gb2312); }   // 12px

static void drawHeader(const char *title, uint16_t color) {
  tft.fillScreen(COL_BG);
  u8f.setForegroundColor(color);
  setPrimaryFont();
  u8f.drawUTF8(12, 26, title);
  tft.drawFastHLine(0, 34, SCREEN_W, COL_DIM);
  resetCursor(56);
}

// 热成像页专用的窄标题栏(12px字体+更靠上的分割线)，比drawHeader省出~18px高度给热图
static void drawThermalHeader(const char *title, uint16_t color) {
  tft.fillScreen(COL_BG);
  u8f.setForegroundColor(color);
  setSecondaryFont();
  u8f.drawUTF8(8, 15, title);
  tft.drawFastHLine(0, 21, SCREEN_W, COL_DIM);
}

// tier: 2=正文(16px)，1=小字提示(12px)
static void printLine(const String &text, uint16_t color, uint8_t tier = 2) {
  u8f.setForegroundColor(color);
  if (tier >= 2) setPrimaryFont(); else setSecondaryFont();
  u8f.drawUTF8(12, cursorY, text.c_str());
  cursorY += (tier >= 2) ? 24 : 18;
}

static void printGap(int px) { cursorY += px; }

static void drawFooterHint(const char *text) {
  u8f.setForegroundColor(COL_DIM);
  setSecondaryFont();
  u8f.drawUTF8(12, SCREEN_H - 8, text);
}

static void drawProgressBar(uint32_t elapsedMs) {
  const int x = 12, y = SCREEN_H - 30, w = SCREEN_W - 24, h = 10;
  uint32_t clamped = elapsedMs > HOLD_MS ? HOLD_MS : elapsedMs;
  int fillW = (int)((uint32_t)w * clamped / HOLD_MS);
  tft.fillRect(x, y, w, h, 0x2104);
  if (fillW > 0) tft.fillRect(x, y, fillW, h, COL_ACCENT);
  tft.drawRect(x, y, w, h, COL_DIM);
}

// 从共享数据里取一份快照，尽量少占用互斥锁的时间(拷贝完立刻释放锁，再慢慢画)
static bool snapshotFrame(float *outFrame, float &lo, float &hi, float &center, float &amb, float &fpsOut) {
  bool ok;
  xSemaphoreTake(frameMutex, portMAX_DELAY);
  ok = haveFrame;
  if (ok) {
    memcpy(outFrame, frame, sizeof(frame));
    lo = frameMin; hi = frameMax; center = frameCenter; amb = frameAmbient; fpsOut = fps;
  }
  xSemaphoreGive(frameMutex);
  return ok;
}

// ---------------- 各页面 ----------------
static void renderDetectPage() {
  drawHeader("检测中...", COL_TEXT);
  printLine("正在查找 MLX90640", COL_TEXT);
}

static void renderErrorPage() {
  drawHeader("未找到传感器", COL_WARN);
  printLine("请检查接线：", COL_TEXT);
  printLine("SDA=IO27  SCL=IO22", COL_TEXT);
  printLine("VIN=3.3V  地址=0x33", COL_TEXT);
  printGap(6);
  printLine("模块自带LDO+上拉，不用外加", COL_DIM, 1);
  drawFooterHint("长按2秒重新扫描");
}

/* 热成像主页：窄标题栏 + 256x192热图（尽量占满屏幕） + 底部一行统计+提示 */
static void renderThermalStatic() {
  drawThermalHeader("热成像画面", COL_CYAN);
}

static void renderThermalValues() {
  static float localFrame[32 * 24];
  float lo, hi, center, amb, fpsNow;

  if (!snapshotFrame(localFrame, lo, hi, center, amb, fpsNow)) {
    u8f.setForegroundColor(COL_DIM);
    setPrimaryFont();
    u8f.drawUTF8(HM_X, HM_Y + HM_H / 2, "等待第一帧数据...");
    return;
  }

  float span = hi - lo;
  if (span < 2.0f) span = 2.0f;

  for (uint8_t r = 0; r < 24; r++) {
    for (uint8_t c = 0; c < 32; c++) {
      float t = localFrame[r * 32 + c];
      float norm = (t - lo) / span;
      uint16_t col = heatColor(norm);
      tft.fillRect(HM_X + c * HM_CELL, HM_Y + r * HM_CELL, HM_CELL, HM_CELL, col);
    }
  }

  char buf[80];
  tft.fillRect(0, HM_Y + HM_H + 2, SCREEN_W, 16, COL_BG);
  u8f.setForegroundColor(COL_TEXT);
  setSecondaryFont();
  snprintf(buf, sizeof(buf), "%.0f~%.0f℃ 中心%.1f℃  轻触翻页·长按扫描", lo, hi, center);
  u8f.drawUTF8(6, HM_Y + HM_H + 14, buf);
}

static void renderStatsPage() {
  drawHeader("数值统计", COL_CYAN);

  static float localFrame[32 * 24];
  float lo, hi, center, amb, fpsNow;
  if (!snapshotFrame(localFrame, lo, hi, center, amb, fpsNow)) {
    printLine("等待第一帧数据...", COL_DIM);
    drawFooterHint("轻触：翻页    长按2秒：重新扫描");
    return;
  }

  char buf[48];
  printLine("最低温度", COL_DIM, 1);
  snprintf(buf, sizeof(buf), "%.1f C", lo);
  tft.setTextColor(COL_CYAN, COL_BG);
  tft.drawString(buf, 12, cursorY, 4);
  cursorY += 34;

  printLine("最高温度", COL_DIM, 1);
  snprintf(buf, sizeof(buf), "%.1f C", hi);
  tft.setTextColor(COL_WARN, COL_BG);
  tft.drawString(buf, 12, cursorY, 4);
  cursorY += 34;

  char line[64];
  snprintf(line, sizeof(line), "中心点 %.1f C    环境 %.1f C    %.1f FPS",
           center, amb, fpsNow);
  u8f.setForegroundColor(COL_TEXT);
  setSecondaryFont();
  u8f.drawUTF8(12, cursorY + 6, line);

  drawFooterHint("轻触：翻页    长按2秒：重新扫描");
}

static void renderInfoPage() {
  drawHeader("传感器信息", COL_OK);
  printLine("型号：" + String(MODULE_VARIANT_NAME), COL_TEXT, 1);
  char sn[24];
  snprintf(sn, sizeof(sn), "%04X%04X%04X",
           mlx.serialNumber[0], mlx.serialNumber[1], mlx.serialNumber[2]);
  printLine("序列号：" + String(sn), COL_TEXT, 1);
  printGap(4);
  printLine("地址 0x33   阵列 32x24(768点)", COL_TEXT, 1);
  printLine("模式 棋盘交错(chess)   刷新率 4Hz", COL_TEXT, 1);
  printGap(4);
  printLine("BAA(110x75广角)本页仅作参数说明", COL_DIM, 1);
  printLine("本机实测型号是BAB(55x35窄角)", COL_DIM, 1);
  drawFooterHint("轻触：翻页    长按2秒：重新扫描");
}

static void renderAboutPage() {
  drawHeader("画面是怎么算出来的？", COL_ACCENT);
  printLine("传感器每次只读半帧(384点)，", COL_TEXT, 1);
  printLine("交错两次(subpage)才拼成一整", COL_TEXT, 1);
  printLine("张768点画面，用的是精度更高", COL_TEXT, 1);
  printLine("的棋盘交错模式，不是行交错。", COL_TEXT, 1);
  printGap(6);
  printLine("原始数据不能直接当温度用：", COL_ACCENT, 1);
  printLine("开机先读一次芯片EEPROM里出厂", COL_TEXT, 1);
  printLine("校准系数，每帧再结合环境温度", COL_TEXT, 1);
  printLine("做一次补偿运算，才是真实摄氏", COL_TEXT, 1);
  printLine("度——这一步库已经封装好了。", COL_TEXT, 1);
  drawFooterHint("轻触：回热成像画面    长按2秒：重新扫描");
}

static void renderCurrentState() {
  switch (state) {
    case STATE_DETECT: renderDetectPage(); break;
    case STATE_ERROR:  renderErrorPage(); break;
    case STATE_THERMAL: renderThermalStatic(); renderThermalValues(); break;
    case STATE_STATS:  renderStatsPage(); break;
    case STATE_INFO:   renderInfoPage(); break;
    case STATE_ABOUT:  renderAboutPage(); break;
  }
}

// ---------------- 触摸事件 -> 状态机 ----------------
static const char *stateName(AppState s) {
  switch (s) {
    case STATE_DETECT: return "DETECT";
    case STATE_ERROR:  return "ERROR";
    case STATE_THERMAL: return "THERMAL";
    case STATE_STATS:  return "STATS";
    case STATE_INFO:   return "INFO";
    case STATE_ABOUT:  return "ABOUT";
  }
  return "?";
}

static void onShortTap() {
  AppState before = state;
  switch (state) {
    case STATE_THERMAL: state = STATE_STATS; renderCurrentState(); break;
    case STATE_STATS:   state = STATE_INFO;  renderCurrentState(); break;
    case STATE_INFO:    state = STATE_ABOUT; renderCurrentState(); break;
    case STATE_ABOUT:   state = STATE_THERMAL; renderCurrentState(); break;
    default: break;   // 检测中/错误页只能长按重试
  }
  Serial.printf("[touch] short tap: %s -> %s\n", stateName(before), stateName(state));
}

static void onLongPressComplete() {
  ESP.restart();
}

// ---------------- 传感器初始化(只在setup()里跑一次，跑完才建task) ----------------
static bool sensorInit() {
  if (!mlx.begin(MLX90640_I2CADDR_DEFAULT, &Wire)) return false;

  mlx.setMode(MLX90640_CHESS);           // 棋盘交错，精度优于行交错
  mlx.setResolution(MLX90640_ADC_18BIT);
  mlx.setRefreshRate(MLX90640_4_HZ);     // 先从4Hz开始，稳定后再考虑调高
  return true;
}

// ---------------- 传感器任务(core 0)：只有这个任务碰Wire/I2C ----------------
// mlx.getFrame()是阻塞调用，放在独立任务里跑，不会影响core 1上loop()的触摸检测。
static void sensorTaskFunc(void *pv) {
  static float localFrame[32 * 24];
  static uint32_t lastFrameMs = 0;

  for (;;) {
    if (mlx.getFrame(localFrame) == 0) {
      float lo = localFrame[0], hi = localFrame[0];
      for (uint16_t i = 1; i < 32 * 24; i++) {
        if (localFrame[i] < lo) lo = localFrame[i];
        if (localFrame[i] > hi) hi = localFrame[i];
      }
      float center = localFrame[12 * 32 + 16];
      float amb = mlx.getTa(false);
      uint32_t now = millis();
      float fpsNow = fps;
      if (lastFrameMs != 0) {
        uint32_t dt = now - lastFrameMs;
        if (dt > 0) fpsNow = 1000.0f / (float)dt;
      }
      lastFrameMs = now;

      xSemaphoreTake(frameMutex, portMAX_DELAY);
      memcpy(frame, localFrame, sizeof(frame));
      frameMin = lo; frameMax = hi; frameCenter = center; frameAmbient = amb;
      fps = fpsNow;
      haveFrame = true;
      sensorFailStreak = 0;
      frameVersion++;
      xSemaphoreGive(frameMutex);
    } else {
      xSemaphoreTake(frameMutex, portMAX_DELAY);
      if (sensorFailStreak < 250) sensorFailStreak++;
      xSemaphoreGive(frameMutex);
    }
    vTaskDelay(pdMS_TO_TICKS(5));   // 让出一点CPU，getFrame()本身已经会等到数据就绪
  }
}

void setup() {
  Serial.begin(115200);
  delay(300);

  tft.init();
  tft.setRotation(1);
  tft.fillScreen(COL_BG);

  u8f.begin(tft);
  u8f.setFontMode(1);       // 透明背景
  u8f.setFontDirection(0);

  touchInit();

  Wire.begin(I2C_SDA, I2C_SCL);
  Wire.setClock(400000);   // 官方支持读帧最高约1MHz，400kHz是稳妥的起点

  renderDetectPage();

  if (!sensorInit()) {
    Serial.println("MLX90640 not found");
    state = STATE_ERROR;
    renderCurrentState();
    return;
  }

  Serial.print("Serial number: ");
  Serial.print(mlx.serialNumber[0], HEX);
  Serial.print(mlx.serialNumber[1], HEX);
  Serial.println(mlx.serialNumber[2], HEX);

  frameMutex = xSemaphoreCreateMutex();
  xTaskCreatePinnedToCore(sensorTaskFunc, "mlxTask", 4096, NULL, 1, NULL, 0);

  state = STATE_THERMAL;
  renderCurrentState();
}

void loop() {
  static uint32_t lastCheck = 0;
  static uint32_t lastPoll = 0;
  static bool wasDown = false;
  static uint32_t pressStartMs = 0;
  static bool longFired = false;
  static uint32_t lastActionMs = 0;
  static uint32_t lastSeenVersion = 0;

  uint32_t now = millis();

  // 只做"要不要重画/要不要判定掉线"的轻量检查，真正读传感器的慢操作在sensorTask里，
  // 不占用这里的时间，所以下面的触摸检测能一直按20ms节奏跑，不会被I2C等待卡住。
  if (state != STATE_ERROR && state != STATE_DETECT && now - lastCheck >= 100) {
    lastCheck = now;
    uint32_t ver;
    uint8_t fails;
    xSemaphoreTake(frameMutex, portMAX_DELAY);
    ver = frameVersion;
    fails = sensorFailStreak;
    xSemaphoreGive(frameMutex);

    if (fails >= 12) {
      state = STATE_ERROR;
      renderCurrentState();
    } else if (ver != lastSeenVersion) {
      lastSeenVersion = ver;
      if (state == STATE_THERMAL) renderThermalValues();
    }
  }

  if (now - lastPoll < 20) return;
  lastPoll = now;

  bool down = isTouchedNow();

  if (down && !wasDown) {
    pressStartMs = now;
    longFired = false;
    Serial.printf("[touch] down at %lu ms\n", (unsigned long)now);
  }

  if (down) {
    uint32_t held = now - pressStartMs;
    if (held > 300) drawProgressBar(held);
    if (!longFired && held >= HOLD_MS) {
      longFired = true;
      lastActionMs = now;
      Serial.println("[touch] long press -> restart");
      onLongPressComplete();
    }
  }

  if (!down && wasDown) {
    uint32_t held = now - pressStartMs;
    Serial.printf("[touch] up at %lu ms, held=%lu ms\n", (unsigned long)now, (unsigned long)held);
    if (!longFired && (now - lastActionMs > 250)) {
      lastActionMs = now;
      onShortTap();
    } else if (!longFired) {
      renderCurrentState();
    }
  }

  wasDown = down;
}