Skip to content

Commit e32fd10

Browse files
hacker-cbhacker-cb
committed
Add ESP-IDF development image and workflow
- Introduced a new Docker image for ESP-IDF 5.4.1, including QEMU support and comprehensive testing tools. - Created a GitHub Actions workflow for building the ESP-IDF Docker image, allowing for automated builds on push and pull request events. - Updated README with detailed usage instructions, supported chips, and quick start guide for the ESP-IDF image. - Added Dockerfile for the ESP-IDF image, including necessary dependencies and configuration for testing and code quality tools.
1 parent 66644d3 commit e32fd10

File tree

4 files changed

+594
-9
lines changed

4 files changed

+594
-9
lines changed

‎.github/workflows/esp-idf.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# ESP-IDF Docker Build Workflow
2+
name: 🐳 ESP-IDF Docker Image
3+
4+
env:
5+
ESP_IDF_VERSION: v5.4.1
6+
7+
on:
8+
push:
9+
branches: [master, dev]
10+
paths:
11+
- '.github/workflows/esp-idf.yml'
12+
- '.github/workflows/reusable-docker-build.yml'
13+
- 'images/esp-idf/**'
14+
pull_request:
15+
branches: [master, dev]
16+
paths:
17+
- '.github/workflows/esp-idf.yml'
18+
- '.github/workflows/reusable-docker-build.yml'
19+
- 'images/esp-idf/**'
20+
# Manual trigger
21+
workflow_dispatch:
22+
inputs:
23+
esp_idf_version:
24+
description: 'ESP-IDF version (e.g., v5.4.1, v5.3.1)'
25+
required: false
26+
default: 'v5.4.1'
27+
type: string
28+
force_rebuild:
29+
description: 'Force rebuild without cache'
30+
required: false
31+
default: false
32+
type: boolean
33+
custom_tags:
34+
description: 'Additional custom tags (comma-separated, optional)'
35+
required: false
36+
default: ''
37+
type: string
38+
39+
jobs:
40+
prepare:
41+
runs-on: ubuntu-latest
42+
outputs:
43+
esp_idf_version: ${{ steps.prepare.outputs.esp_idf_version }}
44+
custom_tags: ${{ steps.prepare.outputs.custom_tags }}
45+
steps:
46+
- name: 🏷️ Prepare ESP-IDF version and tags
47+
id: prepare
48+
run: |
49+
ESP_IDF_VERSION="${{ github.event.inputs.esp_idf_version || env.ESP_IDF_VERSION }}"
50+
CUSTOM_TAGS="${{ github.event.inputs.custom_tags || '' }}"
51+
52+
# Add ESP-IDF version tag
53+
if [ -n "$CUSTOM_TAGS" ]; then
54+
TAGS="${CUSTOM_TAGS},${ESP_IDF_VERSION}"
55+
else
56+
TAGS="${ESP_IDF_VERSION}"
57+
fi
58+
59+
echo "esp_idf_version=${ESP_IDF_VERSION}" >> $GITHUB_OUTPUT
60+
echo "custom_tags=${TAGS}" >> $GITHUB_OUTPUT
61+
62+
build:
63+
needs: prepare
64+
uses: ./.github/workflows/reusable-docker-build.yml
65+
permissions:
66+
contents: read
67+
packages: write
68+
id-token: write
69+
with:
70+
image_name: jethome-dev-esp-idf
71+
context_path: images/esp-idf
72+
force_rebuild: ${{ github.event.inputs.force_rebuild || false }}
73+
custom_tags: ${{ needs.prepare.outputs.custom_tags }}
74+
build_args: |
75+
ESP_IDF_VERSION=${{ needs.prepare.outputs.esp_idf_version }}
76+

‎README.md‎

Lines changed: 36 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,33 +6,56 @@ Docker-based development environment for embedded systems, providing containeriz
66

