CC API

The Z-Wave JS CC API, is a no fuss, to the point and easy to use API.
You can think of this API as a low level approach to the driver.

It however, has one major drawback - it does not keep the UI, or local values upto date, unless value changes are responded to with an unsolicited value update. For this reason, it's use should only be relied upon, if absolutely necessary.

for normal use, we recommend the Value API

• Set the cc
• Set the CC method
• Provide any params the method needs.
• Move on

Examples

Turn on a binary switch

let Message = {
    payload: {
        mode: "CCAPI",
        node: 2,
        cc: "Binary Switch",
        method: "set",
        params: [true]
    }
}
return Message

You can also specify an endpoint. i.e. for those devices that may have multiple outlets let say.

let Message = {
    payload: {
        mode: "CCAPI",
        node: 2,
        cc: "Binary Switch",
        endpoint: 2,
        method: "set",
        params: [true]
    }
}
return Message

Or specify a duration, for the CC's that support a duration of time.

let Message = {
    payload: {
        mode: "CCAPI",
        node: 2,
        cc: "Multilevel Switch",
        method: "set",
        params: [20,"1m20s"]
    }
}
return Message

In order to set a configuration value using CC API, you can send a message with "params": [param number, param size, param value]. This example shows setting configuration parameter 3 for node 37:

let Message = {
    payload: {
        mode: "CCAPI",
        node: 37,
        cc: "Configuration",
        method: "set",
        params: [3,4,1] // [param number, param value, param length]
    }
}
return Message

For a complete list of CC's and their methods, Please go Here

Forcing Updates

The CC API is a set and forget type of request, therefore, this API does not verify that the value was set.
In normal circumstances, the device being changed, will send an unsolicited value update.

Some devices however, do not do this. In those situations, you can poll for the value after setting it (which should return the recently updated value)

let Message = {
    payload: {
        mode: "CCAPI",
        node: 2,
        cc: "Binary Switch",
        method: "set",
        forceUpdate: {
          property: "currentValue"
        },
        params: [false]
    }
}
return Message

The properties in the forceUpdate object, are those that are provided in VALUE_UPDATED events.
namely a property and sometimes propertyKey.

Whilst you can provide properties to override this query, such as an endpoint, and the commandClass, it is best to allow the driver to control this. For special circumstances however, you are free to modify it.

Z-Wave JS Enum Values

Some of the CC's use enums for their values, an example is the User Code CC. When creating a new user, you specify the user status, and Z-Wave JS makes it easy to do so, using an Enum as below.

NOTE: Specifying the Enum to reference, may not be necessary - We have added the ability never the less.

export enum UserIDStatus {
    Available = 0x00,
    Enabled,
    Disabled,
    Messaging,
    PassageMode,
    StatusNotAvailable = 0xfe,
}

To use an enum in your message, you specify an Enum to reference from Z-Wave JS, like below.

let Message = {
    payload: {
        node: 5,
        mode: "CCAPI",
        cc: "User Code",
        method: "set",
        enums: {1:"UserIDStatus"}, // {Paramater Index: Enum name, Paramater Index: Enum name}
        params: [5,"Enabled","1234"] // User 5, User Status, User Code
    }
}
return Message;

The above will then convert parameter 1 (the 2nd parameter) to 0x01

Method Return Mechanism

If the CCAPI method you are calling, yields a value (i.e a get type of request for instance),
The value that gets returned, can be traced back to 2 different locations.

• The returned object from the method its self.
• And a VALUE_UPDATED event, that get triggered by the driver.

For this reason, we don't return from the method directly, rather we depend on the event that gets triggered.
If we were to return from the method - you will end up with duplicated messages.

However! some methods don't cause an event, and are only returned from the method.
So, for these, we can include a property named responseThroughEvent and set it to false

let Message = {
    payload: {
        mode: "CCAPI",
        node: 16,
        cc: "Entry Control",
        method: "getSupportedKeys",
        responseThroughEvent: false
    }
}
return Message

This will make the module wait, and will return directly from the value that it returns.