Use seconds or :default to give the duration when setting a switch

Whether a binary or multilevel switch,
instead of passing the duration pre-encoded.

Required for certification

[SRH-1797]

Author: jfcloutier

lib/grizzly/zwave/command_classes/switch_support.ex

@@ -0,0 +1,43 @@
+defmodule Grizzly.ZWave.CommandClasses.SwitchSupport do
+  @moduledoc """
+  Support for Switch Binary and Switch Multilevel Command Classes
+  """
+
+  alias Grizzly.ZWave.DecodeError
+
+  # Duration in seconds, or the manufacturer's default
+  @type duration :: :default | 0..7620
+
+  # Duration encoding
+  #   * 0 -> instantly
+  #   * 1..127 -> seconds
+  #   * 128..254 -> minutes + 127
+  #   * 255 -> factory default (option v2)
+  @doc """
+  Encode a duration into a byte according to the Z-Wave specs
+  """
+  @spec duration_to_byte(duration()) :: byte()
+  def duration_to_byte(:default), do: 255
+  def duration_to_byte(seconds) when seconds in 0..127, do: seconds
+
+  def duration_to_byte(seconds) when seconds in 128..7620 do
+    minutes = div(seconds, 60)
+    127 + minutes
+  end
+
+  # Force duration values within supported bounds
+  def duration_to_byte(seconds) when seconds > 7620, do: 254
+  def duration_to_byte(seconds) when seconds < 0, do: 0
+
+  @doc """
+  Decode a duration from a byte according to the Z-Wave specs
+  """
+  @spec duration_from_byte(byte()) ::
+          {:error, DecodeError.t()} | {:ok, duration()}
+  def duration_from_byte(255), do: {:ok, :default}
+  def duration_from_byte(byte) when byte in 0..127, do: {:ok, byte}
+  def duration_from_byte(byte) when byte in 128..254, do: {:ok, (byte - 127) * 60}
+
+  def duration_from_byte(byte),
+    do: {:error, %DecodeError{value: byte, param: :duration, command: :switch_multilevel_report}}
+end

lib/grizzly/zwave/commands/switch_binary_report.ex

@@ -5,17 +5,22 @@ defmodule Grizzly.ZWave.Commands.SwitchBinaryReport do
   Params:
 
     * `:target_value` - `:on`, `:off`, or `:unknown` (required)
-    * `:duration` - 0-255 (required V2)
     * `:current_value` - `:on`, `:off`, or `:unknown` (required V2)
+    * `:duration` - How long in seconds the switch should take to reach target value or the factory default (:default)
+                    Beyond 127 seconds, the duration is truncated to the minute. E.g. 179s is 2 minutes and 180s is 3 minutes
+                    (required V2)
   """
   @behaviour Grizzly.ZWave.Command
 
   alias Grizzly.ZWave.{Command, DecodeError}
-  alias Grizzly.ZWave.CommandClasses.SwitchBinary
+  alias Grizzly.ZWave.CommandClasses.{SwitchBinary, SwitchSupport}
 
   @type value() :: :on | :off | :unknown
 
-  @type param() :: {:target_value, value()} | {:duration, byte()} | {:current_value, value()}
+  @type param() ::
+          {:target_value, value()}
+          | {:duration, SwitchSupport.duration()}
+          | {:current_value, value()}
 
   @impl Grizzly.ZWave.Command
   def new(opts) do
@@ -41,8 +46,9 @@ defmodule Grizzly.ZWave.Commands.SwitchBinaryReport do
 
       current_value ->
         duration = Command.param!(command, :duration)
+        duration_byte = SwitchSupport.duration_to_byte(duration)
         current_value_byte = encode_target_value(current_value)
-        <<current_value_byte, target_value_byte, duration>>
+        <<current_value_byte, target_value_byte, duration_byte>>
     end
   end
 
@@ -61,9 +67,11 @@ defmodule Grizzly.ZWave.Commands.SwitchBinaryReport do
     end
   end
 
-  def decode_params(<<current_value, target_value, duration>>) do
+  def decode_params(<<current_value, target_value, duration_byte>>) do
     with {:ok, target_value} <- value_from_byte(target_value),
-         {:ok, current_value} <- value_from_byte(current_value) do
+         {:ok, duration} <- SwitchSupport.duration_from_byte(duration_byte),
+         {:ok, current_value} <-
+           value_from_byte(current_value) do
       {:ok,
        [
          target_value: target_value,

lib/grizzly/zwave/commands/switch_binary_set.ex

@@ -4,15 +4,17 @@ defmodule Grizzly.ZWave.Commands.SwitchBinarySet do
 
   Params:
 
-    * `:target_value` - `:on` or `:off`(required)
-    * `:duration` - 0-255 (optional v2)
+  * `:target_value` - `:on` or `:off`(required)
+  * `:duration` - How long in seconds the switch should take to reach target value or the factory default (:default)
+                  Beyond 127 seconds, the duration is truncated to the minute. E.g. 179s is 2 minutes and 180s is 3 minutes
+                  (optional V2)
   """
   @behaviour Grizzly.ZWave.Command
 
   alias Grizzly.ZWave.{Command, DecodeError}
