-
Notifications
You must be signed in to change notification settings - Fork 0
ZigBee Family Tree
The family tree provides a means to locate compliance records for related products based on the device supplied ZigBee Certification type, Manufacturer's name, model name, hardware version, firmware version. The family tree also provides compliance records based on the SKU instead of the model name. The follow are two examples with different device descriptors provided by two devices with different FwVersions. The ComplianceId is the hash of the JSON payload.
ZNMH1F1
{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0","FwVer":"1.0"}
ZNMH1F2
{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0","FwVer":"2.0"}
The SKU version of the above examples would be as follows:
ZNMH1F1
{"Cert":"ZigBee3","Name":"Acme","Sku":"Boomerang","HwVer":"1.0","FwVer":"1.0"}
ZNMH1F2
{"Cert":"ZigBee3","Name":"Acme","Sku":"Boomerang","HwVer":"1.0","FwVer":"2.0"}
The following are examples and shorthand notations for less specific versions of the JSON payload:
ZNMH1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0"}'
ZNM = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang"}'
ZN = '{"Cert":"ZigBee3","Name":"Acme"}'
Z = '{"Cert":"ZigBee3"}'
The Family Tree is a table in which each of the user can calculate the hash for any level of the product tree, and retrieve all possible children. The family tree for the two version described above would be as follows:
| Index | Children |
|---|---|
| hash(Z) | ZN, ZNM, ZNMH1, ZNMH1F1, ZNMH1F2 |
| hash(ZN) | ZNM, ZNMH1, ZNMH1F1, ZNMH1F2 |
| hash(ZNM) | ZNMH1, ZNMH1F1, ZNMH1F2 |
| hash(ZNMH1) | ZNMH1F1, ZNMH1F2 |
| hash(ZNMH1F1) | NULL |
| hash(ZNMH1F2) | NULL |
Thus, if the device joining a gateway provides ZNMH1F1, and the gateway wants to know if there is a newer certified firmware version, the gateway would simply remove the FwVer tag from the JSON payload which creates ZNMH1. The gateway reads the row hash(ZNMH1), receives ZNMH1F1 (current version of device) and ZNMH1F2 (new version).
The ComplainceId for the new version is hash(ZNMH1F2) (Model version, not SKU), which can be used to access the Compliance table.
See Search for certified FW updates for a detailed example.
| Name | Write Access | Type | Description |
|---|---|---|---|
| FamilyString | Admin | string | JSON string |
| Valid | Admin | bool | Indicates if the current row is valid |
| ComplianceId | Admin | Address | If the family string is complete (ZNMHF) then this value shall be the ComplianceId. Otherwise, the value shall be 0 |
| SubAddress | Admin | address[] | List of hash(Sub FamilyString) |
| SubFamilyString | Admin | string[] | Sub FamilyStrings |
| SubComplianceId | Admin | Address | ComplianceId for complete family strings (ZNMHF) |
The ReadFamily function accepts Z, ZN, ZNM, ZNMH, ZNMHF JSON strings, and returns the number of sub family members can be found in the family tree. The function also returns the FamilyIndex for the Family String passed into the function, and the ComplianceId.
| Type | Name | Description |
|---|---|---|
| string | FamilyString | JSON string |
| Type | Name | Description |
|---|---|---|
| address | FamilyIndex | FamilyString Hash for the FamilyString submitted in the read |
| bool | FamilyValid | true if the family string is valid |
| uint | SubCount | Number of sub FamilyStrings which are associated with the current family string |
| address | ComplianceId | ComplianceId |
var ZNM = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang"}';
Compliance.ReadFamily(ZNM);
["0x599ebf746e46e6189944f0bffbb2f814e4ced59f", true, 3, "0x0000000000000000000000000000000000000000"]
The ReadFamilyIndex function requires the hash of the FamilyString, and returns the number of sub FamilyStrings. This function may also be used to convert from a ComplianceId back to the FamilyString.
| Type | Name | Description |
|---|---|---|
| address | FamilyIndex | hash(FamilyString) |
| Type | Name | Description |
|---|---|---|
| string | FamilyString | FamilyString |
| uint | SubCount | Number of sub FamilyStrings associated with the current FamilyString |
| address | ComplianceId | ComplianceID when the Family string is fully specified ZNMHF) |
var FamilyIndex = "0x425fd133b04814563267cec46e360ef33a106f28";
Compliance.ReadFamilyIndex(FamilyIndex);
["{\"Cert\":\"ZigBee3\",\"Name\":\"Acme\",\"Model\":\"Boomerang\",\"HwVer\":\"1.0\",\"FwVer\":\"1.0\"}", 0, "0x425fd133b04814563267cec46e360ef33a106f28"]
The ReadSubFamilyIndex returns a Sub FamilyString associated with a FamilyString.
| Type | Name | Description |
|---|---|---|
| string | FamilyString | Current FamilyString |
| uint | SubFamilyIndex | Sub FamilyString index |
| Type | Name | Description |
|---|---|---|
| address | SubAddress | hash(Sub FamilyString) |
| string | SubString | Sub FamilyString |
| address | SubComplianceID | Sub Family Compliance ID |
var ZNM = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang"}';
Compliance.ReadSubFamilyIndex(ZNM,0);
["0x425fd133b04814563267cec46e360ef33a106f28", "{\"Cert\":\"ZigBee3\",\"Name\":\"Acme\",\"Model\":\"Boomerang\",\"HwVer\":\"1.0\",\"FwVer\":\"1.0\"}", "0x425fd133b04814563267cec46e360ef33a106f28"]
The WriteFamilyTree writes the FamilyString, and then populates all FamilyStrings above the value passed in the parameter list.
For example, if ZNM is passed into the function, then rows ZNM, ZN, and Z will be written/Updated. If only ZN is passed, then rows ZN and Z will be written/updated.
The WriteFamilyTree may only be called by the Admin, and should be called once a device has passed certification.
| Type | Name | Description |
|---|---|---|
| string | Certification String | Family String with only certification |
| string | Certification/Name String | Family String with certification and company name |
| string | Certification/Name String/Model (or Sku) Family String | Family String with certification, company name, model(or Sku) Name |
| string | Certification/Name String/Model (or Sku)/HwVer Family String | Family String with certification, company name, model(or Sku) Name, Hardware Version |
| string | Certification/Name String/Model (or Sku)/HwVer/FwVer Family String | Family String with certification, company name, model(or Sku) Name, Hardware Version, Firmware Version |
| Type | Name | Description |
|---|---|---|
| bool | Status | True if the operation was successful |
var ZNMH1F1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0","FwVer":"1.0"}'
var ZNMH1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0"}'
var ZNM = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang"}'
var ZN = '{"Cert":"ZigBee3","Name":"Acme"}'
var Z = '{"Cert":"ZigBee3"}'
var ComplianceId = Compliance.CalcComplianceId(ZNMH1F1) Compliance.WriteFamilyTree(Z, ZN, ZNM, ZNMH1, ZNMH1F1, ComplianceId, {from:ContractOwner,gas:470000});`
This function removes a sub FamilyString from a given parent FamilyString.
This function may only be called by the Admin.
| Type | Name | Description |
|---|---|---|
| string | FamilyString | Parent FamilyString |
| string | SubFamilyString | Sub FamilyString to delete |
| Type | Name | Description |
|---|---|---|
| bool | Status | True if the operation was successful |
var ZNMH1F1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0","FwVer":"1.0"}'
var ZNMH1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0"}'
Compliance.DeleteSubFamily(ZNMH1, ZNMH1F1, {from:ContractOwner,gas:470000});
This function adds a sub FamilyString to the FamilyString.
This function may only be called by the Admin.
| Type | Name | Description |
|---|---|---|
| string | FamilyString | Parent FamilyString |
| string | SubFamilyString | Sub FamilyString to add to parent |
| address | SubComplianceId | Sub Family Compliance ID (0 if not fully specified) |
| Type | Name | Description |
|---|---|---|
| bool | Status | True if the operation was successful |
var ZNMH1F1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0","FwVer":"1.0"}'
var ZNMH1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0"}'
var ComplianceId = Compliance.CalcComplianceId(ZNMH1F1);
Compliance.WriteSubFamily(ZNMH1, ZNMH1F1, ComplianceId, {from:ContractOwner,gas:470000});
This function writes only the FamilyString and sets/clears the Valid flag. This function should only be used to modify a FamilyString or valid bit as it does not access any parent FamilyStrings, and thus the tables may become unstable.
This function may only be called by the Admin.
| Type | Name | Description |
|---|---|---|
| string | FamilyString | Family String |
| bool | Valid | Indicates if the Family String is valid |
| address | ComplianceId | ComplianceID if the Family String is fully specified (ZNMHF) |
| Type | Name | Description |
|---|---|---|
| bool | Status | True if the operation was successful |
var ZNMH1 = '{"Cert":"ZigBee3","Name":"Acme","Model":"Boomerang","HwVer":"1.0"}'
Compliance.WriteSubFamily(ZNMH1, false, 0, {from:ContractOwner,gas:470000});