This is the web service powering semi-automatic firmware updates in Z-Wave JS.

Firmware upgrades are defined in the files in the firmware directory. This information is parsed by the web service and used to respond to requests.

Z-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.

When desired, Z-Wave JS will download the update(s) from the provided URL, verify their integrity and install them.

We kindly ask you to open a PR for any changes to firmware updates. This way they can automatically be checked for errors.

See the documentation for more information on how to author these files.

All 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.

To request an API key, please reach out and provide the following information:

• Project/Company name
• Open source / Commercial
• Repository URL (open source only)
• Approximate no. of requests/hour

Once you have your API key, you can use it to make HTTP requests to the API endpoints. Currently these are defined:

POST https://firmware.zwave-js.io/api/v1/updates
Content-Type: application/json
X-API-Key: <Your API Key>

{
    "manufacturerId": "0x1234",
    "productType": "0xabcd",
    "productId": "0xcafe",
    "firmwareVersion": "1.6"
}

The 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.

Example response:

[
    {
        "version": "1.5",
        "changelog": "* Initial release",
        "files": [
            {
                "target": 0,
                "integrity": "sha256:45d004e1b5997a053f1de40753d19fc534fd657080810cfb697b868a3cf0e764",
                "url": "https://example.com/firmware/1.5.otz"
            }
        ],
        "downgrade": true,
        "normalizedVersion": "1.5.0"
    },
    {
        "version": "1.7",
        "changelog": "* Fixed some bugs\n*Added more bugs",
        "files": [
            {
                "target": 0,
                "integrity": "sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1",
                "url": "https://example.com/firmware/1.7.otz"
            }
        ],
        "downgrade": false,
        "normalizedVersion": "1.7.0"
    }
]

To help applications decide which updates to show and how, additional fields are added to the response:

• downgrade: Whether this version is a downgrade (true) or an upgrade (false). Applications may want to only show downgrades when specifically requested.
• normalizedVersion: A normalized, semver compatible representation of the version field to make it easier to compare them. Examples:
  • version 1.7 becomes 1.7.0
  • version 1.7.0 stays 1.7.0
  • version 1.7.2 stays 1.7.2

Response type definition:

type APIv1_Response = {
    version: string;
    changelog: string;
    files: {
        target: number;
        url: string;
        integrity: string;
    }[];
    downgrade: boolean;
    normalizedVersion: string;
}[];

POST https://firmware.zwave-js.io/api/v2/updates
Content-Type: application/json
X-API-Key: <Your API Key>

{
    "manufacturerId": "0x1234",
    "productType": "0xabcd",
    "productId": "0xcafe",
    "firmwareVersion": "1.6"
}

Changes compared to v1:

• Adds the channel field to the response, which can be either stable or beta
• normalizedVersion distinguishes between versions from the stable and beta channels. Examples:
  • stable version 1.7 becomes 1.7.0
  • stable version 1.7.0 stays 1.7.0
  • stable version 1.7.2 stays 1.7.2
  • beta version 1.8 becomes 1.8.0-beta
  • beta version 1.8.2 becomes 1.8.2-beta

Example response:

[
    {
        "version": "1.7",
        "changelog": "* Fixed some bugs\n*Added more bugs",
        "channel": "stable",
        "files": [
            {
                "target": 0,
                "integrity": "sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1",
                "url": "https://example.com/firmware/1.7.otz"
            }
        ],
        "downgrade": false,
        "normalizedVersion": "1.7.0"
    },
    {
        "version": "1.8",
        "changelog": "* Fixed some bugs\n*Added more bugs",
        "channel": "beta",
        "files": [
            {
                "target": 0,
                "integrity": "sha256:833f9eea2328cb05cbddc00b482e73225a09ca15dc8f90060e8b58ed9aa83a99",
                "url": "https://example.com/firmware/1.8.otz"
            }
        ],
        "downgrade": false,
        "normalizedVersion": "1.8.0-beta"
    }
]

Response type definition:

type APIv2_Response = {
    version: string;
    changelog: string;
    channel: "stable" | "beta";
    files: {
        target: number;
        url: string;
        integrity: string;
    }[];
    downgrade: boolean;
    normalizedVersion: string;
}[];

POST https://firmware.zwave-js.io/api/v3/updates
Content-Type: application/json
X-API-Key: <Your API Key>

{
    "manufacturerId": "0x1234",
    "productType": "0xabcd",
    "productId": "0xcafe",
    "firmwareVersion": "1.6",
    "region": "europe"
}

Changes compared to v2:

• Adds the optional region field to both the request and the response, which can be one of these values:
  • "europe"
  • "usa"
  • "australia/new zealand"
  • "hong kong"
  • "india"
  • "israel"
  • "russia"
  • "china"
  • "japan"
  • "korea"

If 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). If no region is specified in the request, the response will only contain updates without a specified region.

Previous API versions will ignore the region field in the request and will not return updates with a specified region.

Example response:

[
    {
        "version": "1.7",
        "changelog": "EU Version:\n* Fixed some bugs\n*Added more bugs",
        "channel": "stable",
        "files": [
            {
                "target": 0,
                "integrity": "sha256:cd19da525f20096a817197bf263f3fdbe6485f00ec7354b691171358ebb9f1a1",
                "url": "https://example.com/firmware/1.7-eu.otz"
            }
        ],
        "downgrade": false,
        "normalizedVersion": "1.7.0",
        "region": "europe"
    }
]

Response type definition:

type APIv3_Response = {
    version: string;
    changelog: string;
    channel: "stable" | "beta";
    region?:
        | "europe"
        | "usa"
        | "australia/new zealand"
        | "hong kong"
        | "india"
        | "israel"
        | "russia"
        | "china"
        | "japan"
        | "korea";
    files: {
        target: number;
        url: string;
        integrity: string;
    }[];
    downgrade: boolean;
    normalizedVersion: string;
}[];

See the documentation for more information on how to test the service locally.