ESP32 Thermal Monitoring Device (via Telegram Messenger)

Project Overview

This repository contains specialized firmware for the Stove Watcher application. It is strictly designed and limited to operate on the tCam-Mini hardware platform (an ESP32 paired with a Lepton 3.1R (radiometric) thermal module).

The use of the radiometric module is mandatory as the safety logic relies on accurate, absolute temperature measurements (e.g., the 80°C threshold) for stove monitoring.

The firmware is an enhancement built directly upon the base tCam-Mini source code. Its primary function is to continuously monitor a kitchen cooktop or stove for safety purposes.

The device identifies when the stove is running hot and, crucially, triggers an immediate alarm and sends a Telegram alert (with an image snapshot) if the stove remains hot and unattended for a predefined period (e.g., 5 minutes).

If the device encounters a critical network failure while trying to send an alert, it executes a hard reboot (esp_restart()) to attempt to restore a stable connection environment.

Credit and Scope Limitation (tCam-Mini)

This project is a small, specialized functional layer built on the incredible work done by Dan Julio on the tCam-Mini firmware and hardware.

Crucially, all original tCam-Mini functionality remains fully intact and untouched. This includes:

• Standard Wi-Fi management and connection setup.
• Full compatibility with the tCam-Mini mobile or desktop applications for configuration and remote viewing.
• The fundamental camera initialization and radiometric data handling, which requires the Lepton 3.1R (radiometric) module.

This repository changes are supplementary: they run alongside the original firmware's capabilities, adding a dedicated, real-time safety monitor (the Stove Watcher logic) on top of the existing platform.

tCam-Mini Project Link:
https://danjuliodesigns.com/products/tcam_mini.html

Telegram Bot & Configuration (Required for Alerts)

To receive real-time alerts with thermal images, you must create a Telegram bot and obtain two values that go into stove_monitor.h.

Step 1: Create Your Telegram Bot

1. Open Telegram and message @BotFather
2. Send the command: /newbot
3. Choose a name (e.g., "Stove Watcher") and a username ending in bot (e.g., @my_stove_watcher_bot)
4. BotFather will reply with your Bot Token, for example:
   123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   → Copy this entire token. This is your TELEGRAM_BOT_TOKEN.

Step 2: Get Your Chat ID

Fastest method:

