5. APIs

APIs

• .frame()
• .parse()
• .header()

---

.frame(frameCntl, manufCode, seqNum, cmd, zclPayload[, clusterId])

Generate the raw packet of a ZCL command. Please see Section 2.3.1 General ZCL Frame Format in specification for more information.

Arguments:

1. frameCntl (Object): Frame control. Details of each property are given with the following table:

   Property	Type	Mandatory	Description
   frameType	2-bit	required	Frame type.
   manufSpec	1-bit	required	Manufacturer specific.
   direction	1-bit	required	Direction.
   disDefaultRsp	1-bit	required	Disable default response.

2. manufCode (Number): Manufacturer code, which is an uint16 integer. This field is ignored if frameCntl.manufSpec is 0.

3. seqNum (Number): Sequence number, which is a uint8 integer.

4. cmd (String | Number): Command id of which command packet you'd like to build.

5. zclPayload (Object | Array): ZCL payload depending on the given command.

6. clusterId (String | Number): Cluster id. Must be given if frameCntl.frameType is 1 (functional command packet).

Returns:

• (Buffer): Raw buffer of the ZCL packet.

Examples:

• Generate a ZCL foundation command packet

// foundation command: 'write'
var foundFrameCntl = {
        frameType: 0,  // Command acts across the entire profile (foundation)
        manufSpec: 0,
        direction: 0,
        disDefaultRsp: 0
    },
    foundPayload = [
        { attrId: 0x1234, dataType: 0x41, attrData: 'hello' },
        { attrId: 0xabcd, dataType: 0x24, attrData: [ 100, 2406 ] }
    ];

var foundBuf = zcl.frame(foundFrameCntl, 0, 0, 'write', foundPayload);

• Generate a ZCL functional command packet

// functional command: 'add', cluster: 'genGroups'(0x0004)
var funcFrameCntl = {
        frameType: 1,  // Command is specific to a cluster (functional)
        manufSpec: 1,
        direction: 0,
        disDefaultRsp: 0
    },
    funcPayload = {
        groupid: 0x0001,
        groupname: 'group1'
    };

var funcBuf = zcl.frame(funcFrameCntl, 0xaaaa, 1, 'add', funcPayload, 0x0004);

---

.parse(zclBuf[, clusterId], callback)

Parse a ZCL packet into a data object.

Arguments:

1. zclBuf (Buffer): ZCL raw packet to be parsed.

2. clusterId (String | Number): Cluster id. Must be given if zclBuf is a functional command.

3. callback (Function): function (err, result) {...}. Get called when the ZCL packet is parsed. The result is a data object with following properties:

   Property	Type	Description
   frameCntl	Object	Frame type.
   manufCode	Number	Manufacturer code.
   seqNum	Number	Sequence number.
   cmdId	String	Command id.
   payload	Object | Object[]	ZCL payload.

Returns:

• none

Examples:

• Parse a foundation command packet.

var foundBuf = new Buffer([
    0x00, 0x00, 0x02, 0x34, 0x12, 0x41, 0x05, 0x68,
    0x65, 0x6c, 0x6c, 0x6f, 0xcd, 0xab, 0x24, 0x66,
    0x09, 0x00, 0x00, 0x64
]);

zcl.parse(foundBuf, function(err, result) {
    if (!err)
        console.log(result);

    // The parsed result is an object
    // {
    //     frameCntl: { frameType: 0, manufSpec: 0, direction: 0, disDefaultRsp: 0 },
    //     manufCode: 0,
    //     seqNum: 0,
    //     cmdId: 'write',
    //     payload: [ 
    //         { attrId: 4660, dataType: 65, attrData: 'hello' },
    //         { attrId: 43981, dataType: 36, attrData: [ 100, 2406 ] }
    //     ]
    // }
});

• Parse a functional command packet.

var funcBuf = new Buffer([
    0x05, 0xaa, 0xaa , 0x01, 0x00, 0x01, 0x00, 0x06,
    0x67, 0x72, 0x6f, 0x75, 0x70, 0x31
]);

zcl.parse(funcBuf, 0x0004, function(err, result) {
    if (!err)
        console.log(result);

    // The parsed result is an object
    // {
    //     frameCntl: { frameType: 1, manufSpec: 1, direction: 0, disDefaultRsp: 0 },
    //     manufCode: 43690,
    //     seqNum: 1,
    //     cmdId: 'add',
    //     payload: {
    //         groupid: 1,
    //         groupname: 'group1'
    //     }
    // }
});

---

.header(zclBuf)

Parse the ZCL header only.

Arguments:

1. zclBuf (Buffer): ZCL header buffer to be parsed.

Returns:

• (Object): ZCL header data.

Examples:

var zclBuf = new Buffer([ 0x05, 0xaa, 0xaa , 0x01, 0x00, ... ]);
var header = zcl.header(zclBuf);

console.log(header);
// {
//     frameCntl: { frameType: 1, manufSpec: 1, direction: 0, disDefaultRsp: 0 },
//     manufCode: 43690,
//     seqNum: 1,
//     cmdId: 0,
// }