Add support for controller-specific Serial API commands (e.g. through plugins)

[AlCalzone]

Some controllers, e.g. Aeotec Z-Stick Gen5 bring their own serial API commands which use proprietary function types. We could add support for them and auto-load the correct controller "plugin" after the controller was identified.

See the document in #1241 (reply in thread) for a description of the commands.

Discoverability of these commands for developers is an issue though.

[marcus-j-davies]

@AlCalzone

According to 7.3 Here

The response contains FUNCID_SUPPORTED_BITMASK[ ]
I wonder if the none "zwave" functions are reported - could be interesting and potentially a way to determine if any controller has some proprietary functions, configuring the abilities accordingly for the end user.

if this bitmask only reports on the zwave specifics, and not the proprietary functions - then no good.

[AlCalzone]

I think detecting the functionality is not the problem. However different sticks will have different implementations using the same proprietary funcids and we need to find a way to make this easily discoverable for the dev who wants to use these methods. Setting up syntax help (IntelliSense) for something dynamic like this is going to be interesting.

[marcus-j-davies]

I concur...

Taking the need to know about the proprietary functions a way (i think this can be achieved overtime)
especially with the use of FUNCID_SUPPORTED_BITMASK[ ]

You could look at something along the lines of

driver.controller.proprietary.CONTROLLER_MODEL.method(...)

Then upon calling such methods, if the Manufacturer/Product ID's don't match, throw.
You could substitute CONTROLLER_MODEL with a key, and that key being something obtained during the interview process - the user will obviously need to call on this key - but it removes the risk of them supplying something invalid.

at least this way, static IntelliSense can be provided based on CONTROLLER_MODEL

It feels muddy if I'm honest - but is an option.

[ivdimitro]

Hi, maybe I am missing something but in the old Open zwave implementation the Aeotec stick had configuration as any other device.
I know the way the configuration is currently handled is much different way than before but there is mechanism for overwrites and exceptions.
Can we just define the sticks as devices with overwrites? I doubt that there that many sticks to be worth implementing the generic solution you have described above.

[marcus-j-davies]

Hi @ivdimitro
There might be a config entry, but it will never work.

See here,
OpenZWave/open-zwave#1801.

Configuration changes on Controllers are proprietary, we removed config entries for this controller, for this reason.
it makes no sense having config entries if 1) its not a part of the CC, 2) the payload can be very different across controllers, 3) it won't work 😄

This is currently a low priority, but my suggestion is to have something like this.

Lets take the Aeotec LED example
driver.controller.proprietary.ZW090.enableLED(true)

ZW090 & enableLED will obviously be built over time as and when we are made aware or PR's submit entries to this area.

we want to add intellisense for developers, so it needs to be strongly typed.

[AlCalzone]

Configuration changes on Controllers are proprietary

That's the gist of it. It requires proprietary commands (of which the UZB3 for example has several), and I prefer a more generic solution (which could also be useful for other controllers) than hard coding device specific features directly into the driver.

[marcus-j-davies]

Yup,

I have done something quite generic with NR.
https://github.com/zwave-js/node-red-contrib-zwave-js/wiki/Controller-API#proprietaryfunction

This takes 2 params: the proprietary function ID & the payload that it expects

/* Turn of LED */
const OffBufferData = Buffer.from([0x51, 0x01, 0x00, 0x05, 0x01]) /* User Request Data */
const Message = {
    payload: {
        mode: "ControllerAPI",
        method: "proprietaryFunction",
        params: [0xF2, OffBufferData]
    }
}
return Message

behind the scene its doing this.

const ZWaveMessage = new ZWaveJS.Message(Driver, {
    type: ZWaveJS.MessageType.Request,
    functionType: Params[0],
    payload: Params[1]
});

const MessageSettings = {
    priority: ZWaveJS.MessagePriority.Controller,
    supportCheck: false
};

await Driver.sendMessage(ZWaveMessage, MessageSettings);

its a glorifed sendMessage wrapper 😄

[ivdimitro]

Hi @ivdimitro There might be a config entry, but it will never work.

See here, OpenZWave/open-zwave#1801.

Configuration changes on Controllers are proprietary, we removed config entries for this controller, for this reason. it makes no sense having config entries if 1) its not a part of the CC, 2) the payload can be very different across controllers, 3) it won't work smile

This is currently a low priority, but my suggestion is to have something like this.

Lets take the Aeotec LED example driver.controller.proprietary.ZW090.enableLED(true)

ZW090 & enableLED will obviously be built over time as and when we are made aware or PR's submit entries to this area.

we want to add intellisense for developers, so it needs to be strongly typed.

I've seen the configuration but never bothered to change anything as I like the lights :). Thanks for the explanation.