zha-device-handlers
ZHA quirks bridge the functionality gap created when manufacturers deviate from the ZCL specification, handling deviations and exceptions by parsing custom messages to and from Zigbee devices.
- 1.2k
- Python
- Apache-2.0
- 2 d ago
Zigbee OTA images for zigpy/ZHA
Repo zigpy/zigpy-ota, read from GitHub 1 d ago. zigpy has not joined Take My Repo.
zigpy/zigpy-ota is a public repo on GitHub by zigpy. Zigbee OTA images for zigpy/ZHA. It declares the GPL-3.0 license on GitHub. It is written mainly in Python, has 32 stars and last changed on 2026-11-20. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-21.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
OTA firmware images, metadata, and CLI tools for Zigbee devices, used by zigpy-based applications like Home Assistant's ZHA.
You don't need to use this repository directly. OTA updates are automatically available through:
Note: Firmware marked as [disabled] or [stale] is not installable. It's retained for historic and changelog purposes only.
By default, only stable firmware is available, which is highly recommended for most users.
To opt into pre-release firmware, add this to your Home Assistant configuration:
zha:
zigpy_config:
ota:
extra_providers:
- type: zigpy_ota
channel: beta # or 'dev' for bleeding edge (unstable, not recommended)
override_previous: true
Use the GitHub issue form to submit OTA images - this is the recommended and easiest method:
Add Manufacturer Device vX.X.Xmin_current_file_version to highest existing versionImportant: Submit one issue per OTA image. Multiple versions should be separate issues.
What happens next:
ota-create label to trigger PR creationIf you need to make changes to your submission, edit the original issue and ask a maintainer to add the ota-resubmit label to update the PR.
Tip: You can also submit older firmware versions (e.g., factory-installed firmware) so that ZHA displays "up-to-date" instead of "unknown" for devices already running the latest available firmware.
For updates to existing images (e.g., adding min_current_file_version or model_names to an existing image), you can submit a PR directly:
.yaml file in the images/ directorySee the YAML Metadata Format section below.
To disable or revert an existing firmware update, submit a PR using one of these methods:
disabled: true to the YAML metadata file to exclude it from the index without deleting the files..zigbee or .ota) and its corresponding YAML metadata file (.yaml) from the images/ directory, then submit a PR with those changesFor options 2 and 3, both the OTA binary and YAML metadata file must be removed together to fully remove a firmware update from the index. Use deletion only if the firmware bricks devices.
Note: The repository generally retains all firmware images for historic purposes.
Zigpy always prefers newer firmware versions, so older images are only used when they have constraints (like min_current_file_version or model_names) that make them more specific to certain devices.
You can check the firmware index to see if an image is marked as [stale] or [disabled]. These are not installed by zigpy/ZHA.
dev, the dev/ folder on the release/files branch is automatically updated with the latest index filesrelease/files branchdev branchImages are included in channels based on their channel YAML field:
channel field (default): included in stable, beta, and devchannel: beta: included in beta and dev onlychannel: dev: included in dev onlyIndex file naming (GitHub release assets):
zigpy_v2_ota.json, z2m_v1_ota.json, and markdown_v1.mdzigpy_v2_ota_beta.json, z2m_v1_ota_beta.json, and markdown_v1_beta.mdRecommended: Discover the URL dynamically via version files on the release/version branch:https://raw.githubusercontent.com/zigpy/zigpy-ota/release/version/{stable,beta,dev}.json
Index files are also mirrored to the release/files branch organized by channel (stable/, beta/, dev/), where all folders use the same filenames (zigpy_v2_ota.json, z2m_v1_ota.json, markdown_v1.md).
After an image is merged to the dev branch, the updated index is immediately available for testing at:https://raw.githubusercontent.com/zigpy/zigpy-ota/release/files/dev/zigpy_v2_ota.json
Direct access for all channels (not preferred):https://raw.githubusercontent.com/zigpy/zigpy-ota/release/files/{stable,beta,dev}/zigpy_v2_ota.json
Example: To use the stable Zigbee2MQTT index, add this to your Z2M configuration:
ota:
zigbee_ota_override_index_location: https://raw.githubusercontent.com/zigpy/zigpy-ota/release/files/stable/z2m_v1_ota.json
The YAML metadata file must have the same name as the OTA file with .yaml appended.
(e.g., firmware_name.ota → firmware_name.ota.yaml).
OTA files are automatically renamed to a standardized format based on their metadata: <manufacturer_id>-<image_type>-<file_version>_<hash>.ota (hash is first 6 chars of SHA3-256). The original filename is preserved in the source_file_name field.
This renaming is done automatically when submitting a new OTA image via the issue form. In the future, CLI tools will also be added to rename files locally.
For images stored in this repository:
# OTA metadata
file_name: 100B-010C-01001A02_abc123.ota
source_file_name: original_firmware.zigbee
source_url: https://manufacturer.com/original_firmware.zigbee
# Optional fields:
release_notes: |-
- Bug fixes
- New features
manufacturer_names: [Manufacturer A, Manufacturer B]
model_names: [Model X, Model Y]
min_current_file_version: 100
max_current_file_version: 200
min_hardware_version: 5
max_hardware_version: 10
specificity: 3
channel: beta
file_name: The standardized filename in the repository (auto-generated from OTA metadata)source_file_name: The original filename from the source (preserved for reference)manufacturer_names - List of manufacturer name strings for device matchingmodel_names - List of model name strings for device matchingmin_current_file_version - Minimum current firmware version for update eligibilitymax_current_file_version - Maximum current firmware version for update eligibilitymin_hardware_version - Minimum hardware version compatibilitymax_hardware_version - Maximum hardware version compatibilityspecificity - Breaks ties between matching images with the same file version (higher wins; a newer file version always takes priority)channel - Release channel (omit for stable which appears in all channels; beta appears in beta and dev; dev appears only in dev)Note on multi-step upgrades: Due to how zigpy's firmware matching algorithm works, it's typically sufficient to set min_current_file_version on the newer image to require a previous upgrade first.
Zigpy automatically prioritizes and prefers more specific images based on the device's current firmware version, so max_current_file_version constraints are usually not needed.
For the generated Z2M index, maxFileVersion is automatically computed from min_current_file_version constraints of newer images.
# Clone the repository
git clone https://github.com/zigpy/zigpy-ota.git
cd zigpy-ota
# Run setup script (creates venv, installs dependencies, sets up pre-commit)
script/setup
# Activate the virtual environment
source .venv/bin/activate
# Or manually:
# uv sync
# pre-commit install
# Run all tests
pytest
# Update snapshots after intentional changes
pytest --snapshot-update
# Run specific test file
pytest tests/test_prepare_pr.py
# Run with coverage
pytest --cov=zigpy_ota --cov-report=html
# Run all pre-commit hooks
pre-commit run --all-files
# Type checking
mypy zigpy_ota
# Linting and formatting
ruff check zigpy_ota
ruff format zigpy_ota
# Generate index from images
zigpy-ota generate-index --format zigpy # zigpy JSON (default)
zigpy-ota generate-index --format z2m # Zigbee2MQTT JSON
zigpy-ota generate-index --format markdown # Human-readable markdown
# Parse a GitHub issue submission
zigpy-ota parse-issue issue.md
# Prepare PR from issue (download OTA, create YAML, generate PR markdown)
zigpy-ota prepare-pr issue.md --output-pr-markdown pr.md
# Generate stub YAML metadata for an OTA file
zigpy-ota generate-stub-metadata firmware.ota
# Rename OTA files to standardized format (updates YAML too)
zigpy-ota rename-ota-files --dry-run # preview
zigpy-ota rename-ota-files # apply
# Generate fake OTA image for testing
zigpy-ota generate-fake-ota output.ota --manufacturer-id 0x100B --image-type 0x010C --file-version 0x00000001
# Replace real OTA files with fake ones (for tests)
zigpy-ota replace-with-fake-ota tests/data/ota_files/*.ota
The generate-index command has validation flags (all default to strict/fail):
# Strict validation (recommended for CI/CD)
zigpy-ota generate-index
# Development mode flags:
--allow-missing-yaml # Allow OTA images without corresponding YAML metadata
--allow-missing-ota # Allow YAML files without corresponding OTA binary
--allow-inconsistent-yaml # Allow third-party YAML with local OTA files present
--allow-filename-mismatch # Allow YAML file_name field not matching filename
--allow-invalid-yaml # Allow YAML files that fail to parse
--allow-collisions # Allow duplicate images (same ID/type/version)
--allow-unreachable # Allow images that can never be offered to any device
# Download and validate third-party/remote hosted images (not for CI/CD)
--validate-third-party
See CLAUDE.md for detailed developer documentation.
The zigpy-ota software code is licensed under GPL-3.0 (GNU General Public License v3.0). See LICENSE file.
Important: Binary firmware image files in this repository are third-party content from their respective manufacturers and are NOT covered by the GPL license. These firmware files remain under their original copyright and licensing terms as set by their manufacturers. Users must comply with applicable manufacturer terms when using these firmware files.
For questions or discussions, see GitHub Discussions.
zigpy/zigpy-ota is a public repo on GitHub by zigpy. Zigbee OTA images for zigpy/ZHA.
It declares the GPL-3.0 license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-20. GitHub counts 141 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.

ZHA quirks bridge the functionality gap created when manufacturers deviate from the ZCL specification, handling deviations and exceptions by parsing custom messages to and from Zigbee devices.
TI CC2531, CC13x2, CC26x2 radio support for Zigpy and ZHA
A library which communicates with Deconz radios for zigpy