The driver is the core of this library. It controls the serial interface, handles transmission and receipt of messages and manages the network cache. Any action you want to perform on the Z-Wave network must go through a driver instance or its associated nodes.
A detailed description of its methods and properties follows below.
Constructor
new (port: string) => Driver
The constructor takes the address of the serial port as the single argument. On Windows, this is similar to "COM3". On Linux this has the form /dev/ttyAMA0 (or similar).
start method
async start(): Promise<void>
This starts the driver and opens the underlying serial port and performs an interview of the controller and all nodes.
The following table gives you an overview of what happens during the startup process. Note that the promise resolves before the interview process is completed:
| Step | What happens behind the scenes | Library response |
|---|---|---|
| 1 | Serial port is opened | start() Promise resolves |
| 2 | Controller interview is performed | "driver ready" event is emitted |
| 3 | Every node is interviewed in the background (This may take a long time) | "interview completed" event is emitted for every node |
| 4 | - | "interview completed" event is emitted for the driver |
getSupportedCCVersionForNode method
getSupportedCCVersionForNode(nodeId: number, cc: CommandClasses): number
Nodes in a Z-Wave network are very likely support different versions of a Command Class (CC) and frequently support older versions than the driver software.
This method helps determine which version of a CC can be used to control a node. It takes two arguments:
nodeId: number- The ID that identifies a node in the networkcc: CommandClasses- The command class whose version should be retrieved
This method
- returns
0if the node does not support the given CC - also returns
0if the node interview was not completed yet - returns the version the node claims to support otherwise
Note: This only provides reliable information after the node interview was completed.
getSafeCCVersionForNode method
getSafeCCVersionForNode(nodeId: number, cc: CommandClasses): number
Since it might be necessary to control a node before its supported CC versions are known, this method helps determine which CC version to use. It takes the same arguments as getSupportedCCVersionForNode, but behaves differently. It
- returns
1if the node claims not to support the CC or no information is known - throws (!) if the requested CC is not implemented in this library
- returns the version the node claims to support otherwise
hardReset method
async hardReset(): Promise<void>
Performs a hard reset on the controller. WARNING: This wipes out all configuration!
The returned Promise resolves when the hard reset has been performed. It does not wait for completion of the initialization process which is started afterwards.
destroy method
async destroy(): Promise<void>
This shuts down the driver, closes the serial port and saves the network information to the local cache.
Note: Make sure to call this before your application is closed.
sendMessage method
sendMessage<TResponse?>(msg: Message, options?: SendMessageOptions): Promise<TResponse>
This method sends a message to the Z-Wave controller. It takes two arguments:
message- An instance of the message class that should be sentoptions(optional) - Additional options to influence the behavior of the method. SeeSendMessageOptionsfor a detailed description.
If it is known in advance which type the response will have, you can optionally pass the desired return type.
The behavior of this method strongly depends on the message that should be sent:
- If the sent message expects a response (this is defined in each message class), the method will wait until that response has been received. In this case, the returned Promise will resolve to that response.
- If no response is expected, the Promise will resolve after the transmission has been acknowledged by the controller (or the node in case of a
SendDataRequest). - When the message can't be transmitted because the node is asleep, the Promise will only resolve after the node wakes up again and receives the message. Depending on the configuration, this may take a very long time.
- When the message can't be transmitted due to a timeout, the method will throw.
sendCommand method
async sendCommand<TResponse?>(command: CommandClass, options?: SendMessageOptions): Promise<TResponse | undefined>
This method sends a command to a Z-Wave node. It takes two arguments:
command- An instance of the command class that should be sentoptions(optional) - Additional options to influence the behavior of the method. SeeSendMessageOptionsfor a detailed description.
If it is known in advance which type the response will have, you can optionally pass the desired return type.
Internally, it wraps the command in a SendDataRequest and calls sendMessage with it. Anything that applies to sendMethod is therefore true for sendCommand.
saveNetworkToCache method
async saveNetworkToCache(): Promise<void>
This method saves the current state of the Z-Wave network to a cache file. This allows the driver to remember information about the network without having to rely on a time-consuming interview process the next time it is started.
It is internally used during the interview and by the destroy method, so you shouldn't have to call it yourself.
Calls to the method are debounced. This means that the cache file is not guaranteed to be written immediately. However it is guaranteed that the data is persisted soon after the call.
restoreNetworkFromCache method
async restoreNetworkFromCache(): Promise<void>
This method restores the network information a previously saved cache file if one exists. Like saveNetworkToCache you shouldn't have to use it yourself.
cacheDir property
readonly cacheDir: string
This property returns absolute path of the directory where information about the Z-Wave network is cached.
controller property
readonly controller: ZWaveController
Once the "driver ready" event was emitted, this property provides access to the controller instance, which contains information about the controller and a list of all nodes.
Note: Don't use it before the driver is ready!
Driver events
The Driver class inherits from the Node.js EventEmitter and thus also supports its methods like on, removeListener, etc. The following events are implemented:
| Event | Description |
|---|---|
"error" |
Is emitted when the underlying serial port emits an error or invalid data is received. You need to add a listener for this event, otherwise unhandled "error" events will crash your application! |
"driver ready" |
Is emitted after the controller interview is completed but before the node interview is started. |
"all nodes ready" |
Is emitted when all nodes are safe to be used (i.e. the "ready" event has been emitted for all nodes). |