grizzly v0.8.5 Grizzly.Inclusion View Source

Z-Wave Inclusion Server

Overview

When using this process inclusion and exclusion are done asynchronously and information will be communicated via message passing.

By default this process will send information about the inclusion to the process that started the inclusion. However, if you pass the :client option into the call that points to a pid, messages will be sent to that process.

Move over, the caller can pass in the :timeout option in order to set the timeout of the inclusion. By default this is set to one minute.

Adding Nodes

Add

To add a node to the network this is what will be called:

Grizzly.Inclusion.add_node()

This will return :ok and set the Z-Wave module into add node mode.

You can use RingLogger.next to see the logs from grizzly and Grizzly to verify. In this example, whatever messages that are sent will go to the process who called this function. If you have a process that you what to filter all inclusion messages through you can run this:

Grizzly.Inclusion.add_node(client: some_pid)

This will then filter all messages to that client.

A notification will be broadcasted, and a message sent to the client, like this:

{:node_added, %Grizzly.Node{}}

Remove

To remove a node from the network this function should be called:

Grizzly.Inclusion.remove_node()

The :client option works like adding a node.

When removing a node is successful and complete, a notification will be broadcasted, and a message sent to the client, like this:

{:node_removed, node_id}

Where node_id is an integer of the node's id that was removed

If the node_id is 0, then the node was removed from another network and now can be included into this controller's network.

Stopping

This is useful for when an inclusion has started and the user wants to stop the inclusion process from taking place. The function to do this:

Grizzly.Inclusion.add_node_stop()

When this takes places the client will be sent a message like this:

:node_add_stopped

This is the same for removing a node but instead run this function:

Grizzly.Inclusion.remove_node_stop()

And this message will be sent to the client

:node_remove_stopped

Learn mode

It is necessary to put the controller into Learn mode for it to be included by another controller. This is required for certification testing.

Grizzly.Inclusion.start_learn_mode()

The :client option works like adding a node.

When being in Learn mode completes, a message sent to the client, like this:

{:learn_mode_set, %{status: :done, new_node_id: 4}}

When status is :done, new_node_id is the new node id taken by the controller (an integer other than 0).

When status is :failed or :security_failed, Learn mode completed without the controller being included.

Timeouts

By default the timeout is set to one minute, but the :timeout option can passed into to either add_node/1 or remove_node/1 in milliseconds to adjust the timeout.

When the time passes for the timeout to trigger the client will be sent two messages. The first is to let the client know that it timed out and the second is to confirm that the inclusion process was stopped on the Z-Wave module.

For when add_node was called, the messages look like:

{:timeout, :add_node}
:node_add_stopped

And for when remove_node was called, the messages look like:

{:timeout, :add_node}
:node_add_stopped

The controller will only stay in Learn mode for a limited amount of time. If the process times out before it completes (successfully or not), the Learn mode is aborted.

Errors

Errors are reported to the client as follows

{:error, :node_add_failed}
{:error, :node_add_stopped}
{:error, :node_remove_failed}
{:error, :node_remove_stopped}
{:error, :learn_mode_failed}
{:error, :learn_mode_stopped}

Link to this section Summary

Types

Options for inclusion and exclusion process

Functions

Start the process to add a node the network

Stop the process to add a node to the network

Returns a specification to start this module under a supervisor.

Remove a node from the network

Stop the remove node process from running

Put the controller in learn mode for a few seconds

Put the controller out of learn mode

Link to this section Types

Link to this type

invalid_opts_reason() View Source
invalid_opts_reason() :: :pin_required_for_s2_authentication | :pin_size_invalid

Link to this type

learn_mode_report() View Source
learn_mode_report() :: %{
  status: Grizzly.CommandClass.NetworkManagementBasic.learn_mode_status(),
  new_node_id: non_neg_integer()
}

Link to this type

opt() View Source
opt() ::
  {:client, pid()}
  | {:timeout, non_neg_integer()}
  | {:pin, non_neg_integer() | nil}
  | {:s2_keys, [Grizzly.Security.key()]}

Options for inclusion and exclusion process

  • :client - the process the messages from the inclusion will sent to (default self)
  • :timeout - the timeout interval for when to stop the adding/removing a node (default 60_000)
  • :pin - this is used for S2 authenticated, when doing S2 authenticated inclusion this should be the 5 digit number printed on the joining device.
  • :s2_keys - What keys to grant when the join node request keys, this will use the highest security group.

Link to this section Functions

Link to this function

add_node(opts \\ []) View Source
add_node([opt()]) :: :ok | {:error, {:invalid_option, invalid_opts_reason()}}

Start the process to add a node the network

Link to this function

add_node_stop(opts \\ []) View Source
add_node_stop([opt()]) :: :ok

Stop the process to add a node to the network

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

remove_node(opts \\ []) View Source
remove_node([opt()]) :: :ok

Remove a node from the network

Link to this function

remove_node_stop(opts \\ []) View Source
remove_node_stop([opt()]) :: :ok

Stop the remove node process from running

Link to this function

start_learn_mode(opts \\ []) View Source
start_learn_mode([opt()]) ::
  :ok | {:error, {:invalid_option, invalid_opts_reason()}}

Put the controller in learn mode for a few seconds

Put the controller out of learn mode