-  alias Grizzly.ZWave.CommandClasses.SwitchBinary
+  alias Grizzly.ZWave.CommandClasses.{SwitchBinary, SwitchSupport}
 
-  @type param :: {:target_value, non_neg_integer()} | {:duration, non_neg_integer()}
+  @type param :: {:target_value, :on | :off} | {:duration, SwitchSupport.duration()}
 
   @impl Grizzly.ZWave.Command
   def new(opts) do
@@ -36,7 +38,8 @@ defmodule Grizzly.ZWave.Commands.SwitchBinarySet do
       nil ->
         <<target_value_byte>>
 
-      duration_byte ->
+      duration ->
+        duration_byte = SwitchSupport.duration_to_byte(duration)
         <<target_value_byte, duration_byte>>
     end
   end
@@ -55,11 +58,11 @@ defmodule Grizzly.ZWave.Commands.SwitchBinarySet do
     end
   end
 
-  def decode_params(<<target_value_byte, duration>>) do
-    case target_value_from_byte(target_value_byte) do
-      {:ok, target_value} ->
-        {:ok, [target_value: target_value, duration: duration]}
-
+  def decode_params(<<target_value_byte, duration_byte>>) do
+    with {:ok, target_value} <- target_value_from_byte(target_value_byte),
+         {:ok, duration} <- SwitchSupport.duration_from_byte(duration_byte) do
+      {:ok, [target_value: target_value, duration: duration]}
+    else
       {:error, %DecodeError{}} = error ->
         error
     end

lib/grizzly/zwave/commands/switch_multilevel_report.ex

@@ -5,15 +5,17 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelReport do
   Params:
 
     * `:value` - `:off`, 0 (off) and 99 (100% on), or `:unknown`
