Version 4.0.0 (Breaking)

[marcus-j-davies]

WORK-IN-PROGRESS

• Versions

  • ZWave JS Driver Version: 15.3.0
  • ZWave JS Server Version: 3.1.0 (Schema Version 43)

• Breaking Changes

  • You now need to build your own PSI for the platforms you wish to target.
    Having to maintain the build actions/platforms to keep these updated is eating into the time I have left.
    Building a PSI is relatively uneventful - please see the READ ME on how to do this.
  • DownloadPSI method on the Helper class has been removed.
  • Removed support for NET45 and NET5.0
    The supported frameworks are as follows:
    - NET 48
    - NET 6.0
    - NET 7.0
    - NET 80
    - NETSTANDARD 2.0
    - NETSTANDARD 2.1
  • enableSoftReset has been moved to features.softReset on the ZWaveOptions class
  • The NodeStatistics arg on the ZWaveNode class event StatisticsUpdated has been renamed to NodeStatisticsUpdatedArgs
  • The ControllerStatistics arg on the Controller class event StatisticsUpdated has been renamed to ControllerStatisticsUpdatedArgs
  • The InclusionResult argument has been renamed to InclusionResultArgs
  • The ValueUpdated event now uses a dedicated class for the args parameter
  • The ValueNotification event now uses a dedicated class for the args parameter
  • The NodeRemoved event now contains a reason Enum as to why it was removed.
  • The NetworkHealDone and NetworkHealProgress events have been renamed to
    RebuildRoutesDone and RebuildRoutesProgress and not have dedicated classes for the args
  • The BeginExclusion method now requires an Exclusion Options instance
  • The Node BeginFirmwareUpdate method has been renamed to UpdateFrimware, and requires a class instance.
  • The Node FirmwareUpdateProgress event now passes an args parameter
  • The Node FirmwareUpdateFinished event now passes an args parameter
  • Setting the Node name, location and keepAwake values is now only possible with methods for each.
    This is to address some unintentional communication between the Driver runtime and the lib.
  • The method GetAllEndpoints has been removed, and is replaced with an endpoints property

• New Features

  • Multiple Driver instances are now supported
  • Added ability to save ZWaveOptions to a JSON string and back
  • Added Long Range (LR) support
  • Added deviceConfig property to the Controller class.
  • Added SetRawConfigParameterValue method to the ZWaveNode class.
  • Added RefreshValues method to the ZWaveNode class.
  • Added RefreshCCValues method to the ZWaveNode class.
  • Added WaitForWakeUp method to the ZWaveNode class.
  • Added Ping, method to the ZwaveNode class.
  • Added StartListeningLogs, StopListeningLogs methods and the associated events to the Driver class.
  • Added ValueAdded, ValueRemoved events. ValueRemoved was never added until now, ValueAdded, previously used the ValueUpdated event
  • Added metadata updated event to the ZWaveNode class.
  • Added ManuallyIdleNotificationValue method to the ZWaveNode class.
  • Added endpointLabel to the Endpoint class
  • Added Interview method, to the ZWaveNode class - this should only be used if "disableOnNodeAdded" is set to true
  • Allow specifying Refresh Info options, when re-interviewing a node.
  • Added FirmwareUpdateOTW method (and supporting events) to update the Controller Firmware
  • Added SetRFRegion, GetRFRegion methods to the Controller class
  • Added SetPowerlevel, GetPowerlevel methods to the Controller class
  • Added GetAvailableFirmwareUpdates methods to the Controller class
  • Added ConfigManager methods to the Driver class
  • Added FirmwareUpdateOTA method to the Controller class, to update a node with the fetched Updates via GetAvailableFirmwareUpdates
  • Added HardReset method to the Driver class
    Warning!!! This will Reset your controller, and will result in a clean network with no included nodes.
  • Added SoftReset method to the Driver class
  • Added the ccSpecific property to the ValueMetadata class
  • Added the ability to add new server methods to the library during runtime.
    This is helpful if you want to use a method that is not yet implemented, or to support an older version of an exetrnal server

• Internal changes

  • Switched to an alternative websocket client package (which is now embedded)
  • Massive structural / performance improvements
  • All event handlers are now executed with their own Task instance
  • Better (hopefully) recovery/connection error handling
  • Updated some of the defaults in the Zwave Options to mirror the Driver defaults
  • Internal logic to ensure the server satifies the specified expected schema requested by the library

  Shoutout to...
  @spudwebb for the massive amounts of contribution for this release
  and @georgeinva2004 for testing the stuff I haven't (which is a lot 😬)
  and @AlCalzone for..... Ummm Zwave JS
  and @raman325 for the foundations needed to expose the Driver to other languages

[marcus-j-davies]

@spudwebb

I have bumped the schema - and Im thinking about doing a release on this (v4)
I have combined some of you recent commits.

• 6b99e30
• d275707
• 233343a

I merged them into a secondary PR I was working on (to address smart start inconstancies), and merged that PR to V4

This PR - should now be fully updated with your commits, and has the following versions.

• ZWave JS Driver Version: 14.3.7 (only really applies to Embedded setups)
• ZWave JS Server Version: 1.40.2 (Schema Version 40)

if connecting to a lesser version of the schema (since its now based on 40) - just use the override

public Driver(Uri Server, int SchemaVersion = 0, int ServerErrorThrottleTime = 10000)

