dephy: A Reusable ESP32 Board-Platform Module for Zephyr-Based IoT Products

Project Introduction

The dephy project by judadao 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.

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

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

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:

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:

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.

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/<target>/ 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.