grizzly v0.15.3 Grizzly View Source
Send commands to Z-Wave devices
Grizzly provides the send_command
function as the way to send a command to
Z-Wave devices.
The send_command
function takes the node id that you are trying to send a
command to, the command name, and optionally command arguments and command
options.
A basic command that has no options or arguments looks like this:
Grizzly.send_command(node_id, :switch_binary_get)
A command with command arguments:
Grizzly.send_command(node_id, :switch_binary_set, value: :off)
Also, a command can have options.
Grizzly.send_command(node_id, :switch_binary_get, [], timeout: 10_000, retries: 5)
Some possible return values from send_command
are:
{:ok, Grizzly.Report.t()}
- the command was sent and the Z-Wave device responded with a report. SeeGrizzly.Report
for more information.{:error, :including}
- current the Z-Wave controller is adding or removing a device and commands cannot be processed right now{:error, :firmware_updating}
- current the Z-Wave controller is updating firmware and commands cannot be processed right now{:error, reason}
- there was some other reason for an error, two common ones are::nack_response
For a more detailed explanation of the responses from a send_command
call
see the typedoc for Grizzly.send_command_response()
.
Events from Z-Wave
Events generating from a Z-Wave device, for example a motion detected event,
can be handled via the Grizzly.subscribe_command/1
and
Grizzly.subscribe_commands/1
functions. This will allow you to subscribe
to specific commands. When the command is received from the Z-Wave network
it will placed in a Grizzly.Report
and set to the subscribing process. The
node that generated the report can be accessed with the :node_id
field in
the report.
iex> Grizzly.subscribe_command(:battery_report)
# sometime latter
iex> flush
{:grizzly, :event, %Grizzly.Report{command: %Grizzly.ZWave.Command{name: :battery_report}}}
Link to this section Summary
Functions
List the command for a particular command class
List the support commands
Send a command to the node via the node id
Subscribe to a command event from a Z-Wave device
Subscribe to many events from a Z-Wave device
Unsubscribe to an event
Link to this section Types
Specs
command() :: atom()
Specs
command_opt() :: {:timeout, non_neg_integer()} | {:retries, non_neg_integer()} | {:handler, handler()} | {:transmission_stats, boolean()}
Specs
A custom handler for the command.
See Grizzly.CommandHandler
behaviour for more documentation.
Specs
node_id() :: non_neg_integer()
Specs
send_command_response() :: {:ok, Grizzly.Report.t()} | {:error, :including | :updating_firmware | :nack_response | any()}
The response from sending a Z-Wave command
When everything is okay the response will be {:ok, Grizzly.Report{}}
. For
documentation about a report see Grizzly.Report
module.
When there are errors the response will be in the pattern of
{:error, reason}
.
Three reasons that Grizzly supports for all commands are :nack_response
,
:update_firmware
, and :including
.
A :nack_response
normally means that the Z-Wave node that you were trying
to send a command to is unreachable and did not receive your command at all.
This could mean that the Z-Wave network is overloaded and you should reissue
the command, the device is too far from the controller, or the device is no
longer part of the Z-Wave network.
Grizzly by default will try a command 3 times before sending returning a
:nack_response
. This is configurable via the :retries
command option in
the Grizzly.send_command/4
function. This is useful if you are going to
have a known spike in Z-Wave traffic.
In you receive the reason for the error to be :including
that means the
controller is in an inclusion state and your command will be dropped if we
tried to send it. So we won't allow sending a Z-Wave command during an
inclusion. It's best to wait and try again once your application is done
trying to include.
Specs
seq_number() :: non_neg_integer()
Link to this section Functions
Specs
List the command for a particular command class
Specs
list_commands() :: [atom()]
List the support commands
Specs
send_command(Grizzly.ZWave.node_id(), command(), args :: list(), [command_opt()]) :: send_command_response()
Send a command to the node via the node id
Specs
subscribe_command(command()) :: :ok
Subscribe to a command event from a Z-Wave device
Specs
subscribe_commands([command()]) :: :ok
Subscribe to many events from a Z-Wave device
Specs
unsubscribe_command(command()) :: :ok
Unsubscribe to an event