View Source Grizzly (grizzly v8.2.0)

Send commands, subscribe to unsolicited events, and other helpers.

Unsolicited Events

In order to receive unsolicited events from the Z-Wave network you must subscribe to the corresponding command (e.g. :battery_report, :alarm_report, etc.).

Whenever an unsolicited event is received from a device, subscribers will receive messages in the following format:

{:grizzly, :event, %Grizzly.Report{}}

The Grizzly.Report struct will contain the id of the sending node, a Grizzly.ZWave.Command struct with the command name and arguments, and any additional metadata. Refer to Grizzly.Report and Grizzly.ZWave.Command for details.

Telemetry

  • [:grizzly, :zip_gateway, :crash]

    • Description: Emitted when the Z/IP Gateway process exits abnormally.
    • Measurements: N/A
    • Metadata: N/A
  • [:grizzly, :zwave, :s2_resynchronization]

    • Description: Emitted when an S2 resynchronization event occurs.
    • Measurements: %{system_time: non_neg_integer()}
    • Metadata: %{node_id: non_neg_integer(), reason: non_neg_integer()}

Summary

Types

A custom handler for the command.

The response from sending a Z-Wave command.

Functions

Reports the gateway's current background RSSI (noise).

Whether Grizzly supports sending the given command with supervision.

List the supported Z-Wave commands for a particular command class.

Returns the network's home id. Returns nil if Grizzly is started with run_zipgateway: false or if Z/IP Gateway has not yet logged the home id.

Get the current inclusion status.

Guard for checking if device is a virtual device or not

List all supported Z-Wave commands.

Returns the network encryption keys. Returns nil if Grizzly is started with run_zipgateway: false or if Z/IP Gateway has not yet logged the network keys.

Return the options Grizzly.Supervisor was started with. Returns nil if supervisor is not started.

Sends a no-op command to the given node to check its reachability. Transmission stats are enabled by default.

Restarts the Z/IP Gateway process. An error will be raised if Grizzly.ZIPGateway.Supervisor is not running.

Send a raw binary to the Z-Wave node.

Send a command to the node via the node id or to Z/IP Gateway.

Stops the Z/IP Gateway process if it is running.

Subscribe to unsolicited events for the given command.

Subscribe to unsolicited events for multiple commands.

Subscribe to all events from a particular Z-Wave device.

Subscribe to all events from a group of Z-Wave devices.

Unsubscribe from an unsolicited event.

Delete a subscription created with subscribe_node/1.

Check to if the device id is a virtual device or a regular Z-Wave devices

Returns the network encryption keys formatted for use with the Zniffer application. See Grizzly.ZIPGateway.LogMonitor.zniffer_network_keys/1 for more information.

Types

@type command() :: atom()
@type command_opt() ::
  {:timeout, non_neg_integer()}
  | {:retries, non_neg_integer()}
  | {:handler, module() | handler_spec()}
  | {:transmission_stats, boolean()}
  | {:supervision?, boolean()}
  | {:status_updates?, boolean()}
  | {:mode, Grizzly.Connection.mode()}

Options for Grizzly.send_command/4.

  • :timeout - Time (in milliseconds) to wait for an ACK or report before timing out. Maximum 140 seconds. Default 15_000.
  • :retries - Number of retries in case the node responds with a NACK. Default 0.
  • :handler - A custom response handler (see Grizzly.CommandHandler). Ignored if supervision? is true.
  • :transmission_stats - If true, transmission stats will be included with the returned report (if available). Default false.
  • :supervision? - Whether to use Supervision CC encapsulation. Default false.
  • :status_updates? - If true, the calling process will receive messages when a supervision status update is received from the destination node. Default false.
  • :mode - The connection mode to use when sending the command. Defaults to :sync. Using :async will result in the returned Grizzly.Report always having a type of :queued_delay.
@type handler() :: module() | handler_spec()
@type handler_spec() :: {module(), args :: any()}

A custom handler for the command.

See the Grizzly.CommandHandler behaviour for more documentation.

@type node_id() :: non_neg_integer()
@type send_command_error() ::
  :including | :firmware_updating | :nack_response | :queue_full | :timeout
Link to this type

send_command_response()

View Source
@type send_command_response() ::
  {:ok, Grizzly.Report.t()} | {:error, send_command_error()}

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.

Including

An :including response means that the controller is in inclusion, exclusion, or learn mode and cannot process any commands. Either cancel the inclusion (see Grizzly.Inclusions) or wait until the inclusion is complete before trying again.

Nack response

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 (e.g. due to a factory reset).

By default, Grizzly will retry the command twice before sending returning a :nack_response. This is configurable via the :retries command option in the Grizzly.send_command/4 function. This helps increase the reliability of sending commands during Z-Wave network congestion.

Queue full

Sleeping devices can only receive commands when they are wake up, so Z/IP Gateway queues commands to be sent when it receives a wake up notification from the device. However, it will only queue a limited number of commands. A :queue_full response is returned in this situation.

@type seq_number() :: non_neg_integer()

Functions

@spec background_rssi() ::
  {:ok, [Grizzly.ZWave.Commands.RssiReport.param()]} | {:error, any()}

Reports the gateway's current background RSSI (noise).

Link to this function

can_supervise_command?(command_name)

View Source
@spec can_supervise_command?(command()) :: boolean()

Whether Grizzly supports sending the given command with supervision.

Link to this function

commands_for_command_class(command_class_name)

View Source
@spec commands_for_command_class(atom()) :: [atom()]

List the supported Z-Wave commands for a particular command class.

@spec home_id() :: binary() | nil