1. Open your new bot in Telegram (e.g., https://t.me/my_stove_watcher_bot) and tap Start
2. Open this URL in any browser (replace YOUR_TOKEN with your real token):
   https://api.telegram.org/botYOUR_TOKEN/getUpdates
3. Look for a line containing "chat":{"id": — the number after it is your Chat ID (e.g., 987654321)

Alternative: Message @userinfobot — it instantly replies with your personal Chat ID.

Step 3: Configure stove_monitor.h

Edit stove_monitor.h and replace the placeholders:

#define TELEGRAM_BOT_TOKEN      "123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
#define TELEGRAM_CHAT_ID        "987654321"        // ← Must be a string in quotes!
#define TELEGRAM_QUEUE_SIZE     10
#define TELEGRAM_MAX_MSG_LEN    512

Important:

• TELEGRAM_CHAT_ID must be in quotes (string), not a plain number.
• Never commit your real token or chat ID to a public repository.
• Keep stove_monitor.h in .gitignore or store credentials privately.

Optional: Send Alerts to a Telegram Channel

1. Create a public or private channel
2. Add your bot as an Administrator
3. Channel Chat IDs always start with -100 (e.g., -1001234567890)
   → Use this as TELEGRAM_CHAT_ID if you prefer channel alerts.

Once configured, your device will automatically send:

• Device online message at boot
• "Stove is ON" notifications
• Critical unattended alarm with live thermal image
• "Stove is OFF" confirmation

Added Features and Monitoring Logic

The core changes transform the tCam-Mini's frame processing loop into a state machine for appliance monitoring.

1. State Management and Timers

The stove_monitor.c logic now manages two primary states:

• is_stove_hot (Stove ON): Set when the maximum measured temperature exceeds TEMP_STOVE_ON (default: 80°C).
• Cooldown Hysteresis: When the temperature drops below TEMP_STOVE_ON, a 5-minute cooling timer starts. Only after this timer expires is the stove confirmed as OFF/COOL, preventing rapid state toggling.

2. Unattended Safety Timer

• Human Presence Detection: We rely on thermal motion detection within the human temperature range (TEMP_HUMAN_MIN to TEMP_HUMAN_MAX). If enough pixels in this range move between frames (MOVING_PIXEL_THRESHOLD / MOTION_TEMP_DIFFERENCE), a human is considered present.
• Timer Reset: The last_human_seen_time is updated whenever motion is detected. Crucially, when the stove transitions to the HOT state, the unattended timer is reset to zero to ensure the countdown starts fresh for the current cooking session.
• Alarm Trigger: If is_stove_hot is true, no human is detected, and the unattended time exceeds HUMAN_TIMEOUT_MS (default: 5 minutes), the alarm sequence is triggered.

3. Critical Alert System (Telegram Integration)

Instead of relying on local alerts only, the device sends external notifications:

• Alert Types:
  • Startup: "Device Online" message.
  • Stove ON: "Cooktop is on" message when the hot state is entered.
  • Unattended Alarm: "Cooktop is unattended while hot!" message.
  • Stove OFF: "Cooktop is cool" message when the 5-minute cooldown is complete.
• Image Attachment: All critical alerts are sent as photo messages, including a thermal snapshot (JPEG) of the scene at the moment of the event.

4. Robust Failure Handling (Network Reboot)

This is a critical safety feature:

• Logic: The telegram_send_task handles all outgoing alerts. If the underlying HTTP client (esp_http_client_perform) returns any network or connection-related error (e.g., ESP_ERR_HTTP_CONNECT, ESP_ERR_TCP_TRANSPORT_CONNECT), it signals a critical communication failure.
• Action: Instead of retrying indefinitely, the device immediately logs the error and executes esp_restart(). The device will attempt a clean boot and re-establish Wi-Fi/NTP/Telegram connection to ensure future alerts can be delivered.

Detailed Monitoring Logic and Camera Setup

The monitoring system works based on two independent, co-operating processes: Stove State Monitoring and Human Presence Detection.

The camera must be aimed at both the cooktop surface and the immediate area in front of the stove (where a person would stand) to ensure both systems work correctly.

A. Stove State Monitoring (Hot/Cool) Constants

Constant	Value	Role in Logic
TEMP_STOVE_ON	80.0f C	Threshold for stove ON
STOVE_COOLING_CONFIRM_MS	5 minutes	Hysteresis before OFF
COOLING_DROP_THRESHOLD	10.0f C	Suppress alarm if cooling fast

B. Human Presence Detection (Motion) Constants

Constant	Value	Role in Logic
TEMP_HUMAN_MIN	25.0f C	Lower human temp bound
TEMP_HUMAN_MAX	38.0f C	Upper human temp bound
MOTION_TEMP_DIFFERENCE	150 (1.5°C)	Minimum change for motion
MOVING_PIXEL_THRESHOLD	25 pixels	Minimum moving pixels to confirm presence

C. Alarm Triggering Constants

Constant	Value	Role in Logic
HUMAN_TIMEOUT_MS	5 minutes	Max unattended time when hot
ALARM_INTERVAL_MS	30 seconds	Delay between repeated alarms
BUZZER_PIN	GPIO_NUM_33	Buzzer output pin

D. Image Generation (Automatic Gain Control - AGC)

The visual snapshot sent via Telegram is processed using Automatic Gain Control (AGC). Instead of using fixed minimum and maximum temperatures, the algorithm scans the current frame for the actual coldest and hottest spots. It then scales the entire 0-255 grayscale range (White to Black) to perfectly fit this dynamic range, ensuring the resulting image provides the best possible visual contrast for the current scene. The image is also rotated based on the IMAGE_ROTATION setting for correct orientation.

Technical Modifications (C Code Changes)

File	Change Summary
stove_monitor.h	Defined Telegram token, Chat ID, Queue Size, and constants
stove_monitor.c	Implemented stove state machine, human motion detection, timers, JPEG generation, and queue-based Telegram sending
telegram_send_task	Dedicated task with network failure → reboot logic
perform_telegram_http_call	Supports text and multipart photo uploads
queue_telegram_message	Non-blocking with with_image flag

sdkconfig Component Changes

Configuration	Why the Change?
CONFIG_ESP_HTTP_CLIENT_ENABLE	Required for HTTPS to Telegram
CONFIG_ESP_TLS_INSECURE + skip_cert_common_name_check	Skips certificate verification
Increased task stack (8192+) for telegram task	TLS + image buffering
CONFIG_SNTP_ENABLED	Correct time for TLS
CONFIG_SPIRAM_USE	Large buffers in external RAM (recommended)

ESP-IDF Version & Compatibility

This firmware is developed and tested exclusively with:

• ESP-IDF v4.4.4 (the exact version used by the official tCam-Mini firmware)
• ESP32-WROVER with 8 MB PSRAM (standard on tCam-Mini)

I am intentionally stay on v4.4.4 to remain 100% compatible with the original tCam-Mini build system and tools.

How to Build, Flash and Monitor

Prerequisites

• ESP-IDF v4.4.4 installed and sourced
  (https://docs.espressif.com/projects/esp-idf/en/v4.4.4/esp32/get-started/index.html)
• USB-UART cable connected to tCam-Mini

Commands

# Clone the project
git clone git@github.com:manusovich/tCam-StoveWatcher.git
cd tCam-StoveWatcher

# Set target
idf.py set-target esp32

# Optional: tweak settings
idf.py menuconfig

# Build + flash + monitor (recommended)
idf.py -p /dev/ttyUSB0 build flash monitor

# Or separately:
idf.py build
idf.py -p /dev/ttyUSB0 flash
idf.py -p /dev/ttyUSB0 monitor

You should see something like:

I (xxxx) STOVE_MONITOR: Stove Monitor Initialized. Motion buffer allocated in PSRAM.
I (xxxx) STOVE_MONITOR: NTP SUCCESS! Time: 2025-...
I (xxxx) STOVE_MONITOR: Telegram message sent. Status = 200
*[Device Start]* Stove Monitor Device Online (Time Synced)!