Grizzly - Z-Wave Library for Elixir

Grizzly is a library for working with Z-Wave devices. Z-Wave is a low-frequency radio protocol for controlling smart home devices on a mesh network. Grizzly leverages Z-Wave over IP (Z/IP) to communicate to Z-Wave devices via DTLS. Grizzly provides complete support for the various Z-Wave security groups, extensible device behavior, and reliable error isolation between device behaviors.

Hardware requirements are:

  1. Z-Wave bridge controller
  2. zipgaway binary from Silicon Labs
  3. A Nerves system, custom or official.

To get up and running fast with a raspberry pi 3 check out the grizzly quickstart.

The zipgateway binary will need to be cross-compiled for your target. This can be a bit tricky, so if you need help with this part of the setup process please reach out on the forum by using the grizzly tag.

Z-Wave is a complex protocol with many moving parts and pitfalls. We hope that Grizzly provides a simple API for handling these complexities. As home automation and IoT grows in popularity we are excited to help the Elixir ecosystem provide reliable solutions to hard problems in this space.

If you have questions please feel free to reach out on the forum using the grizzly tag.

Special thanks to SmartRent for their support in open sourcing Grizzly!

Happy IoT hacking!

27 Likes

Yay! I can’t wait to try it out! Big thanks to @mattludwigs and the entire SmartRent team!

:heart: :bear: :heart:

2 Likes

30%20AM

I can’t wait to try it out!

3 Likes

This is really really cool. I have been using Hypriot OS with elixir on docker containers to do home network stuff and was thinking about how to use z-wave with pi and elixir. I can’t wait to get this working.

By the way, if you want to get more people involved, I think you should announce Grizzly here: https://www.reddit.com/r/homeautomation/ Some people there would love this project.

2 Likes

Thank you! If you run into any issues getting setup feel free to ask a question.

Thanks for the suggestion, I will look into announcing it there too soon!

New release v0.4.3

  • Enhancements
    • Support Powerlevel command class
    • Doc clean up
    • Grizzly.send_command/2 and Grizzly.send_command/3
      can be passed a node id instead of a node.
2 Likes

New release v0.5.0

TLDR; Provides better error handling when trying to encode command arguments. Improves robustness of Grizzly.

Introduces Grizzly.Command.EncodeError exception and updates encoding and
decoding functions to return tagged tuples. We now use these things when trying
to send a command via Grizzly.send_command/3 so if you have invalid command
arguments we can provide useful error handling with
{:error, Grizzly.Command.EncodeError.t()}. The EncodeError.t() implements
Elixir’s exception behaviour so you can leverage the standard library to
work with the exception.

Unless you have implemented custom commands or used one of the many command
encoders or decodes explicitly this update should not affect you too much. If
you have used the encoder/decoders explicitly please see the documentation for
the ones you have used to see the updated API. If you have written a command we
encourage you to validate the arguments and return the {:error, EncodeError.t()}
to improve the usability of and robustness your command. The new
Grizzly.Command.Encoding module provides some useful functionality for
validating specs for command arguments.

  • Enhancements
    • Provide command argument validation and error handling via
      Grizzly.Command.EncodeError.()
    • Update all the command arg encoder/decoder to use tagged
      tuples for better handling of invalid command arguments
    • Introduces new Grizzly.Command.Encoding modules for helping
      validate command argument specifications
  • Fixes
    • Crashes when providing invalid command arguments

Big thanks to @jfcloutier for the hard work on this!

3 Likes

New Release: v0.6.0

Changed Grizzly.CommandClass.CommandClassVersion to Grizzly.CommandClass.Version
and changed Grizzly.ComamndClass.CommandClassVersion.Get to
Grizzly.CommandClass.Version.CommandClassGet as these names reflect the Z-Wave
specification better.

If you only have used Grizzly.get_command_class_version/2 and the related function
in Grizzly.Node module this change should not affect you.

  • Enhancements
    • Add support for:
      • MultiChannelAssociation Command Class
      • WakeUp Command Class NoMoreInformation command
      • Complete Association Command Class
      • ZwaveplusInfo Command Class
      • Version Get Command
    • Clean up docs
    • Renamed Grizzly.CommandClass.CommandClassVersion to Grizzly.CommandClass.Version
    • Renamed Grizzly.CommandClass.CommandClassVersion.Get to
      Grizzly.CommandClass.Version.CommandClassGet

