ZigBee User
The ZigBee ledger application is targeted for users of the ZigBee Certification Compliance Ledger, which is run on the Veriteem Distributed Ledger Technology (DLT) fabric. These tools provide interfaces to the data hosted on the DLT, so that you can query the data from the ledger and/or manage content.
A ZigBee user is typically a network or ecosystem operator who is reading the Compliance Ledger to deploy and maintain ZigBee networks. A device enters the network through a gateway. The gateway reads the device supplied attributes to build a Compliance ID, which is then used to read the ZigBee Compliance records. The ZigBee Compliance records contain the Model ID, which is then used to read the manufacturer supplied data.
The Compliance ID is based on the ZigBee Protocol, Manufacturer Name, SKU, Hardware Version, and Firmware version. This information is combined into a JSON string, and hashed with KECCAK-256. The ZigBee Compliance contract also provides a family tree, in which portions of the Compliance ID String may be removed to determine associated records (such as newer firmware versions).
To attach to the ledger to access the contracts, enter into a command line shell:
- VeriteemAttach.py -z
This python program attaches to the Veriteem fabric and makes the javascript based tools to interface with the contracts available to a command line session with geth. Geth is the blockchain command line tool that hosts a javascript VM for interacting with the blockchain that hosts the contracts that make up the ZigBee Certification ledger.
After entering the VeriteemAttach.py -z command, you can load the ZigBee Certification Ledger contracts into your geth session by entering:
- loadScript("LoadZigBee.js")
The following sections provide examples of accessing the contracts. Each of the examples assumes you have opened a command line shell and entered the following:
VeriteemAttach.py -z
loadScript("LoadZigBee.js")
The entry point into the Compliance Ledger is the Compliance ID, which is based on the ZigBee Certification type, Manufacturer's name, SKU, hardware version, and firmware version. This information is read from the device, put into the Compliance ID string, and a KECCAK-256 hash is performed on the Compliance ID String to build the Compliance ID.
| Compliance ID Field | Device Source |
|---|---|
| ZigBee Certification type | *** TBD Simple Descriptor? *** |
| Manufacturer's Name | Basic Cluster (0x0000), ManufacturerName (0x004) or OTA Upgrade(0x0019), MfgId(0x0007) |
| Sku | Basic Cluster (0x0000), ModelIdentifier (0x0005) |
| Hardware Version | Basic Cluster (0x0000), HWVersion (0x0003) |
| Firmware Version | OTA Upgrade (0x0019), CurrentFileVersion (0x0002) |
Here is an example of accessing the ledger from a command line shell.
ZNMHF = '{"Cert":"ZigBee 3.0","Name":"Somfy","Sku":"1811682","HwVer":"0x01","FwVer":"0x01"}'
ComplianceId = ZigBee.CalcComplianceId(ZNMHF)
"0xB479fb1560298818A81D3091d8d1579605897a9E"
The ZigBee Compliance contract includes a family tree, in which portions of the Compliance ID string (Family String) may be removed and passed to the family tree. The family tree will then return associated records with the Family String.
The family tree contains the following levels and associated records:
| Level | Associated Records |
|---|---|
| Cert | All Manufacturers who have associated certified products |
| Cert, Mfg Name | All SKUs associated with this manufacturer |
| Cert, Mfg Name, SKU | All Hardware/firmware records associated with this SKU |
| Cert, Mfg Name, SKU, HW Version | All firmware records associated with this HW version |
| Cert, Mfg Name, SKU, HW Version, FW Version | All compliance records associated with the Compliance ID String |
Here is an example of querying the ledger for cert info in a product family.
Z = '{"Cert":"ZigBee 3.0"}'
ZigBee.ReadFamily(Z)
["0xb132d5db5e1092374412430085befd0715f84155", true, 14, "0x0000000000000000000000000000000000000000"]`<br>
ZigBee.ReadSubFamilyIndex(Z,0)
["0x4aa64069328f6df82b8d1152c948c1666f524eb2", "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\"}", "0x0000000000000000000000000000000000000000"]
ZN = "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\"}"
ZigBee.ReadFamily(ZN)
["0x4aa64069328f6df82b8d1152c948c1666f524eb2", true, 1, "0x0000000000000000000000000000000000000000"]
ZigBee.ReadSubFamilyIndex(ZN,0)
["0xbe85e160578c3e1195c5318f78c88b50d12b053b", "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\",\"Sku\":\"1811682\"}", "0x0000000000000000000000000000000000000000"]
ZNM = "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\",\"Sku\":\"1811682\"}"
ZigBee.ReadFamily(ZNM)
["0xbe85e160578c3e1195c5318f78c88b50d12b053b", true, 2, "0x0000000000000000000000000000000000000000"]`<br>
ZigBee.ReadSubFamilyIndex(ZNM,0)
["0xb479fb1560298818a81d3091d8d1579605897a9e", "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\",\"Sku\":\"1811682\",\"HwVer\":\"0x01\",\"FwVer\":\"0x01\"}", "0xb479fb1560298818a81d3091d8d1579605897a9e"]
ZigBee.ReadSubFamilyIndex(ZNM,1)
["0x6507ab1930ece3a40ae265dededce38963709cc3", "{\"Cert\":\"ZigBee 3.0\",\"Name\":\"Somfy\",\"Sku\":\"1811682\",\"HwVer\":\"0x01\"}", "0x0000000000000000000000000000000000000000"]
The Read function provides compliance record for a ComplianceID. See the overview on how to form a ComplianceId.
| Type | Name | Description |
|---|---|---|
| address | ComplianceModelId | Compliance ID, which is determined by the hash method described in the FamilyTree section. |
| Type | Name | Description |
|---|---|---|
| address | Tester | ID of the Tester who wrote the compliance record |
| address | MfgModelId | Manufacturer's ModelID |
| string | ExpirationData | Expiration Data of compliance record |
| string | ComplianceData | JSON compliance record |
| bool | Valid | True if the compliance Admin has approved the record |
Reading the compliance record:
ZigBee.Read("0xb479fb1560298818a81d3091d8d1579605897a9e")
["0x6270d0914e22fa7f8fb48942b8b3c663f412b2e8", "0xb479fb1560298818a81d3091d8d1579605897a9e", "2/1/18", "{\"SKU\": \"1811682\", \"ParentFunctionalCategories\": [\"Energy Efficiency\"], \"Company\": \"Somfy\", \"CertificateID\": \"ZIG18011ZB330059-24\", \"ProductLinkURL\": \"\", \"FunctionalSubCategories\": [\"Thermometer\", \"Temperature Sensor (Home)\", \"Simple Sensor\", \"Sensor\", \"Energy Efficiency\"], \"ProductRevisionVersion\": \"1\", \"ProductName\": \"Zigbee Temperature & Humidity Sensor\", \"ApplicationTypeVersion\": \"1\", \"CompliantPlatformType\": \"\", \"ApplicationType\": \"ZigBee 3.0\", \"CurrentStatus\": \"Approved\", \"ProductLongDescription\": \"Monitor the temperature & humidity levels in the rooms of your house, display the measurements in TaHoma Bee system and bring you a maximum of comfort.<br />Can be activated to start several scenarios (lighting, blinds up or down, etc.)\", \"ProductType\": \"End Product\", \"ProductShortDescription\": \"Monitor the temperature & humidity levels in the rooms of your house, display the measurements in TaHoma Bee system and bring you a maximum of comfort.\", \"TechnicalSubCategories\": [\"Temperature Sensor (Home)\"], \"TechnicalCategory\": \"ZigBee 3.0\", \"FirmwareVersion\": \"0x01\", \"HardwareVersion\": \"0x01\", \"CertifiedDate\": \"2/1/18\"}", true, "0x0000000000000000000000000000000000000000"]
This function will return the valid bit for the compliance record. This function does not verify the expiration date.
| Type | Name | Description |
|---|---|---|
| address | ComplianceModelId | Compliance ID, which is determined by the hash method described in the FamilyTree section. |
| Type | Name | Description |
|---|---|---|
| bool | Valid | True if the compliance Admin has approved the record |
ZigBee.Valid("0xb479fb1560298818a81d3091d8d1579605897a9e")
`true`
The ModelInfo Contract is the heart of the Compliance Ledger. A device manufacturer creates a Model in the ModelInfo Contract using a ModelID, and then can reference the ModelID in all other compliance and manufacturer supplied tables. The ModelID is a unique random number, which may be the same value as the Compliance ID.
The Model may consist of other components, which are referenced by their ModelID. These components may or may not be manufacturer by the same entity.
The Read function provides the manufacturer ID, JSON model data, and number of subcomponents.
| Type | Name | Description |
|---|---|---|
| address | ModelId | ModelId for the model. This value shall be obtained by the associated compliance contract |
| Type | Name | Description |
|---|---|---|
| string | Data | JSON model data |
| address | MfgId | Manufacturer's ID |
| uint | ComponentCount | Number of components contained in the model |
ModelInfo.Read("0xb479fb1560298818a81d3091d8d1579605897a9e");
["{\"HwVer\": \"0x01\", \"Name\": \"Somfy\", \"Model\": \"1811682\", \"MfgCert\": \"\", \"ModelId\": \"0xB479fb1560298818A81D3091d8d1579605897a9E\", \"CompanyURI\": \"\"}", 0]
The ReadComponent function allows the user to read each address of components contained in the model. The user must first call the Read function to determine the number of components contained int the model.
| Type | Name | Description |
|---|---|---|
| address | ModelId | ModelId for the model. This value shall be obtained by the associated compliance contract |
| uint | ComponentIndex | Index starting at 0 |
| Type | Name | Description |
|---|---|---|
| address | Component | ModelId of the component |
ModelInfo.ReadComponent("0xb479fb1560298818a81d3091d8d1579605897a9e",0)
"0x"
The User interface is a read only interface, which allows ecosystem operators to read the security assertions, firmware versions, and firmware update URIs as provided by the manufacturer. The security table is indexed by the ModelId, which most likely will be determined through the Compliance Contract.
This function returns the number of versions associated with the ModelId.
| Type | Name | Description |
|---|---|---|
| address | ModelId | ModelId for the model. This value shall be obtained by the associated compliance contract |
| Type | Name | Description |
|---|---|---|
| uint | Count | Number of versions associated with the ModelId |
DeviceSecurity.ReadCount("0xB479fb1560298818A81D3091d8d1579605897a9E")
0
This function reads a specific version of the security record. The user should call the ReadCount function to determine the current number of versions for the given ModelId.
| Type | Name | Description |
|---|---|---|
| address | ModelId | ModelId for the model. This value shall be obtained by the associated compliance contract |
| uint | VersionIndex | Index into the version list. Index starts at 0. |
| Type | Name | Description |
|---|---|---|
| string | MUD | JSON manufacture usage data per IETF MUD. |
| string | Security | JSON security assertion |
| string | VersionName | Version name, which shall match the version reported by the device |
| string | URI | Firmware update URI |
DeviceSecurity.Read("0xB479fb1560298818A81D3091d8d1579605897a9E",0)
This will return an error if there are no Firmware updates posted by Mfg.