--- title: "dephy: A Reusable ESP32 Board-Platform Module for Zephyr-Based IoT Products" url: "https://maker.wiznet.io/viktor/projects/dephy-a-reusable-esp32-board-platform-module-for-zephyr-based-iot-products/" markdown_url: "https://maker.wiznet.io/viktor/projects/dephy-a-reusable-esp32-board-platform-module-for-zephyr-based-iot-products/md" type: "UCC: User Created Content" author: "judadao" author_url: "https://github.com/judadao/dephy" editor: "WIZnet" editor_url: "https://maker.wiznet.io/" original_author: "judadao" original_url: "https://github.com/judadao/dephy" published: "2026-07-03" language: "en" likes: 0 views: 143 comments: 1 source: "WIZnet Makers (https://maker.wiznet.io/)" --- # dephy: A Reusable ESP32 Board-Platform Module for Zephyr-Based IoT Products > The dephy project by judadao is a reusable board-profile and Zephyr workspace management module for ESP32-based IoT products Original author: judadao (source: https://github.com/judadao/dephy) ## Article ## Project Introduction The `dephy` project by [judadao](https://github.com/judadao/dephy) is a reusable board-profile and Zephyr workspace management module for ESP32-based IoT products. Rather than duplicating board configuration and workspace setup scripts across every product repository in a fleet, `dephy` centralizes these concerns in a single pinnable module that product repos consume through a `deps.json` dependency declaration. ![](https://maker.wiznet.io/upload/ckeditor5/847158228%5F1783077160%2Epng) The core philosophy is a strict separation of responsibilities: **product code owns application behavior; **`**dephy**`** owns repeatable board profile setup and Zephyr workspace assumptions.** This separation keeps product repos lean and makes board-level changes (a new HAL version, an updated Zephyr module pin) a single-point update that all downstream products inherit on their next sync. The project is particularly well-suited to teams building Ethernet/MQTT field products on ESP32 hardware — devices that need reliable Zephyr networking but do not require POSIX compatibility or verbose runtime logging. The included `product_slim.conf` Kconfig fragment captures exactly this constraint as a reusable configuration primitive. --- ## System Architecture ### Repository Layout ```plaintext dephy/ ├── boards/ │ └── esp32/ │ ├── conf/ │ │ └── product_slim.conf ← Kconfig fragment for field products │ ├── scripts/ │ │ ├── test_profile.sh ← Validates metadata without Zephyr download │ │ └── sync_zephyr_modules.sh ← Workspace init/update with caching │ └── zephyr/ ← Zephyr module metadata for this profile ├── docs/ │ ├── module_structure.md ← Profile structure and tag policy │ └── todo.md / todo.yaml ← Generated TODO tracking ├── AGENTS.md ← Repository guidelines and boundaries └── repo.json ← Module registry metadata ``` ### The Board Profile System [![](https://maker.wiznet.io/upload/ckeditor5/847158228%5F1783077054%2Epng)](https://github.com/judadao/dephy) *Image source: https://github.com/judadao/dephy* A **board profile** in `dephy` is a self-contained directory under `boards/` that bundles everything a product needs to set up a Zephyr build environment for a target hardware family. The current profile is `boards/esp32`, targeting the ESP32 chip family (including ESP32-S3 variants used in WIZnet-integrated field hardware). Each profile contains: - `**conf/**` — Kconfig configuration fragments that product repos apply on top of their own `prj.conf`. `product_slim.conf` disables POSIX, reduces logging overhead, and enables Zephyr networking — the right baseline for an always-on Ethernet field device. - `**scripts/**` — Shell scripts that handle Zephyr workspace initialization, module synchronization, and validation. These are the only scripts a product CI pipeline needs to call. - `**zephyr/**` — Module declarations that tell `west` which HAL and middleware modules to fetch for this board profile. ### Dependency Pinning and Tag Policy Product repositories pin `dephy` at a versioned tag (for example, `dephy-v1.2.0`) in their `deps.json`. This means: - Every developer and CI runner uses the exact same board profile version. - Board-level updates are opt-in: a product repo upgrades by bumping its pin. - Tags are immutable reference points — `dephy` follows a semantic tag policy documented in `docs/module_structure.md`. ### Smart Module Sync with Signature Caching The most operationally significant feature of `dephy` is its module-sync caching mechanism. Running `west update` on a Zephyr workspace is slow — it clones or updates multiple HAL repositories and can take minutes even on fast connections. `sync_zephyr_modules.sh` solves this by computing a **module-list signature** (a hash of the resolved module pins) and comparing it against a cached signature from the last successful sync. If the pins have not changed, the script skips `west update` entirely, making repeated CI runs and local rebuilds fast. The workflow logic: ```plaintext sync_zephyr_modules.sh --check → print resolved workspace/module list (no mutation) sync_zephyr_modules.sh → sync if signature changed; skip if unchanged DEPHY_FORCE_WEST_UPDATE=1 ... → bypass cache and always run west update ``` This three-mode design — check, smart-sync, force — covers all practical scenarios from local development to CI to emergency re-sync without requiring developers to understand Zephyr workspace internals. ### Architecture Flow The full lifecycle from product dependency to compiled firmware: ```plaintext Product deps.json │ ▼ Pin dephy-vX.Y.Z tag │ ▼ boards/esp32 profile ├──► test_profile.sh (validate metadata, no network) └──► sync_zephyr_modules.sh │ ├──► Signature unchanged? → skip west update └──► Signature changed? → west update → cache new signature │ ▼ hal_espressif + required Zephyr modules │ ▼ Product: west build ``` ### Regression Testing `dephy` integrates with an external `dephy_testkit` pytest module for systematic regression testing. Two test modes are supported: - **Smoke tests** — run locally via `test_profile.sh` and `sync_zephyr_modules.sh --check`, validating profile metadata without touching the network. - **Integration tests** — run via `dephy_testkit` with `--profile integration`, exercising the full workspace sync lifecycle. This layered test strategy means profile validation is always fast locally, while deeper workspace integration tests run in CI. --- ## The Role of WIZnet in the dephy Ecosystem While `dephy` itself is a board-profile and workspace management module rather than a driver, it is explicitly designed around the class of hardware that WIZnet enables: **wired-Ethernet ESP32 field products**. ### product_slim.conf and Ethernet Field Devices The `product_slim.conf` Kconfig fragment is the clearest signal of `dephy`'s intended hardware target. It enables Zephyr networking while disabling POSIX compatibility and verbose logging — precisely the configuration profile of a device running an MQTT/TCP stack over a hardwired Ethernet connection, such as an ESP32-based board equipped with a WIZnet W5500 SPI Ethernet chip. For W5500-based ESP32 products (a common combination in industrial IoT and smart building applications), `product_slim.conf` provides a ready-made Kconfig baseline that avoids the common mistake of enabling POSIX overhead or logging backends that are unnecessary and wasteful on a headless field device. ### hal_espressif and W5500 SPI Integration The Zephyr module list managed by `dephy` includes `hal_espressif` — the ESP32 hardware abstraction layer. For products using the W5500 over SPI, `hal_espressif` provides the SPI peripheral drivers that Zephyr's W5500 Ethernet driver sits on top of. By centralizing the HAL version pin in `dephy`, all products in a family share a tested, consistent SPI stack — eliminating subtle driver incompatibilities that can arise when different products drift to different HAL versions. ### Reproducibility for Production Fleets A fleet of identical field devices must run identical firmware. `dephy`'s tag-pinning model and signature-based sync caching together guarantee that every build — whether on a developer laptop, a CI runner, or a factory flashing station — resolves to the exact same set of Zephyr modules. For W5500-based products where the Ethernet driver behavior is sensitive to HAL version, this reproducibility is not a convenience: it is a correctness guarantee. ![](https://maker.wiznet.io/upload/ckeditor5/847158228%5F1783077116%2Epng) --- ## FAQ **Q: What problem does **`**dephy**`** solve that a regular shared Zephyr manifest doesn't?** A standard Zephyr manifest (`west.yml`) requires the entire Zephyr workspace to live in a fixed directory structure alongside every project. `dephy` decouples board profile setup from the product repo's own source tree: a product repo declares `dephy` as a dependency in `deps.json`, runs one script, and gets a validated workspace without needing to own or version any board-level configuration itself. **Q: Can I use **`**dephy**`** with hardware other than ESP32?** The current release contains only a `boards/esp32` profile, but the module's structure is designed for additional board families. Adding a new profile means creating a `boards//` directory following the same pattern — `conf/`, `scripts/`, and `zephyr/` — and publishing a new tag. Product repos for that target then pin the same `dephy` module with a different profile path. **Q: How does **`**dephy**`** handle the case where different products need different Zephyr module sets?** Each board profile under `boards/` owns its own module list in its `zephyr/` subdirectory. A product consuming `boards/esp32` gets the ESP32 module set; a future `boards/rp2040` profile would carry its own. Profile-level isolation means module sets cannot leak across product families. **Q: What does **`**--check**`** mode actually validate?** `sync_zephyr_modules.sh --check` resolves and prints the workspace path, board profile in use, and complete module list with their pinned revisions — without touching the network or the local Zephyr workspace. It is safe to run at any time and is the recommended first step when debugging a dependency mismatch. **Q: How does the signature caching avoid false cache hits?** The signature is computed from the resolved module list — the full set of module names and their pinned revisions — not from a timestamp or file modification date. If any module pin changes (even by one commit SHA), the signature changes, and `west update` runs. The only way to get a cache hit is if the resolved module set is byte-for-byte identical to the last successful sync. **Q: Does **`**dephy**`** work with standard Zephyr CI runners (like GitHub Actions)?** Yes. The scripts are plain POSIX shell with no external tool dependencies beyond `west` and standard Unix utilities. They run identically on macOS, Linux, and any CI runner that has `west` available. The `DEPHY_FORCE_WEST_UPDATE=1` environment variable is provided specifically for CI scenarios where the cache should be bypassed to ensure a clean environment. **Q: What is **`**product_slim.conf**`** and when should I use it?** `product_slim.conf` is a Kconfig fragment designed for headless Ethernet/MQTT field products — devices that run a network stack continuously but have no interactive console or POSIX application layer. It disables verbose logging and POSIX compatibility to reduce flash and RAM footprint. Use it as a base for any ESP32 product that connects via wired Ethernet (such as one using the WIZnet W5500) and communicates over MQTT or TCP without needing a POSIX shell environment. **Q: How is **`**dephy**`** versioned and how should product repos track updates?** `dephy` uses semantic version tags in the format `dephy-vX.Y.Z`. Product repos should pin an exact tag in `deps.json` rather than tracking `master`. When `dephy` publishes a new tag, the product team reviews the changelog and decides whether to bump. This conservative opt-in update model prevents surprise breakage in production firmware builds. --- Source: https://maker.wiznet.io/viktor/projects/dephy-a-reusable-esp32-board-platform-module-for-zephyr-based-iot-products/