Another shout out to @jfcloutier for adding more support to for commands and command classes!

New Release: v0.6.1

  • Enhancements
    • Update commands IntervalGet and ManufacturerSpecificGet to be more
      consistent
    • Better handling of invalid ManufacturerSpecific info received from
      devices
1 Like

New Release: v0.6.2

  • Enhancements
    • Remove the dependence on pidof allowing grizzly to work on any nerves
      device without the need of busybox
2 Likes

New Release: v0.6.3

  • Enhancements
    • Supports AssociationGroupInformation Command Class

v0.6.4

Added better validation in the UserCode.Set command to ensure that we are keeping to the Z-Wave specification. When you send in invalid user code params the Z-Wave spec is to ignore the command, which can lead to unexpected behavior.

v0.6.5

  • Enhancements
    • Support GetDSK command
    • Support FailedNodeRemove command
    • Allow zipgateway_path configuration
    • Generate the zipgateway.cfg to allow device specific
      information to be passed into the zipgateway runtime.
1 Like

v0.6.6

  • Fixes
    • Application start failure when providing the correct
      data structure to the zipgateway_cfg configuration
      field
2 Likes

v0.7.0

Introduces SmartStart support!

SmartStart will allow you to pair a device to a Z-Wave controller without
turning the device on. Devices that support SmartStart will have a device
specific key (DSK) that you can provide to the controller prior to turning on
the device.

iex> Grizzly.send_command(Grizzly.Controller, Grizzly.CommandClass.NodeProvisioning.Set, dsk: dsk)
:ok

After running the above command you can plug in your SmartStart device and the
controller will try to join the Z-Wave network automatically.

As a note, your controller might not have the necessary firmware to have SmartStart.

To verify this you can use RingLogger to read zipgateway logs which at the start
will log if the controller supports SmartStart.

Breaking Changes

Breaking change to the return value of sending Grizzly.CommandClass.ZipNd.InvNodeSolicitation.

When using that function send_command would return
{:ok, {:node_ip, node_id, ip_address}} but now it returns
{:ok, %{ip_address: ip_address, node_id: node_id, home_id: home_id}}.

  • Enhancements
    • SmartStart support through the NodeProvisioning command class
    • Added home_id field to Grizzly.Node.t()
    • Support fetching home_id of the Z-Wave nodes when fetching
      Z-Wave information about the node
1 Like

v0.8.0!

Adds support for handling SmartStart meta extension fields.

These fields give more information about the current status, inclusion methods,
and product information for the SmartStart device.

There are two breaking changes:

  1. All SmartStart meta extensions were moved from Grizzly.CommandClass.NodeProvisioning
    namespace into the Grizzly.SmartStart.MetaExtension namespace.
  2. Upon finalizing the meta extension behaviour and API we made changes to how
    previously supported meta extensions worked. Namely, we added a new/1
    callback that does parameter validation, and returns {:ok, MetaExtension.t()}.
    This breaks the previous behaviour of to_binary/1 functions in previously
    implemented meta extensions.
  • Enhancements
    • Full support for SmartStart meta extensions
    • Add meta_extensions field to Grizzly.CommandClass.NodeProvisioning
      commands that can handle meta extensions
    • Update Grizzly.Conn.Server.Config docs
  • Fixes
    • Invalid keep alive (heart beat) interval
    • Set correct constraints on Time command offset values

Thank you to those who contributed to this release:

  • Jean-Francois Cloutier
  • Ryan Winchester
4 Likes

v0.8.1!

  • Enhancements
    • Update docs and resources
  • Fixes
    • An issue when the unsolicited message server would cause a
      no match error that propagated up the supervision tree

Thank you to those who contributed to this release:

  • Ryan Winchester
4 Likes

v0.8.2

  • Enhancements
    • Support SWITCH_BINARY_REPORT version 2
1 Like

v0.8.3

  • Enhancements
    • Support Wake Up v2 and Multi Channel Association v3
3 Likes

v0.8.4

  • Fixes
    • Handle when there are no nodes in the node provisioning list when
      requesting all the DSKs.
1 Like