-    * `:duration` - How long the switch should take to reach target value, 0 -> instantly, 1..127 -> seconds, 128..253 -> minutes, 255 -> unknown (optional v2)
+    * `:duration` - How long in seconds the switch should take to reach target value or the factory default (:default)
+                    Beyond 127 seconds, the duration is truncated to the minute. E.g. 179s is 2 minutes and 180s is 3 minutes
+                    (optional v2)
   """
 
   @behaviour Grizzly.ZWave.Command
   require Logger
   alias Grizzly.ZWave.{Command, DecodeError}
-  alias Grizzly.ZWave.CommandClasses.SwitchMultilevel
+  alias Grizzly.ZWave.CommandClasses.{SwitchMultilevel, SwitchSupport}
 
-  @type param :: {:value, 0..99 | :off | :unknown} | {:duration, non_neg_integer()}
+  @type param :: {:value, 0..99 | :off | :unknown} | {:duration, SwitchSupport.duration()}
 
   @impl Grizzly.ZWave.Command
   @spec new([param()]) :: {:ok, Command.t()}
@@ -38,7 +40,8 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelReport do
         <<value_byte>>
 
       # version 2
-      duration_byte ->
+      duration ->
+        duration_byte = SwitchSupport.duration_to_byte(duration)
         <<value_byte, duration_byte>>
     end
   end
@@ -59,25 +62,26 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelReport do
   end
 
   # version 2
-  def decode_params(<<value_byte, duration>>) do
-    case value_from_byte(value_byte) do
-      {:ok, value} ->
-        {:ok, [value: value, duration: duration]}
-
+  def decode_params(<<value_byte, duration_byte>>) do
+    with {:ok, value} <- value_from_byte(value_byte),
+         {:ok, duration} <- SwitchSupport.duration_from_byte(duration_byte) do
+      {:ok, [value: value, duration: duration]}
+    else
       {:error, %DecodeError{}} = error ->
         error
     end
   end
 
   # version 4
-  def decode_params(<<value_byte, target_value_byte, duration, rest::binary>>) do
+  def decode_params(<<value_byte, target_value_byte, duration_byte, rest::binary>>) do
     if byte_size(rest) > 0 do
       Logger.warning(
         "[Grizzly] Unexpected trailing bytes in SwitchMultilevelReport: #{inspect(rest)}"
       )
     end
 
     with {:ok, value} <- value_from_byte(value_byte),
+         {:ok, duration} <- SwitchSupport.duration_from_byte(duration_byte),
          {:ok, target_value} <- value_from_byte(target_value_byte) do
       {:ok,
        [

lib/grizzly/zwave/commands/switch_multilevel_set.ex

@@ -5,20 +5,17 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelSet do
   Params:
 
     * `:target_value` - '`:off`, `:previous` or a value between 0 and 99
-    * `:duration` - How long the switch should take to reach target value,
-      * 0 -> instantly
-      * 1..127 -> seconds
-      * 128..254 -> minutes + 127
-      * 255 -> factory default (option v2)
-
+    * `:duration` - How long in seconds the switch should take to reach target value or the factory default (:default)
+                    Beyond 127 seconds, the duration is truncated to the minute. E.g. 179s is 2 minutes and 180s is 3 minutes
+                    (optional v2)
   """
 
   @behaviour Grizzly.ZWave.Command
 
   alias Grizzly.ZWave.{Command, DecodeError}
-  alias Grizzly.ZWave.CommandClasses.SwitchMultilevel
+  alias Grizzly.ZWave.CommandClasses.{SwitchMultilevel, SwitchSupport}
 
-  @type param :: {:target_value, :off | :previous | 0..99} | {:duration, 0..255}
+  @type param :: {:target_value, :off | :previous | 0..99} | {:duration, SwitchSupport.duration()}
 
   @impl Grizzly.ZWave.Command
   @spec new([param()]) :: {:ok, Command.t()}
@@ -43,7 +40,8 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelSet do
       nil ->
         <<target_value_byte>>
 
-      duration_byte ->
+      duration ->
+        duration_byte = SwitchSupport.duration_to_byte(duration)
         <<target_value_byte, duration_byte>>
     end
   end
@@ -66,11 +64,11 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelSet do
     end
   end
 
-  def decode_params(<<target_value_byte, duration>>) do
-    case target_value_from_byte(target_value_byte) do
-      {:ok, target_value} ->
-        {:ok, [target_value: target_value, duration: duration]}
-
+  def decode_params(<<target_value_byte, duration_byte>>) do
+    with {:ok, target_value} <- target_value_from_byte(target_value_byte),
+         {:ok, duration} <- SwitchSupport.duration_from_byte(duration_byte) do
+      {:ok, [target_value: target_value, duration: duration]}
+    else
       {:error, %DecodeError{}} = error ->
         error
     end

test/grizzly/zwave/commands/switch_binary_report_test.exs

@@ -23,6 +23,23 @@ defmodule Grizzly.ZWave.Commands.SwitchBinaryReportTest do
       assert <<0x25, 0x03, 0xFE>> == ZWave.to_binary(report)
     end
 