Returns the network's home id. Returns nil if Grizzly is started with run_zipgateway: false or if Z/IP Gateway has not yet logged the home id.

@spec inclusion_status() :: Grizzly.Inclusions.status()

Get the current inclusion status.

Link to this macro

is_virtual_device(device_id)

View Source (macro)

Guard for checking if device is a virtual device or not

@spec list_commands() :: [atom()]

List all supported Z-Wave commands.

@spec network_keys() ::
  [{Grizzly.ZIPGateway.LogMonitor.network_key_type(), binary()}] | nil

Returns the network encryption keys. Returns nil if Grizzly is started with run_zipgateway: false or if Z/IP Gateway has not yet logged the network keys.

@spec options() :: Grizzly.Options.t() | nil

Return the options Grizzly.Supervisor was started with. Returns nil if supervisor is not started.

Link to this function

ping(node_id, opts \\ [])

View Source

Sends a no-op command to the given node to check its reachability. Transmission stats are enabled by default.

@spec restart_zipgateway() :: :ok

Restarts the Z/IP Gateway process. An error will be raised if Grizzly.ZIPGateway.Supervisor is not running.

Link to this function

send_binary(node_id, binary)

View Source
@spec send_binary(Grizzly.ZWave.node_id(), binary()) ::
  :ok | {:error, :including | :firmware_updating}

Send a raw binary to the Z-Wave node.

This function does not block and expects the sending process to handle the lifecycle of the command being sent. This maximizes control but minimizes safety and puts things such as timeouts, retries, and response handling in the hand of the calling process.

When sending a binary command to a Z-Wave node, the binary must be encapsulated in a Z/IP Packet (see Grizzly.ZWave.Commands.ZIPPacket).

seq_no = 0x01
{:ok, my_command} = Grizzly.ZWave.Commands.SwitchBinaryGet.new()
{:ok, packet} = Grizzly.ZWave.Commands.ZIPPacket.with_zwave_command(my_command, seq_no)
binary = Grizzly.ZWave.to_binary(packet)

Grizzly.send_binary(node_id, binary)

This can be useful when you need very fine-grained control of the outgoing Z/IP Packet, if you need to send a command that has not been implemented in Grizzly yet (contributions are welcome!), or for debugging purposes.

After sending a binary packet the calling process will receive a message in the form of:

{:grizzly, :binary_response, <<...>>}
Link to this function

send_command(node_id, command_name, args \\ [], opts \\ [])

View Source
@spec send_command(
  Grizzly.ZWave.node_id() | :gateway | Grizzly.VirtualDevices.id(),
  command(),
  args :: list(),
  [command_opt()]
) :: send_command_response()

Send a command to the node via the node id or to Z/IP Gateway.

Arguments

  • node_id - The node id to send the command to. If :gateway is passed, the command will be sent to the locally running Z/IP Gateway -- this is useful if this controller has a node id other than 1.

  • command - The command to send. See Grizzly.Commands.Table for a list of available commands and their associated modules.

  • args - A list of arguments to pass to the command. See the associated command module for details.

  • opts - A keyword list of options to control how the command is sent and processed. See Grizzly.command_opt/0 for details.

Usage

# A command with no arguments or options:
Grizzly.send_command(node_id, :switch_binary_get)

# ... with arguments:
Grizzly.send_command(node_id, :switch_binary_set, value: :off)

# ... with arguments and options:
Grizzly.send_command(node_id, :switch_binary_get, [], timeout: 10_000, retries: 5)

Return values and errors

Following are the most common return values and errors that you will see. For a complete list, see Grizzly.send_command_response/0.

  • {:ok, Grizzly.Report.t()} - the command was sent and the Z-Wave device responded with an ACK or a report. See Grizzly.Report for more information.
  • {:error, :including} - the Z-Wave controller is currently in inclusion or exclusion mode
  • {:error, :firmware_updating} - the Z-Wave controller is undergoing a firmware update
  • {:error, reason} - see Grizzly.send_command_response/0
@spec stop_zipgateway() :: :ok

Stops the Z/IP Gateway process if it is running.

Link to this function

subscribe_command(command_name)

View Source
@spec subscribe_command(command()) :: :ok

Subscribe to unsolicited events for the given command.

Link to this function

subscribe_commands(command_names)

View Source
@spec subscribe_commands([command()]) :: :ok

Subscribe to unsolicited events for multiple commands.

Subscribe to all events from a particular Z-Wave device.

NOTE: Subscribers using both subscribe_node and subscribe_command will receive duplicate messages.

Link to this function

subscribe_nodes(node_ids)

View Source
@spec subscribe_nodes([node_id() | Grizzly.VirtualDevices.id()]) :: :ok

Subscribe to all events from a group of Z-Wave devices.

NOTE: Subscribers using both subscribe_node and subscribe_command will receive duplicate messages.

Link to this function

unsubscribe_command(command_name)

View Source
@spec unsubscribe_command(command()) :: :ok

Unsubscribe from an unsolicited event.

Link to this function

unsubscribe_node(node_id)

View Source

Delete a subscription created with subscribe_node/1.

Link to this function

virtual_device?(device_id)

View Source
@spec virtual_device?(
  :gateway
  | Grizzly.ZWave.node_id()
  | Grizzly.VirtualDevices.id()
) :: boolean()

Check to if the device id is a virtual device or a regular Z-Wave devices

@spec zniffer_network_keys() :: binary() | nil

Returns the network encryption keys formatted for use with the Zniffer application. See Grizzly.ZIPGateway.LogMonitor.zniffer_network_keys/1 for more information.