{"id":19733593,"url":"https://github.com/zwave-js/firmware-updates","last_synced_at":"2025-04-30T03:32:20.166Z","repository":{"id":41090397,"uuid":"508258310","full_name":"zwave-js/firmware-updates","owner":"zwave-js","description":"The firmware update service for Z-Wave JS at https://firmware.zwave-js.io","archived":false,"fork":false,"pushed_at":"2024-05-22T08:02:08.000Z","size":1543,"stargazers_count":25,"open_issues_count":15,"forks_count":26,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-05-22T09:25:55.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zwave-js.github.io/firmware-updates/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zwave-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["zwave-js"],"patreon":null,"open_collective":"z-wave-js","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2022-06-28T10:46:06.000Z","updated_at":"2024-05-22T09:25:58.582Z","dependencies_parsed_at":"2023-12-01T23:29:36.183Z","dependency_job_id":"401aa263-62f4-4fa2-913b-4f49f2e56149","html_url":"https://github.com/zwave-js/firmware-updates","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zwave-js%2Ffirmware-updates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zwave-js%2Ffirmware-updates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zwave-js%2Ffirmware-updates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zwave-js%2Ffirmware-updates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zwave-js","download_url":"https://codeload.github.com/zwave-js/firmware-updates/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224196899,"owners_count":17271907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T00:32:08.605Z","updated_at":"2024-11-12T00:33:15.863Z","avatar_url":"https://github.com/zwave-js.png","language":"TypeScript","funding_links":["https://github.com/sponsors/zwave-js","https://opencollective.com/z-wave-js"],"categories":[],"sub_categories":[],"readme":"# Z-Wave JS Firmware Update Service\n\nThis is the web service powering semi-automatic firmware updates in Z-Wave JS.\n\n## How it works\n\nFirmware upgrades are defined in the files in the `firmware` directory. This information is parsed by the web service and used to respond to requests.\n\nZ-Wave JS will query the web service on demand, providing the device identification of the device to be updated. If an update is available, the web service will respond with the necessary information to display to the user.\n\nWhen desired, Z-Wave JS will download the update(s) from the provided URL, verify their integrity and install them.\n\n## Providing firmware definition files\n\n\u003e [!WARNING]\n\u003e We **will not** accept firmware updates hosted by third parties. All updates must come from the respective device manufacturer. We make an exception for firmwares that are publicly hosted by the manufacturer, but those **will** still require the manufacturer's review before merging.\n\nWe kindly ask you to open a PR for any changes to firmware updates.\nThis way they can automatically be checked for errors.\n\nSee [the documentation](docs/firmware-files.md) for more information on how to author these files.\n\n## How to use?\n\n### API Keys\n\nAll requests to the API require an API key, provided using the `X-API-Key` HTTP header. API keys are **free for non-commercial use** or installations in non-commercial environments. Commercial use will be charged.\n\n\u003e [!NOTE]\n\u003e Home Assistant and official Z-Wave JS projects already have an API key for non-commercial use. Requesting an API key is not necessary for those.\n\nTo request an API key, please [reach out](mailto:info@zwave-js.io) and provide the following information:\n\n-   Project/Company name\n-   Open source / Commercial\n-   Repository URL (open source only)\n-   Approximate no. of requests/hour\n\nOnce you have your API key, you can use it to make HTTP requests to the API endpoints. Currently these are defined:\n\n### API v1, get updates\n\n```\nPOST https://firmware.zwave-js.io/api/v1/updates\nContent-Type: application/json\nX-API-Key: \u003cYour API Key\u003e\n\n{\n    \"manufacturerId\": \"0x1234\",\n    \"productType\": \"0xabcd\",\n    \"productId\": \"0xcafe\",\n    \"firmwareVersion\": \"1.6\"\n}\n```\n\nThe `firmwareVersion` field may also contain a patch version, e.g. `1.6.1`. When no patch version is provided, it will be assumed to be `0`, so `1.6` is equivalent to `1.6.0`.\n\n**Example response:**\n\n```json\n[\n    {\n        \"version\": \"1.5\",\n        \"changelog\": \"* Initial release\",\n        \"files\": [\n            {\n                \"target\": 0,\n                \"integrity\": \"sha256:45d004e1b5997a053f1de40753d19fc534fd657080810cfb697b868a3cf0e764\",\n                \"url\": \"https://example.com/firmware/1.5.otz\"\n            }\n        ],\n        \"downgrade\": true,\n        \"normalizedVersion\": \"1.5.0\"\n    },\n    {\n        \"version\": \"1.7\",\n        \"changelog\": \"* Fixed some bugs\\n*Added more bugs\",\n        \"files\": [\n            {\n                \"target\": 0,\n                \"integrity\": \"sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1\",\n                \"url\": \"https://example.com/firmware/1.7.otz\"\n            }\n        ],\n        \"downgrade\": false,\n        \"normalizedVersion\": \"1.7.0\"\n    }\n]\n```\n\nTo help applications decide which updates to show and how, additional fields are added to the response:\n\n-   `downgrade`: Whether this version is a downgrade (`true`) or an upgrade (`false`). Applications may want to only show downgrades when specifically requested.\n-   `normalizedVersion`: A normalized, [semver](https://semver.org/) compatible representation of the version field to make it easier to compare them. Examples:\n    -   version `1.7` becomes `1.7.0`\n    -   version `1.7.0` stays `1.7.0`\n    -   version `1.7.2` stays `1.7.2`\n\n\u003e [!NOTE]\n\u003e API version 1 will only return updates from the `stable` channel. To also get updates from the `beta` channel, use API version 2.\n\n**Response type definition:**\n\n```ts\ntype APIv1_Response = {\n    version: string;\n    changelog: string;\n    files: {\n        target: number;\n        url: string;\n        integrity: string;\n    }[];\n    downgrade: boolean;\n    normalizedVersion: string;\n}[];\n```\n\n### API v2, get updates\n\n```\nPOST https://firmware.zwave-js.io/api/v2/updates\nContent-Type: application/json\nX-API-Key: \u003cYour API Key\u003e\n\n{\n    \"manufacturerId\": \"0x1234\",\n    \"productType\": \"0xabcd\",\n    \"productId\": \"0xcafe\",\n    \"firmwareVersion\": \"1.6\"\n}\n```\n\nChanges compared to v1:\n\n-   Adds the `channel` field to the response, which can be either `stable` or `beta`\n-   `normalizedVersion` distinguishes between versions from the `stable` and `beta` channels. Examples:\n    -   stable version `1.7` becomes `1.7.0`\n    -   stable version `1.7.0` stays `1.7.0`\n    -   stable version `1.7.2` stays `1.7.2`\n    -   beta version `1.8` becomes `1.8.0-beta`\n    -   beta version `1.8.2` becomes `1.8.2-beta`\n\n**Example response:**\n\n```json\n[\n    {\n        \"version\": \"1.7\",\n        \"changelog\": \"* Fixed some bugs\\n*Added more bugs\",\n        \"channel\": \"stable\",\n        \"files\": [\n            {\n                \"target\": 0,\n                \"integrity\": \"sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1\",\n                \"url\": \"https://example.com/firmware/1.7.otz\"\n            }\n        ],\n        \"downgrade\": false,\n        \"normalizedVersion\": \"1.7.0\"\n    },\n    {\n        \"version\": \"1.8\",\n        \"changelog\": \"* Fixed some bugs\\n*Added more bugs\",\n        \"channel\": \"beta\",\n        \"files\": [\n            {\n                \"target\": 0,\n                \"integrity\": \"sha256:833f9eea2328cb05cbddc00b482e73225a09ca15dc8f90060e8b58ed9aa83a99\",\n                \"url\": \"https://example.com/firmware/1.8.otz\"\n            }\n        ],\n        \"downgrade\": false,\n        \"normalizedVersion\": \"1.8.0-beta\"\n    }\n]\n```\n\n**Response type definition:**\n\n```ts\ntype APIv2_Response = {\n    version: string;\n    changelog: string;\n    channel: \"stable\" | \"beta\";\n    files: {\n        target: number;\n        url: string;\n        integrity: string;\n    }[];\n    downgrade: boolean;\n    normalizedVersion: string;\n}[];\n```\n\n### API v3, get updates\n\n```\nPOST https://firmware.zwave-js.io/api/v3/updates\nContent-Type: application/json\nX-API-Key: \u003cYour API Key\u003e\n\n{\n    \"manufacturerId\": \"0x1234\",\n    \"productType\": \"0xabcd\",\n    \"productId\": \"0xcafe\",\n    \"firmwareVersion\": \"1.6\",\n    \"region\": \"europe\"\n}\n```\n\nChanges compared to v2:\n\n-   Adds the **optional** `region` field to both the request and the response, which can be one of these values:\n    -   `\"europe\"`\n    -   `\"usa\"`\n    -   `\"australia/new zealand\"`\n    -   `\"hong kong\"`\n    -   `\"india\"`\n    -   `\"israel\"`\n    -   `\"russia\"`\n    -   `\"china\"`\n    -   `\"japan\"`\n    -   `\"korea\"`\n\nIf the `region` field is present in the request, the response will only contain updates for that region, or updates without a specified region (which are assumed to be region-agnostic).\nIf no `region` is specified in the request, the response will only contain updates without a specified region.\n\nPrevious API versions will ignore the `region` field in the request and will not return updates with a specified region.\n\n**Example response:**\n\n```json\n[\n    {\n        \"version\": \"1.7\",\n        \"changelog\": \"EU Version:\\n* Fixed some bugs\\n*Added more bugs\",\n        \"channel\": \"stable\",\n        \"files\": [\n            {\n                \"target\": 0,\n                \"integrity\": \"sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1\",\n                \"url\": \"https://example.com/firmware/1.7-eu.otz\"\n            }\n        ],\n        \"downgrade\": false,\n        \"normalizedVersion\": \"1.7.0\",\n        \"region\": \"europe\"\n    }\n]\n```\n\n**Response type definition:**\n\n```ts\ntype APIv3_Response = {\n    version: string;\n    changelog: string;\n    channel: \"stable\" | \"beta\";\n    region?:\n        | \"europe\"\n        | \"usa\"\n        | \"australia/new zealand\"\n        | \"hong kong\"\n        | \"india\"\n        | \"israel\"\n        | \"russia\"\n        | \"china\"\n        | \"japan\"\n        | \"korea\";\n    files: {\n        target: number;\n        url: string;\n        integrity: string;\n    }[];\n    downgrade: boolean;\n    normalizedVersion: string;\n}[];\n```\n\n## Development and testing locally\n\nSee [the documentation](docs/testing-locally.md) for more information on how to test the service locally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzwave-js%2Ffirmware-updates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzwave-js%2Ffirmware-updates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzwave-js%2Ffirmware-updates/lists"}