Reports from Z-Wave commands

When you send a command in Z-Wave you will receive a report back.

When Things Go Well

There are two primary reports that are returned when sending a command.

The first is :command report and the second is an :ack_response report. These both will have a status of :complete.

Normally, an :ack_response report is returned when you set a value on a device. This means the device received the command and is processing it, not that the device has already processed it. You might have to go read the value back after setting it if you want to make the device ran the set based command.

A :command report type is returned often after reading a value from a device. This report will have its :command field filled with a Z-Wave command.

case Grizzly.send_command(node_id, command, command_args, command_opts) do
  {:ok, %Grizzly.Report{status: :complete, type: :command} = report} ->
    # do something withe report.command
  {:ok, %Grizzly.Report{status: :complete, type: :ack_response}} ->
    # do whatever
end

Queued Commands

When sending a command to a device that sleeping, normally battery powered devices, the command will be queued internally. The command will still be considered :inflight as it has not reached the device yet. You know when a command has been queued when the report's :status field is :inflight and the :type field is :queued_delayed. Fields to help you manage queued commands are :command_ref, :queued_delay, and :node_id

During the command's queued lifetime the system sends pings back to the caller to ensure that the low level connection is still established. This also provides an updated delayed time before the device wakes up.

case Grizzly.send_command(node_id, command, command_args, command_opts) do
  {:ok, %Grizzly.Report{status: :inflight, type: :queued_delay}} ->
    # the command was just queued
end

Once the command has been queued the calling process will receive messages about the queued command like so:

{:grizzly, :report, %Report{}}

This report can take two forms. One for a completed queued command and one for a queued ping.

def handle_info({:grizzly, :report, report}, state) do
  case report do
    %Grizzly.Report{status: :inflight, type: :queued_ping} ->
      # handle the ping if you want
      # an updated queue delay will be found in the :queued_delay
      # field of the report
    %Grizzly.Report{status: :complete, type: :command, queued: true} ->
      # here if the :queued field is marked has true and the report is
      # complete that will indicate a command has made it to the sleeping
      # device and the device has received the command
    %Grizzly.Report{status: :complete, type: :timeout, queued: true} ->
      # The woke up and the controller sent the command but for reason
      # the command's processing timed out
  end
end

Timeouts

If sending the command times out you will get a command with the :type of :timeout

case Grizzly.send_command(node_id, command, command_args, command_opts) do
  {:ok, %Grizzly.Report{status: :complete, type: :timeout}} ->
    # handle the timeout
end

The reason why this is considered okay is because the command that was sent was valid and we were able to establish a connect to the desired device but it just did not provide any report back.

Full Example

The below example shows the various ways one might match after calling Grizzly.send_command/4.

case Grizzly.send_command(node_id, command, command_args, command_opts) do
  {:ok, %Grizzly.Report{status: :complete, type: :command} = report} ->
    handle_complete_report(report)
  {:ok, %Grizzly.Report{status: :complete, type: :ack_response} = report} ->
    handle_complete_report(report)
  {:ok, %Grizzly.Report{status: :complete, type: :timeout} = report} ->
    handle_timeout(report)
  {:ok, %Grizzly.Report{status: :inflight, type: :queued} = report} ->
    handle_queued_command(report)
end

note: the handle_* functions will need to implemented and are only used in the example for illustration purposes