ESP32-Lepton

High-performance ESP-IDF driver for FLIR Lepton 3.5 thermal imaging cameras.

Table of Contents

• ESP32-Lepton
  • Table of Contents
  • Features
  • Hardware Support
  • Requirements
  • Installation
    • Using ESP-IDF Component Manager
    • Manual Installation
  • Supported commands
  • Documentation
    • Requirements
    • Structure
    • Format
    • Style Guide
    • Building Locally
      • Build HTML Documentation
      • Build PDF Documentation
      • Build All Documentation
    • Automated CI/CD
    • Accessing Built Documentation
    • Module Overview
      • lepton.adoc
      • lepton_capture.adoc
      • lepton_cci.adoc
      • cci.adoc
      • vospi.adoc
  • Kconfig Options
  • Color Palettes
  • Performance
  • Examples
  • License
  • Maintainer

Features

• Full support for Lepton 3.5 (160x120 resolution)
• VoSPI (Video over SPI) high-speed frame capture
• CCI (Command & Control Interface) via I2C
• AGC (Automatic Gain Control) support
• FFC (Flat Field Correction) control
• Radiometry support (temperature measurement)
• Multiple color palettes (Iron, Rainbow, Whitehot, Blackhot, Amber, Arctic, Lava)

Hardware Support

Camera Model	Resolution	Status
Lepton 3.0	160x120	⚠️ Not tested
Lepton 3.5	160x120	✅ Tested
Lepton 2.x	80x60	⚠️ Not tested

Tested ESP32 Platforms:

• ESP32-S3 (Recommended)
• ESP32 (Should work, not extensively tested)

Requirements

• ESP-IDF: v5.1 or newer
• Hardware:
  • ESP32 or ESP32-S3 module
  • FLIR Lepton 3.x camera module
  • SPI interface (3-wire or 4-wire)
  • I2C interface for CCI
  • Adequate power supply (≥150mA @ 3.3V for Lepton)

Installation

Using ESP-IDF Component Manager

Add to your main/idf_component.yml:

dependencies:
  esp32-lepton:
    git: https://github.com/Kampi/ESP32-Lepton.git

Manual Installation

• Clone into your project's components directory:

cd your_project/components
git clone https://github.com/Kampi/ESP32-Lepton.git

Supported commands

See CCI API Status.

Documentation

Requirements

# Ubuntu/Debian
sudo apt-get install asciidoctor ruby-asciidoctor-pdf

# macOS
brew install asciidoctor

# Or via Ruby gems
gem install asciidoctor asciidoctor-pdf

Structure

The documentation is organized into separate modules:

• index.adoc - Main overview and getting started guide
• lepton.adoc - Main driver API documentation
• lepton_capture.adoc - Frame capture task implementation
• lepton_cci.adoc - High-level CCI commands
• cci.adoc - Low-level CCI protocol implementation
• vospi.adoc - VoSPI (Video over SPI) interface

Format

The documentation uses AsciiDoc format, which provides:

• Rich formatting capabilities
• Code syntax highlighting
• Cross-references between documents
• Professional PDF output
• Easy-to-read source format

Style Guide

• Use clear, concise language
• Include code examples for all API functions
• Add usage examples for complex features
• Document error conditions and return values
• Cross-reference related modules using link:module.html[Module Name]

Building Locally

Build HTML Documentation

cd docs
asciidoctor index.adoc -o index.html
asciidoctor lepton.adoc -o lepton.html
asciidoctor lepton_capture.adoc -o lepton_capture.html
asciidoctor lepton_cci.adoc -o lepton_cci.html
asciidoctor cci.adoc -o cci.html
asciidoctor vospi.adoc -o vospi.html

Build PDF Documentation

cd docs
asciidoctor-pdf index.adoc -o index.pdf
asciidoctor-pdf lepton.adoc -o lepton.pdf
asciidoctor-pdf lepton_capture.adoc -o lepton_capture.pdf
asciidoctor-pdf lepton_cci.adoc -o lepton_cci.pdf
asciidoctor-pdf cci.adoc -o cci.pdf
asciidoctor-pdf vospi.adoc -o vospi.pdf

Build All Documentation

cd docs
for adoc in *.adoc; do
  asciidoctor "$adoc" -o "${adoc%.adoc}.html"
  asciidoctor-pdf "$adoc" -o "${adoc%.adoc}.pdf"
done

Automated CI/CD

The documentation is automatically built and deployed via GitHub Actions:

• Trigger: Push to main/master branch or changes in docs/ directory
• Output: HTML and PDF versions
• Artifacts: Uploaded as GitHub Actions artifacts
• Releases: Nightly documentation releases with tarball and individual PDFs

Accessing Built Documentation

• Artifacts: Download from GitHub Actions run
• Releases: Check the "nightly" pre-release for latest documentation
• Tarball: ESP32-Lepton-Docs-nightly.tar.gz contains all HTML files
• Individual PDFs: Available in releases (e.g., lepton-nightly.pdf)

Module Overview

lepton.adoc

Core driver interface with initialization, configuration, and high-level control functions. This is the main entry point for users of the component.

lepton_capture.adoc

Describes the FreeRTOS task that continuously captures thermal frames from the sensor. Includes VSync interrupt handling and frame buffer management.

lepton_cci.adoc

High-level CCI commands for sensor configuration (AGC, emissivity, ROI, telemetry, etc.). Wraps low-level CCI functions with device state management.

cci.adoc

Low-level I2C protocol implementation for the Lepton CCI interface. Handles command execution, register access, and status polling.

vospi.adoc

SPI-based video interface for high-speed thermal data acquisition. Implements packet synchronization, frame assembly, and DMA transfers.

Kconfig Options

Configure via idf.py menuconfig:

Component config → ESP32-Lepton

Color Palettes

Built-in palettes for thermal visualization:

Palette	Description	Use Case
Iron	Black → Red → Yellow → White	General thermal imaging
Rainbow	Full spectrum blue → cyan → green → yellow → red	High contrast visualization
Whitehot	Black → Gray → White (cold to hot)	Standard grayscale imaging
Blackhot	White → Gray → Black (cold to hot)	Inverted grayscale imaging
Amber	Black → Brown → Orange → Yellow → White	Night vision / security
Arctic	Dark blue → Cyan → White	Cold-scene visualization
Lava	Black → Purple → Red → Orange → Yellow	Volcanic / high-temp imaging

Performance

Typical Frame Rates:

• Lepton 3.5: ~8.6 Hz (native)
• ESP32-S3 @ 240 MHz: ~9 Hz capture + RGB conversion

Examples

See the examples/ directory:

• basic_init: Basic initialization of the Lepton camera
• basic_capture: Basic capture example

License

This project is licensed under the GNU General Public License v3.0.

See LICENSE for full text.

Maintainer

Daniel Kampert
📧 DanielKampert@kampis-elektroecke.de
🌐 www.kampis-elektroecke.de

---

Contributions Welcome! Please open issues or pull requests on GitHub.