Zigbee OTA Firmwares

API change history

The security policies restrict a single client IP address to only 30 calls every minute, with a total of 100,000 calls and 1 gigabyte of bandwidth per month.

Download the firmware by company ID, product ID and firmware version.

Sample request:

GET //api/v1/firmware/zigbee/download?company=4489&product=17&version=1.2.55.3

Try it

Request

Request URL

Request parameters

  • This is the ZigBee assigned identifier for each member company. When used during the OTA upgrade process, manufacturer code value of 0xffff has special meaning of a wild card.The value has a ‘match all’ effect.OTA server may send a command with wild card value for manufacturer code to match all client devices from all manufacturers

  • The manufacturer should assign an appropriate and unique image type value to each of its devices in order to distinguish the products.This is a manufacturer specific value.However, the OTA Upgrade cluster has reserved the last 64 values of image type value to indicate specific file types such as security credential, log, and configuration. When a client wants to request one of these specific file types, it shall use one of the reserved image type values instead of its own (manufacturer specific) value when requesting the image via Query Next Product Request command

  • For firmware image, the file version represents the release and build number of the image’s application and stack.The application release and build numbers are manufacturer specific, however, each manufacturer should obtain stack release and build numbers from their stack vendor. OTA Upgrade cluster makes the recommendation below regarding how the file version should be defined, in an attempt to make it easy for humans and upgrade servers to determine which versions are newer than others.The upgrade server should use this version value to compare with the one received from the client. The server may implement more sophisticated policies to determine whether to upgrade the client based on the file version. A higher file version number indicates a newer file.

Request body

Responses

200 OK

Returns the firmware file.

204 No Content

The firmware not found.

400 Bad Request

Invalid request.

429 Too many requests

The rate limit 10 calls per 60 seconds or quota 100 MB per month has been exceeded.

Code samples

@ECHO OFF

curl -v -X GET "https://api.update.ledvance.com/v1/zigbee/firmwares/download?Company={}&Product={}&Version={}"

--data-ascii "{body}" 

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);


            // Request parameters
            queryString["Company"] = "{}";
            queryString["Product"] = "{}";
            queryString["Version"] = "{}";
            var uri = "https://api.update.ledvance.com/v1/zigbee/firmwares/download?" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.update.ledvance.com/v1/zigbee/firmwares/download");

            builder.setParameter("Company", "{}");
            builder.setParameter("Product", "{}");
            builder.setParameter("Version", "{}");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}


<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "Company": "{}",
            "Product": "{}",
            "Version": "{}",
        };
      
        $.ajax({
            url: "https://api.update.ledvance.com/v1/zigbee/firmwares/download?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.update.ledvance.com/v1/zigbee/firmwares/download";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"Company={}",
                         @"Product={}",
                         @"Version={}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.update.ledvance.com/v1/zigbee/firmwares/download');
$url = $request->getUrl();

$headers = array(
    // Request headers
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'Company' => '{}',
    'Product' => '{}',
    'Version' => '{}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
}

params = urllib.urlencode({
    # Request parameters
    'Company': '{}',
    'Product': '{}',
    'Version': '{}',
})

try:
    conn = httplib.HTTPSConnection('api.update.ledvance.com')
    conn.request("GET", "/v1/zigbee/firmwares/download?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
}

params = urllib.parse.urlencode({
    # Request parameters
    'Company': '{}',
    'Product': '{}',
    'Version': '{}',
})

try:
    conn = http.client.HTTPSConnection('api.update.ledvance.com')
    conn.request("GET", "/v1/zigbee/firmwares/download?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://api.update.ledvance.com/v1/zigbee/firmwares/download')

query = URI.encode_www_form({
    # Request parameters
    'Company' => '{}',
    'Product' => '{}',
    'Version' => '{}'
})
if query.length > 0
  if uri.query && uri.query.length > 0
    uri.query += '&' + query
  else
    uri.query = query
  end
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body