+    test "encodes duration param correctly" do
+      params = [current_value: :on, target_value: :off, duration: 10]
+      {:ok, command} = SwitchBinaryReport.new(params)
+      expected_binary = <<0xFF, 0x00, 0x0A>>
+      assert expected_binary == SwitchBinaryReport.encode_params(command)
+
+      params = [current_value: :on, target_value: :off, duration: :default]
+      {:ok, command} = SwitchBinaryReport.new(params)
+      expected_binary = <<0xFF, 0x00, 0xFF>>
+      assert expected_binary == SwitchBinaryReport.encode_params(command)
+
+      params = [current_value: :on, target_value: :off, duration: 180]
+      {:ok, command} = SwitchBinaryReport.new(params)
+      expected_binary = <<0xFF, 0x00, 0x82>>
+      assert expected_binary == SwitchBinaryReport.encode_params(command)
+    end
+
     test "decodes correctly on" do
       binary = <<0x25, 0x03, 0xFF>>
       expected_report = SwitchBinaryReport.new(target_value: :on)

test/grizzly/zwave/commands/switch_multilevel_report_test.exs

@@ -20,6 +20,16 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelReportTest do
     {:ok, command} = SwitchMultilevelReport.new(params)
     expected_binary = <<0x63, 0x0A>>
     assert expected_binary == SwitchMultilevelReport.encode_params(command)
+
+    params = [value: 99, duration: :default]
+    {:ok, command} = SwitchMultilevelReport.new(params)
+    expected_binary = <<0x63, 0xFF>>
+    assert expected_binary == SwitchMultilevelReport.encode_params(command)
+
+    params = [value: 99, duration: 180]
+    {:ok, command} = SwitchMultilevelReport.new(params)
+    expected_binary = <<0x63, 0x82>>
+    assert expected_binary == SwitchMultilevelReport.encode_params(command)
   end
 
   test "decodes v1 params correctly" do
@@ -33,6 +43,16 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelReportTest do
     {:ok, params} = SwitchMultilevelReport.decode_params(binary_params)
     assert Keyword.get(params, :value) == 0x32
     assert Keyword.get(params, :duration) == 0x0A
+
+    binary_params = <<0x32, 0xFF>>
+    {:ok, params} = SwitchMultilevelReport.decode_params(binary_params)
+    assert Keyword.get(params, :value) == 0x32
+    assert Keyword.get(params, :duration) == :default
+
+    binary_params = <<0x32, 0x81>>
+    {:ok, params} = SwitchMultilevelReport.decode_params(binary_params)
+    assert Keyword.get(params, :value) == 0x32
+    assert Keyword.get(params, :duration) == 120
   end
 
   test "decodes v4 params correctly" do

test/grizzly/zwave/commands/switch_multilevel_set_test.exs

@@ -20,6 +20,16 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelSetTest do
     {:ok, command} = SwitchMultilevelSet.new(params)
     expected_binary = <<0x63, 0x0A>>
     assert expected_binary == SwitchMultilevelSet.encode_params(command)
+
+    params = [target_value: 99, duration: :default]
+    {:ok, command} = SwitchMultilevelSet.new(params)
+    expected_binary = <<0x63, 0xFF>>
+    assert expected_binary == SwitchMultilevelSet.encode_params(command)
+
+    params = [target_value: 99, duration: 180]
+    {:ok, command} = SwitchMultilevelSet.new(params)
+    expected_binary = <<0x63, 0x82>>
+    assert expected_binary == SwitchMultilevelSet.encode_params(command)
   end
 
   test "encodes v2 params correctly - accept level 100" do
@@ -40,5 +50,15 @@ defmodule Grizzly.ZWave.Commands.SwitchMultilevelSetTest do
     {:ok, params} = SwitchMultilevelSet.decode_params(binary_params)
     assert Keyword.get(params, :target_value) == 0x32
     assert Keyword.get(params, :duration) == 0x0A
+
+    binary_params = <<0x32, 0xFF>>
+    {:ok, params} = SwitchMultilevelSet.decode_params(binary_params)
+    assert Keyword.get(params, :target_value) == 0x32
+    assert Keyword.get(params, :duration) == :default
+
+    binary_params = <<0x32, 0x81>>
+    {:ok, params} = SwitchMultilevelSet.decode_params(binary_params)
+    assert Keyword.get(params, :target_value) == 0x32
+    assert Keyword.get(params, :duration) == 120
   end
 end