grizzly v0.8.2 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.
Moverover, the caller can pass in the :timeout
option inorder 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
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
invalid_opts_reason()
View Source
invalid_opts_reason() :: :pin_required_for_s2_authentication | :pin_size_invalid
invalid_opts_reason() :: :pin_required_for_s2_authentication | :pin_size_invalid
learn_mode_report()
View Source
learn_mode_report() :: %{
status: Grizzly.CommandClass.NetworkManagementBasic.learn_mode_status(),
new_node_id: non_neg_integer()
}
learn_mode_report() :: %{ status: Grizzly.CommandClass.NetworkManagementBasic.learn_mode_status(), new_node_id: non_neg_integer() }
opt()
View Source
opt() ::
{:client, pid()}
| {:timeout, non_neg_integer()}
| {:pin, non_neg_integer() | nil}
| {:s2_keys, [Grizzly.Security.key()]}
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 (defaultself
):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
add_node(opts \\ [])
View Source
add_node([opt()]) :: :ok | {:error, {:invalid_option, invalid_opts_reason()}}
add_node([opt()]) :: :ok | {:error, {:invalid_option, invalid_opts_reason()}}
Start the process to add a node the network
add_node_stop(opts \\ [])
View Source
add_node_stop([opt()]) :: :ok
add_node_stop([opt()]) :: :ok
Stop the process to add a node to the network
child_spec(init_arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
remove_node(opts \\ [])
View Source
remove_node([opt()]) :: :ok
remove_node([opt()]) :: :ok
Remove a node from the network
remove_node_stop(opts \\ [])
View Source
remove_node_stop([opt()]) :: :ok
remove_node_stop([opt()]) :: :ok
Stop the remove node process from running
start_learn_mode(opts \\ [])
View Source
start_learn_mode([opt()]) ::
:ok | {:error, {:invalid_option, invalid_opts_reason()}}
start_learn_mode([opt()]) :: :ok | {:error, {:invalid_option, invalid_opts_reason()}}
Put the controller in learn mode for a few seconds
start_link(_) View Source
stop_learn_mode(opts) View Source
Put the controller out of learn mode