77
| Image | Description | Documentation |
88
|-------|-------------|---------------|
9+
| [esp-idf](./images/esp-idf/) | ESP-IDF 5.4.1 with QEMU, pytest, and testing tools for all ESP32 chips | [README](./images/esp-idf/README.md) |
910
| [platformio](./images/platformio/) | PlatformIO with ESP32 (all variants) + ESP-IDF + Unity testing | [README](./images/platformio/README.md) |
1011

1112
## Quick Start
1213

13-
Pull the image:
14+
### ESP-IDF
1415

1516
```bash
16-
docker pull ghcr.io/jethome-iot/jethome-dev-platformio:latest
17+
# Pull image
18+
docker pull ghcr.io/jethome-iot/jethome-dev-esp-idf:latest
19+
20+
# Build project
21+
docker run --rm -v $(pwd):/workspace \
22+
ghcr.io/jethome-iot/jethome-dev-esp-idf:latest \
23+
idf.py build
24+
25+
# Interactive development
26+
docker run -it --rm -v $(pwd):/workspace \
27+
ghcr.io/jethome-iot/jethome-dev-esp-idf:latest
1728
```
1829

19-
Build your PlatformIO project:
30+
### PlatformIO
2031

2132
```bash
33+
# Pull image
34+
docker pull ghcr.io/jethome-iot/jethome-dev-platformio:latest
35+
36+
# Build project
2237
docker run --rm -v $(pwd):/workspace \
2338
ghcr.io/jethome-iot/jethome-dev-platformio:latest \
2439
pio run
25-
```
26-
27-
Interactive development:
2840

29-
```bash
41+
# Interactive development
3042
docker run -it --rm -v $(pwd):/workspace \
3143
ghcr.io/jethome-iot/jethome-dev-platformio:latest
3244
```
3345

3446
## What's Included
3547

48+
### ESP-IDF Image
49+
50+
- **Base**: espressif/idf:v5.4.1 (Ubuntu 24.04 LTS)
51+
- **ESP-IDF**: 5.4.1 with all ESP32 toolchains
52+
- **QEMU**: Xtensa and RISC-V emulation support
53+
- **Supported Chips**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4
54+
- **Testing**: pytest, pytest-embedded, gcovr, lcov
55+
- **Code Quality**: pylint, flake8, black, clang-format, clang-tidy
56+
- **Documentation**: Sphinx, sphinx-rtd-theme
57+
- **Tools**: jq, vim, nano, rsync, git
58+
3659
### PlatformIO Image
3760

