Skip to main content

ZephyrForge Python Host

USB HID control, diagnostics, and a local dashboard for ZephyrForge firmware on the ESP32-S3-DevKitC. The host talks to the board's native USB HID interface (VID:PID 0xCAFE:0x4021) using the USB HID contract. Basic monitoring needs no SD card. Wireless controls depend on the connected firmware's capabilities.

Python and .NET share the frontend in host/web/src. Direct owns its separate frontend and standalone server; its release reuses the standard-library console relay without depending on the Python package. See the Direct independence policy. This Python host connects over USB HID, not the USB-UART bridge or Bluetooth LE. Wireless status uses Report 12 and all writes use the unified Report 20 channel. The dashboard preserves the saved Wi-Fi and BLE switches from Report 2 and supports staged credentials, connection tests, and scans. Opaque scan SSIDs include ssid_hex beside an escaped display name; test/save requests may send that hex value to preserve the network bytes. Saving a tested pair reuses its staging without resending either credential.

Install

Use Python 3.10 or newer in a virtual environment:

python -m venv .venv

Activate it with source .venv/bin/activate on Linux/macOS or .venv\Scripts\Activate.ps1 in Windows PowerShell, then:

python -m pip install zephyrforge
zephyrforge web

Open http://127.0.0.1:8001/. The wheel includes the dashboard assets; Node.js and .NET are not required. Runtime dependencies are Flask and HIDAPI, pinned in pyproject.toml. Native HID access still requires the operating system's usual libraries, drivers, and permissions. Hatchling and hatch-vcs derive package versions from vMAJOR.MINOR.PATCH Git tags, with development versions between tags. The dashboard displays the installed zephyrforge distribution version, matching pip show zephyrforge, for both wheels and editable installs. Uninstalled source checkouts report 0.0.0-debug.

Wheels are attached to GitHub Releases and published to PyPI after release setup; downloads may be unavailable before then. For firmware build and flashing, start with Getting Started.

Run from a source checkout

For an explicit development installation in your active environment, from the repository root:

python -m pip install --editable host/python
zephyrforge web

Reinstall the editable package after changing commits or tags to refresh its installed version metadata. Alternatively, bash tools/host/run-python.sh web refreshes the editable installation on every launch, so its dashboard version matches the package metadata for the current checkout. The script reuses its virtual environment; if installation fails, it does not start the host with stale metadata. Stop an already-running host before relaunching.

Source-checkout launches need no asset copy. Building a wheel or source distribution requires explicit asset staging first; there is no custom build hook.

Commands

zephyrforge web
zephyrforge web --port 8011
zephyrforge status
zephyrforge status --serial SERIAL
zephyrforge reboot --serial SERIAL --confirm
python -m zephyrforge --help

status prints JSON diagnostics from the reports received within a five-second collection window; unavailable fields remain null. It includes self-test status when the board advertises that capability, without extending the collection window. reboot requires explicit confirmation and uses the board's saved settings. All three commands accept either --serial SERIAL or --device-path PATH to select a board. The server always binds to 127.0.0.1. Python and .NET default to ports 8001 and 8002.

Use Rescan and the dashboard's board selector to switch between attached boards. Run only one HID host connection per board; separate host processes can conflict for access.

On Linux, grant your user access to the HID device once with hid-permissions-setup.sh, then reconnect the board and restart the dashboard. It installs /etc/udev/rules.d/99-zephyrforge-hid.rules for CAFE:4021 and may prompt for sudo:

bash tools/host/hid-permissions-setup.sh

From a source checkout, run-python.sh creates build/zephyrforge, installs this package in editable mode on first use, checks HID permissions and runs zephyrforge (default command web).

Dashboard Operations

  • Monitor: live board identity, runtime, memory, pins, SD-card details, and Wi-Fi state.

  • Boot configuration: save the clock (Default, 80, 160 or 240 MHz) and the Wi-Fi/BLE switches with Save&Reboot. The SD profile is always Standard. Reboot Board uses the already saved settings. See settings and save safety.

  • Wireless: provision Wi-Fi and a Control key over USB. Bluetooth connections use the independent Direct dashboard. See wireless setup.

  • USB drive: explicitly export an initialized SD card, then safely eject in the OS before confirming return to firmware. See SD ownership.

  • Wi-Fi diagnostic shell: click fresh connected Wi-Fi status to open the existing browser terminal. It is unauthenticated plaintext; use only a trusted, isolated network and never enter secrets. See diagnostic shells.

Controls follow the connected firmware's advertised capabilities; the shared HTTP API owns supported and unsupported operations. Forced save, a CDC serial console, and the application TCP CLI remain unavailable. The native diagnostic shell is separate from the unsupported saved TCP CLI switch and proof commands; the BLE Control key does not protect it.

Commands can be rejected or remain uncertain after a timeout/disconnect; delivery is not completion. Do not replay uncertain writes. Feature availability and safety gates follow the connected firmware. Host tests use fakes only; see the qualification gaps.

Dashboard HTTP API

Python and .NET implement the shared dashboard HTTP API. That contract owns routes, request fields, reserved status values and unsupported operations. Use the board ID returned by discovery when selecting a board for API requests.

Development and License

For host tests, type checks and frontend ownership, see Host development.

Package Responsibility
zephyrforge.reports Report codecs and ZephyrForge-specific validation; never opens a device
zephyrforge.hid HIDAPI device access and Report 20 command exchange
zephyrforge.dashboard Board monitor, multi-board selection, and the loopback Flask server
zephyrforge.cli The zephyrforge and python -m zephyrforge entry point
zephyrforge.web Dashboard assets explicitly staged from the shared frontend for package builds

Each public package can be imported independently without opening a device.

Python tests are grouped under tests/zephyrforge_tests/ by CLI, dashboard, HID, reports, packaging, and integration responsibility. Shared fixtures and repository-path helpers live under tests/zephyrforge_tests/support/; test dependencies and compile-only type contracts remain directly under tests/.

The package uses the BSD-3-Clause license. Its LICENSE mirrors the repository license and is included in built wheels; keep both copies identical.

Metadata

Release files for zephyrforge 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for zephyrforge 0.0.3
File Interpreter ABI Platform Actions
zephyrforge-0.0.3-py3-none-any.whl Python 3 none any Details for zephyrforge-0.0.3-py3-none-any.whl

Release files / zephyrforge-0.0.3-py3-none-any.whl

Download URL zephyrforge-0.0.3-py3-none-any.whl
Size 112.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
042fdf636ae2fac84b3b2d3f22276941becfc78c0260891600338eaee095b661
BLAKE2b-256 checksum
How to use checksums
07dffe8c1f349356693c7c75cce3f79a671f4de5cac8df327323ab55b9ef6b4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for zephyrforge 0.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for zephyrforge-0.0.3-py3-none-any.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.3 This release

1 release file Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page