RFC: Documentation

[AlCalzone]

I've started moving the documentation to GitHub Pages with Docsify, because the Wiki version was awkward. Since I'm somewhat routine-blinded, this issue is to collect information about what should be documented and how.

This is already planned:

• [ ] Getting started: Examples for common tasks
• [ ] API -> CommandClasses:
  • [ ] Overview over all implemented CCs (basically like #6)
  • [ ] For every CC: Public CC API (node.commandClasses.xyz.method())
  • [ ] Auto-Generation of this API documentation or at least auto-generation of stubs
• [ ] Auto-generation of interface/enum documentation (copy from code)

[Durban-Designer]

Definitely could use this. The docs you have now are a huge help but an example repo of a full project would be a even bigger help! Trying to read from a Z-Wave sensor through a USB interface and it's been touch and go. Connecting to serial is fine but actually preventing the node from falling asleep has been a challenge.

[AlCalzone]

preventing the node from falling asleep

That's usually not what you want to do. Most sensors support the Association CC with one or more so-called lifeline groups. These are used by the devices to send updates on their own, which allows them to reduce their battery usage. If you aren't getting them, either the associations are not configured correctly (most notably multi-channel vs node associations) or the reports aren't configured on the device. I have this device for example, which allows configuring which values are sent automatically and how often.

If you absolutely must poll the sensor, you can set the keepAwake property on the node instance and use node.commandClasses["Multilevel Sensor"].get() to get the current value. However, the property only keeps the driver from sending the node to sleep and the node may go to sleep on its own.

Here's a bunch of unsorted test code I'm using to test while developing: https://github.com/AlCalzone/node-zwave-js/blob/master/test/run.ts

I'm using the library in https://github.com/AlCalzone/ioBroker.zwave2/blob/master/src/main.ts, but I don't query specific values here. I basically just mirror all available values into another application, which allows to control them by value ids, without calling specific API methods.

And here's another library which uses zwave-js, maybe it helps you: https://github.com/RoboPhred/wutwot/tree/master/packages/wutwot-zwave

[robertsLando]

https://zwave-js.github.io/node-zwave-js/#/api/node?id=status

Alive it's missing in NodeStatus docs

[robertsLando]

Also I see you have methods to write/load the cache file. How is this internally managed? In docs you say that them are used internally, so should I ignore them or is it better to write the cache at some point? (scan complete for example)

The network cache is written after certain interview steps: when it is manually restarted whenever a node interview finishes these stages (but debounced) InterviewStage.ProtocolInfo InterviewStage.NodeInfo InterviewStage.CommandClasses InterviewStage.Complete

3. when the driver is shut down The values and metadata DBs are written continuously, but also throttled: every 1000ms if there were changes or after 50 changes, whatever happens earlier So I would say, let the driver do its thing and don't care about the cache. The only exception is deleting it when you want to force a fresh interview of everything

[robertsLando]

how can I identify the type of a valueId?

In zwave-js, a valueId has a value and metadata. Metadata is what defines the value's shape and description. Example for a wakeup interval:

{"type":"number","readable":false,"writeable":true,"min":240,"max":3600,"steps":60,"default":3600}

Missing documentation about Metadada : https://github.com/zwave-js/node-zwave-js/blob/master/packages/core/src/values/Metadata.ts

OZW's List and bitmask is mostly used for configuration values which I've modeled as numeric values with states:

https://github.com/zwave-js/node-zwave-js/blob/master/packages/core/src/values/Metadata.ts#L65-L66