Skip to content

Commit 1ca09fb

Browse files
Dunky13Dunky13
committed
Improve tooling workflow and setup documentation
1 parent 709b42d commit 1ca09fb

34 files changed

Lines changed: 2391 additions & 209 deletions

‎.github/workflows/light-firmware-build.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Light Firmware Build
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- ".github/workflows/light-firmware-build.yml"
7+
- "esp-matter/**"
8+
- "tools/**"
9+
- "docs/**"
10+
- "README.md"
11+
- "AGENTS.md"
12+
push:
13+
branches:
14+
- main
15+
tags:
16+
- "v*"
17+
paths:
18+
- ".github/workflows/light-firmware-build.yml"
19+
- "esp-matter/**"
20+
- "tools/**"
21+
- "docs/**"
22+
- "README.md"
23+
- "AGENTS.md"
24+
workflow_dispatch:
25+
26+
jobs:
27+
build-light-core:
28+
runs-on: ubuntu-latest
29+
container:
30+
image: espressif/idf:v5.4
31+
timeout-minutes: 90
32+
33+
env:
34+
BUILD_DIR: build/light-c6-thread
35+
36+
steps:
37+
- name: Checkout repository
38+
uses: actions/checkout@v4
39+
with:
40+
submodules: recursive
41+
fetch-depth: 0
42+
43+
- name: Install esp-matter dependencies
44+
shell: bash
45+
run: |
46+
set -euo pipefail
47+
cd esp-matter
48+
./install.sh --ninja-jobs 2
49+
50+
- name: Build base light firmware
51+
shell: bash
52+
run: |
53+
set -euo pipefail
54+
. /opt/esp/idf/export.sh
55+
. ./esp-matter/export.sh
56+
mkdir -p build/light-c6-thread
57+
cd esp-matter/examples/light
58+
idf.py -B ../../../build/light-c6-thread set-target esp32c6 build
59+
60+
- name: Package build artifacts
61+
shell: bash
62+
run: |
63+
set -euo pipefail
64+
mkdir -p dist/light-core
65+
tar -C build -czf dist/light-core/light-c6-thread-build.tar.gz light-c6-thread
66+
cp docs/ci-and-releases.md dist/light-core/README-device-specific-build.md
67+
68+
- name: Upload build artifact
69+
uses: actions/upload-artifact@v4
70+
with:
71+
name: light-c6-thread-build
72+
path: dist/light-core/*
73+
if-no-files-found: error
74+
75+
- name: Publish GitHub release assets
76+
if: startsWith(github.ref, 'refs/tags/v')
77+
uses: softprops/action-gh-release@v2
78+
with:
79+
files: |
80+
dist/light-core/light-c6-thread-build.tar.gz
81+
dist/light-core/README-device-specific-build.md

‎.github/workflows/python-tools-ci.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Python Tools CI
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- ".github/workflows/python-tools-ci.yml"
7+
- "tools/**"
8+
push:
9+
branches:
10+
- main
11+
paths:
12+
- ".github/workflows/python-tools-ci.yml"
13+
- "tools/**"
14+
workflow_dispatch:
15+
16+
jobs:
17+
tools-tests:
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 15
20+
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
with:
25+
submodules: recursive
26+
27+
- name: Set up Python
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: "3.12"
31+
32+
- name: Install repo-local tool deps
33+
run: |
34+
python3 -m pip install -r tools/requirements-tools.txt
35+
36+
- name: Run Python tool tests
37+
run: |
38+
python3 -m unittest \
39+
tools.tests.test_robustness \
40+
tools.tests.test_fleet_data_duplicates \
41+
tools.tests.test_entrypoints
42+
43+
- name: Smoke direct script entrypoints
44+
run: |
45+
python3 tools/run_workflow.py --help
46+
python3 tools/generate_label_assets.py --help
47+
python3 tools/generate_label_html.py --help
48+
python3 tools/light_pipeline.py --help
49+
50+
- name: Smoke module entrypoints
51+
run: |
52+
python3 -m tools.run_workflow --help
53+
python3 -m tools.generate_label_assets --help
54+
python3 -m tools.generate_label_html --help
55+
python3 -m tools.light_pipeline --help

‎README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# ESP32-C6 Matter Light Pipeline
2+
3+
Build, provision, label, and flash a Thread-only Matter light on ESP32-C6 with one CLI.
4+
5+
Main script: [`tools/light_pipeline.py`](./tools/light_pipeline.py)
6+
7+
Docs index: [`docs/README.md`](./docs/README.md)
8+
9+
## What This Repo Does
10+
11+
This repo adds reproducible automation around upstream [`esp-matter`](./esp-matter) for one target flow:
12+
13+
- firmware source: `esp-matter/examples/light`
14+
- chip target: `esp32c6`
15+
- network mode: Thread enabled, Wi-Fi disabled
16+
- flash layout: 8 MB via [`tools/light_partitions_8mb.csv`](./tools/light_partitions_8mb.csv)
17+
- provisioning model: one manifest row per device with unique pairing data
18+
19+
Result:
20+
21+
1. build firmware
22+
2. generate factory partition
23+
3. generate onboarding codes
24+
4. generate printable labels
25+
5. flash device
26+
27+
## Tested Hardware
28+
29+
Tested on:
30+
31+
- Waveshare [ESP32-C6-Zero](https://www.waveshare.com/esp32-c6-zero.htm)
32+
- Waveshare product page lists it as based on `ESP32-C6FH8`
33+
- 8 MB flash layout used by this repo
34+
35+
## Quick Start
36+
37+
### 1. Install host tools
38+
39+
Install these first:
40+
41+
- Python 3: <https://www.python.org/downloads/>
42+
- Git: <https://git-scm.com/downloads>
43+
- ESP-IDF / EIM: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/> and <https://docs.espressif.com/projects/idf-im-cli/en/latest/>
44+
45+
### 2. Clone and init submodules
46+
47+
```bash
48+
git clone <your-repo-url>
49+
cd esp32-c6-matter
50+
git submodule update --init --recursive
51+
```
52+
53+
### 3. Install upstream ESP-Matter dependencies
54+
55+
```bash
56+
cd esp-matter
57+
./install.sh
58+
cd ..
59+
```
60+
61+
### 4. Generate `eim_config.toml`
62+
63+
Recommended: install ESP-IDF with Espressif Installation Manager (`eim`), then save or export its config as `eim_config.toml` in repo root.
64+
65+
If you do not want full exported config, minimal file also works:
66+
67+
```toml
68+
idf_path = "/Users/<you>/.espressif/v5.5.2/esp-idf"
69+
```
70+
71+
Repo tools read `eim_config.toml` before `IDF_PATH`.
72+
73+
Check detection with:
74+
75+
```bash
76+
python3 tools/detect_env_paths.py
77+
```
78+
79+
### 5. Verify environment
80+
81+
```bash
82+
python3 tools/light_pipeline.py doctor
83+
```
84+
85+
### 6. Build and provision one device
86+
87+
```bash
88+
python3 tools/light_pipeline.py run \
89+
--count 1 \
90+
--vendor-id 0xFFF1 \
91+
--product-id 0x8000 \
92+
--vendor-name "My Vendor" \
93+
--product-name "My Thread Light"
94+
```
95+
96+
### 7. Flash it
97+
98+
```bash
99+
python3 tools/light_pipeline.py flash \
100+
--port /dev/ttyUSB0 \
101+
--serial-index 1
102+
```
103+
104+
Use `--dry-run` first if you want command preview without changing anything.
105+
106+
## Common Commands
107+
108+
Check environment:
109+
110+
```bash
111+
python3 tools/light_pipeline.py doctor
112+
```
113+
114+
Build 8 devices:
115+
116+
```bash
117+
python3 tools/light_pipeline.py run \
118+
--count 8 \
119+
--vendor-id 0xFFF1 \
120+
--product-id 0x8000 \
121+
--vendor-name "My Vendor" \
122+
--product-name "My Thread Light"
123+
```
124+
125+
Build and flash in one go:
126+
127+
```bash
128+
python3 tools/light_pipeline.py run \
129+
--count 1 \
130+
--vendor-id 0xFFF1 \
131+
--product-id 0x8000 \
132+
--vendor-name "My Vendor" \
133+
--product-name "My Thread Light" \
134+
--port /dev/ttyUSB0 \
135+
--serial-index 1
136+
```
137+
138+
List generated devices and detected serial ports:
139+
140+
```bash
141+
python3 tools/light_pipeline.py list
142+
```
143+
144+
## Read Next
145+
146+
- setup and first run: [`docs/getting-started.md`](./docs/getting-started.md)
147+
- pipeline behavior: [`docs/pipeline.md`](./docs/pipeline.md)
148+
- vendor ID, product ID, DAC, PAI, PAA, CD: [`docs/identity-and-attestation.md`](./docs/identity-and-attestation.md)
149+
- commissioning after flash: [`docs/commissioning.md`](./docs/commissioning.md)
150+
- manifest schema: [`docs/manifest.md`](./docs/manifest.md)
151+
- CLI options: [`docs/cli.md`](./docs/cli.md)
152+
- generated outputs: [`docs/outputs.md`](./docs/outputs.md)
153+
- helper scripts: [`docs/internal-scripts.md`](./docs/internal-scripts.md)
154+
- version assumptions: [`docs/version-compatibility.md`](./docs/version-compatibility.md)
155+
- security and generated secrets: [`docs/security-and-generated-secrets.md`](./docs/security-and-generated-secrets.md)
156+
- maintenance and clean rebuilds: [`docs/maintenance.md`](./docs/maintenance.md)
157+
- upstream submodule and patches: [`docs/upstream-and-patches.md`](./docs/upstream-and-patches.md)
158+
- examples: [`docs/examples.md`](./docs/examples.md)
159+
- troubleshooting: [`docs/troubleshooting.md`](./docs/troubleshooting.md)
160+
161+
## Notes
162+
163+
- `tools/device_manifest.csv` is reused if it already exists
164+
- `--count` does not overwrite existing manifest automatically
165+
- `--port` on `run` triggers flashing automatically
166+
- `--flash` is deprecated compatibility flag
167+
- repo is configured around 8 MB flash target

‎docs/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Docs
2+
3+
This folder splits project docs by concept so each page stays short and easy to scan.
4+
5+
## Start Here
6+
7+
- project overview: [`../README.md`](../README.md)
8+
- setup and first run: [`getting-started.md`](./getting-started.md)
9+
10+
## Topics
11+
12+
- hardware and target assumptions: [`hardware.md`](./hardware.md)
13+
- pipeline flow and implementation behavior: [`pipeline.md`](./pipeline.md)
14+
- Matter identity and attestation: [`identity-and-attestation.md`](./identity-and-attestation.md)
15+
- commissioning after flash: [`commissioning.md`](./commissioning.md)
16+
- manifest schema and row fields: [`manifest.md`](./manifest.md)
17+
- CLI commands and options: [`cli.md`](./cli.md)
18+
- generated files and labels: [`outputs.md`](./outputs.md)
19+
- helper scripts: [`internal-scripts.md`](./internal-scripts.md)
20+
- version assumptions: [`version-compatibility.md`](./version-compatibility.md)
21+
- security and generated secrets: [`security-and-generated-secrets.md`](./security-and-generated-secrets.md)
22+
- maintenance and clean rebuilds: [`maintenance.md`](./maintenance.md)
23+
- CI and released build artifacts: [`ci-and-releases.md`](./ci-and-releases.md)
24+
- upstream submodule and repo patches: [`upstream-and-patches.md`](./upstream-and-patches.md)
25+
- sample commands and rows: [`examples.md`](./examples.md)
26+
- troubleshooting: [`troubleshooting.md`](./troubleshooting.md)
27+
28+
## Suggested Reading Order
29+
30+
1. [`getting-started.md`](./getting-started.md)
31+
2. [`hardware.md`](./hardware.md)
32+
3. [`pipeline.md`](./pipeline.md)
33+
4. [`identity-and-attestation.md`](./identity-and-attestation.md)
34+
5. [`commissioning.md`](./commissioning.md)
35+
6. [`manifest.md`](./manifest.md)
36+
7. [`cli.md`](./cli.md)
37+
38+
## Scope
39+
40+
These docs describe repo-local automation in `tools/`.
41+
42+
Upstream SDK source and APIs still live under [`../esp-matter/`](../esp-matter).

0 commit comments

Comments
 (0)