tropicsquare · medexs · Jan 21, 2026 · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/.github/workflows/esp32_build_examples.yml b/.github/workflows/esp32_build_examples.yml
@@ -0,0 +1,33 @@
+name: Build examples for ESP32 boards
+on:
+  push:
+    branches:
+      - 'develop'
+      - 'master'
+  pull_request:
+    branches:
+      - 'master'
+      - 'develop'
+
+jobs:
+  build_examples:
+    name: Build examples for ESP32 boards
+    runs-on: ubuntu-latest
+    container: espressif/idf:v5.5.1
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4.1.7
+
+      - name: Build ESP32-DevKit-V4 examples
+        run: |
+            . /opt/esp/idf/export.sh
+            idf.py -C examples/esp32/ESP32-DevKit-V4/hello_world/ build
+            idf.py -C examples/esp32/ESP32-DevKit-V4/identify_chip/ build
+            idf.py -C examples/esp32/ESP32-DevKit-V4/fw_update/ build
+
+      - name: Build ESP32-S3-DevKitC-1 examples
+        run: |
+            . /opt/esp/idf/export.sh
+            idf.py -C examples/esp32/ESP32-S3-DevKitC-1/hello_world/ build
+            idf.py -C examples/esp32/ESP32-S3-DevKitC-1/identify_chip/ build
+            idf.py -C examples/esp32/ESP32-S3-DevKitC-1/fw_update/ build
diff --git a/docs/get_started/tutorials/esp32/index.md b/docs/get_started/tutorials/esp32/index.md
@@ -0,0 +1,74 @@
+# ESP32 Tutorial
+This tutorial will guide you through the building of the examples in the `examples/esp32/` directory. In this directory, there are multiple subdirectories for each supported ESP32 board. Instructions in this tutorial are common for all of the boards.
+
+## Install Dependencies and Prepare the Repository
+See below for instructions based on your OS.
+
+!!! example "Installation instructions"
+    === ":fontawesome-brands-linux: Linux"
+        1. Setup ESP-IDF and its dependencies:
+            - Complete the first 4 steps in the [official ESP-IDF setup guide](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/linux-macos-setup.html).
+            - We recommend getting the 5.5.1 version, but any 5.x.x version should work.
+        2. Get the Libtropic repository:
+            - Using git: `git clone https://github.com/tropicsquare/libtropic.git`
+            - Or you can download the [latest release](https://github.com/tropicsquare/libtropic/releases/latest).
+
+    === ":fontawesome-brands-apple: macOS"
+        TBA
+
+    === ":fontawesome-brands-windows: Windows"
+        TBA
+
+## Start with our Examples!
+Now, let's build and flash the available examples.
+
+### Build and Run Hello World Example
+!!! example "Building and running the Hello World example"
+    === ":fontawesome-brands-linux: Linux"
+        ```bash
+        cd examples/esp32/<your_board>/hello_world/
+        idf.py build flash monitor
+        ```
+
+    === ":fontawesome-brands-apple: macOS"
+        TBA
+
+    === ":fontawesome-brands-windows: Windows"
+        TBA
+
+After this, you should see a colored output in your terminal.
+
+### Build and Run Chip Identification Example
+!!! example "Building and running the Identify Chip example"
+    === ":fontawesome-brands-linux: Linux"
+        ```bash
+        cd examples/esp32/<your_board>/identify_chip/
+        idf.py build flash monitor
+        ```
+
+    === ":fontawesome-brands-apple: macOS"
+        TBA
+
+    === ":fontawesome-brands-windows: Windows"
+        TBA
+
+After this, you should see a colored output in your terminal.
+
+### Build and Run a Firmware Update Example
+!!! example "Building and running the Firmware Update example"
+    === ":fontawesome-brands-linux: Linux"
+        ```bash
+        cd examples/esp32/<your_board>/fw_update/
+        idf.py build flash monitor
+        ```
+
+    === ":fontawesome-brands-apple: macOS"
+        TBA
+
+    === ":fontawesome-brands-windows: Windows"
+        TBA
+
+After this, you should see a colored output in your terminal.
+
+## FAQ
+If you encounter any issues, please check the [FAQ](../../../faq.md) before filing an issue or reaching out to our [support](https://support.desk.tropicsquare.com/).
diff --git a/docs/get_started/tutorials/index.md b/docs/get_started/tutorials/index.md
@@ -15,4 +15,5 @@ Pick a tutorial based on your host platform and a development kit you want to us
 
 - :fontawesome-brands-linux: Linux
     - [:fontawesome-solid-microchip: Raspberry Pi / Arduino devkit (raw SPI interface)](linux/arduino_rpi_shield.md)
-    - [:fontawesome-brands-usb: USB devkit](linux/usb_devkit.md)
+    - [:fontawesome-brands-usb: USB devkit](linux/usb_devkit.md)
+- [ESP32](esp32/index.md)
diff --git a/docs/other/supported_host_platforms/esp32.md b/docs/other/supported_host_platforms/esp32.md
@@ -0,0 +1,13 @@
+# ESP32
+To support the widest range of Espressif SoCs possible, we provide a HAL directly for the [Espressif IoT Development Framework](https://github.com/espressif/esp-idf) (ESP-IDF). The HAL is available in the `libtropic/hal/esp-idf/` directory.
+
+!!! info "ESP-IDF Version"
+    The ESP-IDF version tested with Libtropic is 5.5.1.
+
+Currently tested ESP32 boards are:
+
+- [ESP32-DevKitC-V4](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitc/user_guide.html)
+- [ESP32-S3-DevKitC-1](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitc-1/index.html)
+
+## Initialization
+If Libtropic's [LT_USE_INT_PIN](../../get_started/integrating_libtropic/how_to_configure/index.md#lt_use_int_pin) CMake option is used, the ESP-IDF HAL will use GPIO interrupts. This puts a requirement on your application — in your code, call the [`gpio_install_isr_service`](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/peripherals/gpio.html#_CPPv424gpio_install_isr_servicei) function with parameter `0` before calling `lt_init`. This function has to be called **exactly once** in your application. See the ESP32 examples in the `examples/esp32/` directory for inspiration.
diff --git a/docs/other/supported_host_platforms/esp_idf.md b/docs/other/supported_host_platforms/esp_idf.md
diff --git a/docs/other/supported_host_platforms/index.md b/docs/other/supported_host_platforms/index.md
@@ -2,9 +2,9 @@
 These are the currently supported host platforms:
 
 - [STM32](stm32.md)
+- [ESP32](esp32.md)
 - [Linux](linux.md)
 - [POSIX](posix.md)
-- [ESP-IDF](esp_idf.md)
 - [Arduino](arduino.md)
 
 All HAL files can be found in the `libtropic/hal/` directory.

diff --git a/examples/esp32/ESP32-DevKit-V4/fw_update/CMakeLists.txt b/examples/esp32/ESP32-DevKit-V4/fw_update/CMakeLists.txt
@@ -0,0 +1,27 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+idf_build_set_property(MINIMAL_BUILD ON)
+project(fw_update)
+
+# Add libtropic top-level project so its 'tropic' target is available to components.
+# Add it after including IDF's project.cmake so IDF toolchain variables are configured.
+set(PATH_LIBTROPIC ${CMAKE_CURRENT_LIST_DIR}/../../../../)
+add_subdirectory(${PATH_LIBTROPIC} ${CMAKE_CURRENT_BINARY_DIR}/libtropic_build)
+
+# Add libtropic's MbedTLS CAL.
+add_subdirectory("${PATH_LIBTROPIC}cal/mbedtls_v4" ${CMAKE_CURRENT_BINARY_DIR}/mbedtls_v4_cal)
+target_sources(tropic PRIVATE ${LT_CAL_SRCS})
+target_include_directories(tropic PUBLIC ${LT_CAL_INC_DIRS})
+
+# Add libtropic's ESP-IDF HAL.
+add_subdirectory("${PATH_LIBTROPIC}hal/esp-idf" ${CMAKE_CURRENT_BINARY_DIR}/esp_idf_hal)
+target_sources(tropic PRIVATE ${LT_HAL_SRCS})
+target_include_directories(tropic PUBLIC ${LT_HAL_INC_DIRS})
+
+# Link IDF components to libtropic's HAL and CAL, because they depend on them.
+target_link_libraries(tropic PUBLIC
+	idf::mbedtls
+	idf::esp_driver_spi
+	idf::esp_driver_gpio
+)
diff --git a/examples/esp32/ESP32-DevKit-V4/fw_update/components/libtropic/CMakeLists.txt b/examples/esp32/ESP32-DevKit-V4/fw_update/components/libtropic/CMakeLists.txt
@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.16)
+
+# Path from this file to the libtropic repo root.
+set(PATH_LIBTROPIC ${CMAKE_CURRENT_LIST_DIR}/../../../../../../)
+
+# Register the libtropic component and list its dependencies.
+idf_component_register(REQUIRES mbedtls esp_driver_spi esp_driver_gpio)
+
+# Link the component library to the 'tropic' target from libtropic.
+target_link_libraries(${COMPONENT_LIB} INTERFACE tropic)
+
diff --git a/examples/esp32/ESP32-DevKit-V4/fw_update/main/CMakeLists.txt b/examples/esp32/ESP32-DevKit-V4/fw_update/main/CMakeLists.txt
@@ -0,0 +1,3 @@
+idf_component_register(SRCS "main.c"
+                       INCLUDE_DIRS "."
+                       REQUIRES mbedtls libtropic)