lib/grizzly/zwave/smart_start/meta_extension.ex

defmodule Grizzly.ZWave.SmartStart.MetaExtension do
  @moduledoc """
  Meta Extensions for SmartStart devices for QR codes and node provisioning
  list
  """

  alias Grizzly.ZWave
  alias Grizzly.ZWave.{DeviceClasses, IconType, Security}
  alias Grizzly.ZWave.SmartStart.MetaExtension.UUID16

  import Bitwise

  @advanced_joining 0x35
  @bootstrapping_mode 0x36
  @location_information 0x33
  @max_inclusion_request_interval 0x02
  @name_information 0x32
  @network_status 0x37
  @product_id 0x01
  @product_type 0x00
  @smart_start_inclusion_setting 0x34
  @uuid16 0x03

  @typedoc """
  Unsigned 16 bit integer
  """
  @type unit_16() :: char()

  @typedoc """
  The mode to use when including the node advertised in the provisioning list

  - `:security_2` - the node must be manually set to learn mode and follow the
    S2 bootstrapping instructions
  - `:smart_start` - the node will use S2 bootstrapping automatically using the
    SmartStart functionality
  - `:long_range` - included the device using the Z-Waver long range protocol.
    If no keys are granted in the `:advanced_joining` extension this inclusion
    will fail.
  """
  @type bootstrapping_mode() :: :security_2 | :smart_start | :long_range

  @typedoc """
  The different network statuses are:

  - `:not_in_network` - the node in the provisioning list is not included in
    the network
  - `:included` - the node in the provisioning list is included in the network
    and is functional
  - `:failing` - the node in the provisioning list is included in the network
    but is now marked as failing
  """
  @type network_status() :: :pending | :passive | :ignored

  @typedoc """
  Id of the manufacturer for the product id extension
  """
  @type manufacturer_id() :: unit_16()

  @typedoc """
  Id of the product produced by the manufacturer for the product id extension
  """
  @type product_id() :: unit_16()

  @typedoc """
  Type of product produced by the manufacturer for the product id extension
  """
  @type product_type() :: unit_16()

  @typedoc """
  Version of the application in a string format of "Major.Minor"
  """
  @type application_version() :: binary()

  @type product_id_values() ::
          {manufacturer_id(), product_id(), product_type(), application_version()}

  @typedoc """
  The interval (in seconds) must be in the range of 640..12672 inclusive, and
  has to be in steps of 128 seconds.

  So after 640 the next valid interval is `640 + 128` which is `768` seconds.

  See `SDS13944 Node Provisioning Information Type Registry.pdf` section
  `3.1.2.3` for more information.
  """
  @type inclusion_interval() :: 640..12672

  @typedoc """
  The location string cannot contain underscores and cannot end with a dash.

  The location string can contain a period (.) but a sublocation cannot end a
  dash. For example:

  ```
  123.123-.123
  ```

  The above location invalid. To make it valid remove the `-` before `.`.

  A node's location cannot be more than 62 bytes.
  """
  @type information_location() :: binary()

  @typedoc """
  The name string cannot contain underscores and cannot end with a dash.

  A node's name cannot be more than 62 bytes.
  """
  @type information_name() :: binary()

  @typedoc """
  Generic Device Class for the product type extension
  """
  @type generic_device_class() :: atom()

  @typedoc """
  Specific Device Class for the product type extension
  """
  @type specific_device_class() :: atom()

  @typedoc """
  Installer icon for the product type extension
  """
  @type installer_icon_type() :: IconType.name()

  @type product_type_values() ::
          {generic_device_class(), specific_device_class(), installer_icon_type()}

  @typedoc """
  Settings for the smart start inclusion setting exentsion

  * `:pending` - the node will be added to the network when it issues SmartStart
    inclusion requests.
  * `:passive` - this node is unlikely to issues a SmartStart inclusion request
    and SmartStart inclusion requests will be ignored from this node by the
    Z/IP Gateway. All nodes in the list with this setting must be updated to
    `:pending` when Provisioning List Iteration Get command is issued.
  * `:ignored` - All SmartStart inclusion request are ignored from this node
    until updated via Z/IP Client (Grizzly) or a controlling node.
  """
  @type inclusion_setting() :: :pending | :passive | :ignored

  @typedoc """
  Meta extension for SmartStart devices

  * `:advanced_joining` - used to specify which S2 security keys to grant
    during S2 inclusion
  * `:bootstrapping_mode` - used to specify the bootstrapping mode the including
    node must join with
  * `:location_information` - used to advertise the location assigned to the node
  * `:max_inclusion_request_interval` - used to advertise if a power constrained
    smart start node will issue an inclusion request at a higher interval than
    the default 512 seconds
  * `:name_information` - used to advertise the name of the node
  * `:network_status` - used to advertise if the node is in the network and its
    node id
  * `:product_id` - used to advertise product identifying data
  * `:product_type` - used to advertise the product type data
  * `:smart_start_inclusion_setting` - used to advertise the smart start
    inclusion setting
  * `:uuid16` - used to advertise the 16 byte manufacturer-defined information
    that is unique to the that device
  * `:unknown` - sometimes new extensions are released without first class
    support, so this extension is used for those extensions that still need to
    be supported in this library
  """
  @type extension() ::
          {:advanced_joining, [Security.key()]}
          | {:bootstrapping_mode, bootstrapping_mode()}
          | {:location_information, information_location()}
          | {:max_inclusion_request_interval, inclusion_interval()}
          | {:name_information, information_name()}
          | {:network_status, {ZWave.node_id(), atom()}}
          | {:product_id, product_id_values()}
          | {:product_type, product_type_values()}
          | {:smart_start_inclusion_setting, inclusion_setting()}
          | {:uuid16, UUID16.t()}
          | {:unknown, binary()}

  @doc """
  Encode an extension into a binary
  """
  @spec encode(extension()) :: binary()
  def encode(extension) do
    IO.iodata_to_binary(encode_extension(extension))
  end

  defp encode_extension({:advanced_joining, keys}) do
    keys_byte =
      Enum.reduce(keys, 0, fn
        :s2_unauthenticated, byte -> byte ||| 0x01
        :s2_authenticated, byte -> byte ||| 0x02
        :s2_access_control, byte -> byte ||| 0x04
        :s0, byte -> byte ||| 0x40
        _, byte -> byte
      end)

    [set_circuital_bit(@advanced_joining, 1), 0x01, keys_byte]
  end

  defp encode_extension({:bootstrapping_mode, mode}) do
    mode =
      case mode do
        :security_2 -> 0x00
        :smart_start -> 0x01
        :long_range -> 0x02
      end

    [set_circuital_bit(@bootstrapping_mode, 1), 0x01, mode]
  end

  defp encode_extension({:location_information, location}) do
    location =
      location
      |> String.codepoints()
      |> :erlang.list_to_binary()

    [set_circuital_bit(@location_information, 0), byte_size(location), location]
  end

  defp encode_extension({:max_inclusion_request_interval, interval}) do
    interval = Integer.floor_div(interval - 640, 128)

    [set_circuital_bit(@max_inclusion_request_interval, 0), 0x01, interval]
  end

  defp encode_extension({:name_information, name}) do
    name =
      name
      |> String.codepoints()
      |> Enum.reduce([], fn
        ".", nl ->
          nl ++ ["\\", "."]

        c, nl ->
          nl ++ [c]
      end)

    [set_circuital_bit(@name_information, 0), length(name), name]
  end

  # Encodes for Long Range not enabled
  defp encode_extension({:network_status, {node_id, status}}) do
    status =
      case status do
        :not_in_network -> 0x00
        :included -> 0x01
        :failing -> 0x02
      end

    [set_circuital_bit(@network_status, 0), 0x02, node_id, status]
  end

  defp encode_extension({:product_id, {manu_id, prod_id, prod_type, version}}) do
    {:ok, version} = Version.parse(version <> ".0")

    [
      set_circuital_bit(@product_id, 0),
      0x08,
      <<manu_id::size(16)>>,
      <<prod_id::size(16)>>,
      <<prod_type::size(16)>>,
      version.major,
      version.minor
    ]
  end

  defp encode_extension({:product_type, {gen_class, spec_class, icon_name}}) do
    gen_byte = DeviceClasses.generic_device_class_to_byte(gen_class)

    spec_byte =
      DeviceClasses.specific_device_class_to_byte(
        gen_class,
        spec_class
      )

    {:ok, icon_integer} = IconType.to_value(icon_name)

    [set_circuital_bit(@product_type, 0), 0x04, gen_byte, spec_byte, <<icon_integer::size(16)>>]
  end

  defp encode_extension({:smart_start_inclusion_setting, setting}) do
    setting =
      case setting do
        :pending -> 0x00
        :passive -> 0x02
        :ignored -> 0x03
      end

    [set_circuital_bit(@smart_start_inclusion_setting, 1), 0x01, setting]
  end

  defp encode_extension({:uuid16, uuid16}) do
    [UUID16.encode(uuid16)]
  end

  defp encode_extension({:unknown, binary}) do
    [binary]
  end

  @doc """
  Parse the binary into the list of extensions
  """
  @spec parse(binary()) :: [extension()]
  def parse(binary) do
    do_parse(binary, [])
  end

  defp do_parse(<<>>, extensions) do
    Enum.reverse(extensions)
  end

  defp do_parse(<<@advanced_joining::size(7), 1::size(1), 0x01, keys, rest::binary>>, extensions) do
    ext = {:advanced_joining, unmask_keys(keys)}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@bootstrapping_mode::size(7), 1::size(1), 0x01, mode, rest::binary>>,
         extensions
       ) do
    mode =
      case mode do
        0x00 -> :security_2
        0x01 -> :smart_start
        0x02 -> :long_range
      end

    ext = {:bootstrapping_mode, mode}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@location_information::size(7), 0::size(1), len, location::binary-size(len)-unit(8),
           rest::binary>>,
         extensions
       ) do
    ext = {:location_information, to_string(location)}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@max_inclusion_request_interval::size(7), 0::size(1), 0x01, interval, rest::binary>>,
         extensions
       ) do
    steps = interval - 5
    interval = 640 + steps * 128

    ext = {:max_inclusion_request_interval, interval}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@name_information::size(7), 0::size(1), len, name::binary-size(len)-unit(8),
           rest::binary>>,
         extensions
       ) do
    name =
      name
      |> to_string()
      |> String.replace("\\", "")

    ext = {:name_information, name}

    do_parse(rest, [ext | extensions])
  end

  # When Long Range is enabled
  defp do_parse(
         <<@network_status::size(7), 0::size(1), 0x04, node_id, status_byte,
           _long_range_node_id::size(16), rest::binary>>,
         extensions
       ) do
    status = decode_status(status_byte)

    ext = {:network_status, {node_id, status}}

    do_parse(rest, [ext | extensions])
  end

  # When Long Range is NOT enabled
  defp do_parse(
         <<@network_status::size(7), 0::size(1), 0x02, node_id, status_byte, rest::binary>>,
         extensions
       ) do
    status = decode_status(status_byte)

    ext = {:network_status, {node_id, status}}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@product_id::size(7), 0::size(1), 0x08, manu_id::size(16), prod_id::size(16),
           prod_type::size(16), version_major, version_minor, rest::binary>>,
         extensions
       ) do
    ext = {:product_id, {manu_id, prod_id, prod_type, "#{version_major}.#{version_minor}"}}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@product_type::size(7), 0::size(1), 0x04, gen_class, spec_class, icon::size(16),
           rest::binary>>,
         extensions
       ) do
    {:ok, icon} = IconType.to_name(icon)
    {:ok, gen_class} = DeviceClasses.generic_device_class_from_byte(gen_class)

    {:ok, spec_class} = DeviceClasses.specific_device_class_from_byte(gen_class, spec_class)

    ext = {:product_type, {gen_class, spec_class, icon}}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@smart_start_inclusion_setting::size(7), 1::size(1), 0x01, setting, rest::binary>>,
         extensions
       ) do
    setting =
      case setting do
        0x00 -> :pending
        0x02 -> :passive
        0x03 -> :ignored
      end

    ext = {:smart_start_inclusion_setting, setting}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(
         <<@uuid16::size(7), 0::size(1), len, values::binary-size(len)-unit(8), rest::binary>>,
         extensions
       ) do
    {:ok, uuid} = UUID16.parse(<<@uuid16::size(7), 0::size(1), len, values::binary>>)

    ext = {:uuid16, uuid}

    do_parse(rest, [ext | extensions])
  end

  defp do_parse(<<type, len, values::binary-size(len)-unit(8), rest::binary>>, extensions) do
    ext = {:unknown, <<type, len, values::binary>>}

    do_parse(rest, [ext | extensions])
  end

  defp unmask_keys(byte) do
    Enum.reduce(Security.keys(), [], fn key, keys ->
      if byte_has_key?(<<byte>>, key) do
        [key | keys]
      else
        keys
      end
    end)
  end

  defp byte_has_key?(<<_::size(7), 1::size(1)>>, :s2_unauthenticated), do: true
  defp byte_has_key?(<<_::size(6), 1::size(1), _::size(1)>>, :s2_authenticated), do: true
  defp byte_has_key?(<<_::size(5), 1::size(1), _::size(2)>>, :s2_access_control), do: true
  defp byte_has_key?(<<_::size(1), 1::size(1), _::size(6)>>, :s0), do: true
  defp byte_has_key?(_byte, _key), do: false

  defp set_circuital_bit(byte, cbit) do
    <<byte::size(7), cbit::size(1)>>
  end

  defp decode_status(status_byte) do
    case status_byte do
      0x00 -> :not_in_network
      0x01 -> :included
      0x02 -> :failing
    end
  end
end