3861
- **Base**: Python 3.11 slim (Debian Bookworm)
@@ -56,6 +79,9 @@ docker build -t jethome-dev-platformio .
5679
```
5780
jethome-dev/
5881
├── images/
82+
│ ├── esp-idf/ # ESP-IDF 5.4.1 development image
83+
│ │ ├── Dockerfile # Image definition
84+
│ │ └── README.md # Detailed documentation
5985
│ └── platformio/ # PlatformIO development image
6086
│ ├── Dockerfile # Image definition
6187
│ ├── README.md # Detailed documentation
@@ -66,8 +92,9 @@ jethome-dev/
6692

6793
## Registry
6894

69-
Images are published to:
70-
- **GHCR**: `ghcr.io/jethome-iot/jethome-dev-platformio`
95+
Images are published to GitHub Container Registry (GHCR):
96+
- **ESP-IDF**: `ghcr.io/jethome-iot/jethome-dev-esp-idf`
97+
- **PlatformIO**: `ghcr.io/jethome-iot/jethome-dev-platformio`
7198

7299
## Use Cases
73100

‎images/esp-idf/Dockerfile‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# ESP-IDF Development Image
2+
# Build arguments for version pinning
3+
ARG ESP_IDF_VERSION=v5.4.1
4+
ARG QEMU_RELEASE_TAG=esp-develop-9.0.0-20240606
5+
ARG QEMU_VERSION=esp_develop_9.0.0_20240606
6+
7+
FROM espressif/idf:${ESP_IDF_VERSION}
8+
9+
# Install additional system packages
10+
RUN apt-get update && apt-get install -y \
11+
# JSON processor
12+
jq \
13+
# Code coverage tools
14+
lcov \
15+
gcovr \
16+
# Build acceleration
17+
ccache \
18+
# Additional useful tools
19+
clang-format \
20+
clang-tidy \
21+
vim \
22+
nano \
23+
rsync \
24+
# QEMU dependencies
25+
libglib2.0-0 \
26+
libpixman-1-0 \
27+
libslirp0 \
28+
# Clean up
29+
&& apt-get clean \
30+
&& rm -rf /var/lib/apt/lists/*
31+
32+
# Configure ccache for multi-user environment
33+
# Create ccache directory that's writable by any user
34+
RUN mkdir -p /opt/ccache && \
35+
chmod 1777 /opt/ccache
36+
37+
# Set default ccache configuration
38+
ENV CCACHE_DIR=/opt/ccache \
39+
CCACHE_MAXSIZE=2G \
40+
CCACHE_COMPRESS=1 \
41+
CCACHE_COMPRESSLEVEL=6
42+
43+
# Install ESP32 QEMU (detect architecture)
44+
# Re-declare ARGs after FROM to make them available in this stage
45+
ARG QEMU_RELEASE_TAG
46+
ARG QEMU_VERSION
47+
RUN ARCH=$(uname -m) && \
48+
if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then \
49+
QEMU_ARCH="aarch64-linux-gnu"; \
50+
else \
51+
QEMU_ARCH="x86_64-linux-gnu"; \
52+
fi && \
53+
cd /tmp && \
54+
wget -q https://github.com/espressif/qemu/releases/download/${QEMU_RELEASE_TAG}/qemu-xtensa-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz && \
55+
tar -xf qemu-xtensa-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz && \
56+
mv qemu /opt/qemu-xtensa && \
57+
rm qemu-xtensa-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz && \
58+
wget -q https://github.com/espressif/qemu/releases/download/${QEMU_RELEASE_TAG}/qemu-riscv32-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz && \
59+
tar -xf qemu-riscv32-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz && \
60+
mv qemu /opt/qemu-riscv32 && \
61+
rm qemu-riscv32-softmmu-${QEMU_VERSION}-${QEMU_ARCH}.tar.xz
62+
63+
# Add QEMU to PATH
64+
ENV PATH="/opt/qemu-xtensa/bin:/opt/qemu-riscv32/bin:${PATH}"
65+
66+
# Install Python testing and development packages
67+
# Use IDF_PATH to find the ESP-IDF Python environment
68+
# Let pip resolve compatible versions automatically to avoid dependency conflicts
69+
RUN bash -c '. ${IDF_PATH}/export.sh && pip install --no-cache-dir \
70+
# Testing frameworks - let pip resolve compatible versions
71+
pytest \
72+
pytest-embedded-serial-esp \
73+
pytest-embedded-idf \
74+
pytest-embedded-qemu \
75+
pytest-timeout \
76+
pytest-cov \
77+
# Code coverage
78+
gcovr \
79+
# Code quality
80+
pylint \
81+
flake8 \
82+
black \
83+
# Documentation
84+
sphinx \
85+
sphinx-rtd-theme \
86+
# Utilities (these are already in ESP-IDF venv but may need updates)
87+
pyserial \
88+
requests \
89+
pyyaml'
90+
91+
# Set working directory
92+
WORKDIR /workspace
93+
94+
# Verify installation
95+
ARG ESP_IDF_VERSION
96+
RUN bash -c '. ${IDF_PATH}/export.sh && \
97+
python3 --version && \
98+
pytest --version && \
99+
jq --version && \
100+
qemu-system-xtensa --version && \
101+
qemu-system-riscv32 --version && \
102+
gcovr --version && \
103+
ccache --version && \
104+
echo "ESP-IDF ${ESP_IDF_VERSION} installation verified successfully"'
105+
106+
CMD ["/bin/bash"]
107+

0 commit comments

Comments
 (0)