Do you want to cast your eyes over it?

[marcus-j-davies]

@georgeinva2004

This MASSIVE update may get released this week - do you want to test it?

remember to build your PSI

cd ./PSI
npm install && npm run build

rename ./dist/server.exe to ./dist/server.psi, and distrubute the image with the library.

Note: it doesn't yet have the ability to load a PSI from another location.

[spudwebb]

@spudwebb

I have bumped the schema - and Im thinking about doing a release on this (v4) I have combined some of you recent commits.

• 6b99e30
• d275707
• 233343a

I merged them into a secondary PR I was working on (to address smart start inconstancies), and merged that PR to V4

This PR - should now be fully updated with your commits, and has the following versions.

• ZWave JS Driver Version: 14.3.7 (only really applies to Embedded setups)
• ZWave JS Server Version: 1.40.2 (Schema Version 40)

if connecting to a lesser version of the schema (since its now based on 40) - just use the override

public Driver(Uri Server, int SchemaVersion = 0, int ServerErrorThrottleTime = 10000)

Do you want to cast your eyes over it?

It looks good, but I won't be able to test it before next week.

[AlCalzone]

@marcus-j-davies you should probably bump the driver to 14.3.8. 14.3.7 has an issue with reading from cache.

[marcus-j-davies]

Thanks @AlCalzone for the heads up - Bumped!

[marcus-j-davies]

@spudwebb - Hope your well?

I'm going to be finishing up V4 today, and going to be moving to v5 right after (Branch already based on v4).
V4, will exist only for backwards compatibility for environments < .NET 5 (I.e to support your need)

But After V4 - it will drop support for older targets, V5 will get continued updates but will only support the modern targets

• net6.0
• net7.0
• net8.0
• net9.0
• netstandard2.1
• .... Next

I will be removing the embedded sockets library in v5 - as I need to bring it up to the latest code bases.
If you still need on going support for the latest driver version in V4, I think you may need to start maintaining your fork of V4.

I will bring V4 upto the latest Schema of course - but after that, V5 will be the active branch, where it will steer away from legacy frameworks - hence my suggestion to keep your own fork for V4.

tl;dr
V4 will be the last version to support net48, netstandard2.0

[spudwebb]

Fair enough, I will maintain my own fork of v4.

[marcus-j-davies]

Let me first bring v4 inline with the current schema (working on it at this very minute).
a few more methods are being added.

• Setting/Getting LR Power Level
• Toggle RF
• Node Info Received (NIF) event

I am also setting the ResultPayload value to the success property if it exists at the result,
as I sometimes set it to that, but others I don't - so want to make it consistent

 internal CMDResult(JObject Res)
       {
           this.Success = Res.Value<bool>("success");

           if (Res.ContainsKey("result"))
           {
               bool? success = Res.SelectToken("result.success")?.Value<bool?>();
               if (success.HasValue)
                   SetPayload(success.Value);
           }

           if(Res.ContainsKey("zwaveErrorCode"))
               this.ErrorCode = Res.Value<string>("zwaveErrorCode");

           if (Res.ContainsKey("zwaveErrorMessage"))
               this.Message = Res.Value<string>("zwaveErrorMessage");
       }

Meaning if you don't use SetPayload it will use result.success if it exists.
.success is the transaction its self. -so I think this needs clearing up.

Will tag you once those changes are pushed, so you can grab the latest v4 code

[marcus-j-davies]

@spudwebb

I am adding a new method to the CMDResult class in V4 - which removes the need to do manual casting (I find it annoying)

public T ResultPayloadAs<T>()
{
     return ResultPayload is T value ? value : default!;
}

Usage

Driver.Controller.Nodes.get(4).GetDefinedValueIDs().ContinueWith((R) =>{

    ValueID[] VIDs = R.Result.ResultPayloadAs<ValueID[]>()
    
    foreach(ValueID VID in VIDs){
         // Do something with VID (Value ID)
    }
})

Once again, I will ping you once V4 has been updated with all my changes & bumps to the schema

[marcus-j-davies]

@spudwebb

Do you want to now pull the latest V4 sources from the V4 branch?

• Driver version : 15.20.0
• PSI Server Version : 3.5.0 (schema 44)
• Added method (CMDResult) public T ResultPayloadAs<T>() - Removes the need to cast the result yourself
• Added method (Controller) SetMaxLongRangePowerlevel
• Added method (Controller) GetMaxLongRangePowerlevel
• Added method (Controller)ToggleRF
• Added event (ZWaveNode) NodeInfoEvent
• Some small result path corrections

Let me know if any issue.
This commit will likely be the last before I drop support for older versions of the .NET SDK and the embedded source of the WS lib.

I don't think this applies to you, but still:

To build the PSI

• Download a clean copy of the branch
• With in the PSI folder, issue the following
  • npm install
  • npm run build
  • Rename sever.exe to server.psi

[spudwebb]

Aren't you going to merge and release a v4 version before you switch to v5 and drop support for older versions of the .NET SDK ?

[marcus-j-davies]

Merged - Will be releasing to nuget soon.

[marcus-j-davies]

Published to NuGet!

It will be a lil while before the main branch has the V5 commits, so any issues with this release, do let me know, and I'll publish fixes as needed.

I would grab a copy of the main branch as it is now, so you can maintain backwards compatibility.