Grizzly.ZWave.CommandSpec (grizzly v9.1.0)

Copy Markdown View Source

Data structure describing a Z-Wave command, including how to create, encode, and decode it.

Summary

Types

report_matcher()
t()

Command Specs

handler_spec(spec)

Get the handler and options for a command.

new(fields)

Create a new command spec.

new(command_class, name, byte, mod, opts)

Create a new command spec.

validate(spec)

Validate a command spec.

validate_param_list(params)

Validates a list of parameter specs.

Commands

create_command(spec, params)

Create a command struct from the command spec and parameters.

validate_params(spec, params)

Validate a command's parameters according to the command spec.

Types

report_matcher()

@type report_matcher() :: (get :: Grizzly.ZWave.Command.t(),
                     report :: Grizzly.ZWave.Command.t() ->
                       boolean())

t()

@type t() :: %Grizzly.ZWave.CommandSpec{
  command_byte: byte(),
  command_class: atom(),
  decode_fun: {module(), atom()},
  default_params: keyword(),
  encode_fun: {module(), atom()},
  handler: {module(), keyword()},
  module: module(),
  name: atom(),
  params: [{atom(), Grizzly.ZWave.ParamSpec.t()}],
  report: atom() | nil,
  report_matcher_fun: {module(), atom()} | nil,
  supports_supervision?: boolean(),
  validate_fun:
    {module(), atom()} | (keyword() -> {:ok, keyword()} | {:error, any()}) | nil
}

  • :name (atom/0) - Required. The command's name as an atom (should be globally unique).

  • :command_class (Grizzly.ZWave.CommandClasses.command_class/0) - Required. The command class this command belongs to.

  • :module (atom/0) - Required. The module implementing this command's encoding and decoding functions.

  • :command_byte - Required. The command identifier.

  • :encode_fun - Required. A function or {module, function} tuple used to encode the command's parameters into a binary. Only 1-arity functions are currently supported.

  • :decode_fun - Required. A function or {module, function} tuple used to decode the command's parameters from binary to a keyword list (the reverse of the encode_fun).

    If the function is of arity 1, the first argument will be the binary to decode. If arity 2, the command spec will be inserted as the first argument.

  • :report_matcher_fun - A 2-arity function or {module, function} tuple used to match a report command to a get command. The first argument will be the get command and the second argument will be the report command to match. The function should return true if the report matches the get.

  • :report (atom/0) - The name of the report command associated with this command, if any. For get commands, this will default to the command name with the trailing _get replaced with _report. To override this behavior, explicitly set this field to nil.

    A special value of :any may be used to indicate that any report command can satisfy this particular get command. Otherwise, this should be the name of a registered report command.

  • :handler (tuple of atom/0, keyword/0 values) - A {module, options} tuple indicating the request handler that should be used to handle completion of this command when sent via a Grizzly.Request. Normally, this will default to {AckResponse, []}. However, if the :report option is specified but :handler is not, the default becomes {WaitReport, complete_report: report}.

  • :supports_supervision? (boolean/0) - Whether this command supports Z-Wave Supervision. Defaults to false for commands whose names end with _get. Defaults to true for commands whose names end with _set or _report. Defaults to false for commands named network_management_*, as most of these are only supported by Z/IP Gateway. The default value is true.

  • :validate_fun - A {module, function} tuple indicating a function that validates the command parameters. The function should return {:ok, params} if the parameters are valid or have been updated, or {:error, reason} if the parameters are invalid.

  • :params - The default value is [].

  • :default_params (keyword/0) - A keyword list of default parameters for the command. These parameters will be merged with any parameters passed to create_command/2 before validation. The default value is [].

Command Specs

handler_spec(spec)

Get the handler and options for a command.

new(fields)

Create a new command spec.

new(command_class, name, byte, mod, opts)

Create a new command spec.

validate(spec)

Validate a command spec.

validate_param_list(params)

@spec validate_param_list([{atom(), Grizzly.ZWave.ParamSpec.t()}]) ::
  {:ok, [{atom(), Grizzly.ZWave.ParamSpec.t()}]} | {:error, String.t()}

Validates a list of parameter specs.

Examples

iex> params = [
...>   param1: %Grizzly.ZWave.ParamSpec{name: :param1, type: :uint, size: 8},
...>   param2: %Grizzly.ZWave.ParamSpec{name: :param2, type: :int, size: 16}
...> ]
iex> Grizzly.ZWave.CommandSpec.validate_param_list(params)
{:ok, params}

iex> params = [
...>   param1: %Grizzly.ZWave.ParamSpec{name: :param1, type: :uint, size: 7},
...>   param2: %Grizzly.ZWave.ParamSpec{name: :param2, type: :int, size: 8}
...> ]
iex> Grizzly.ZWave.CommandSpec.validate_param_list(params)
{:error, "Total size of all non-variable parameters must be a multiple of 8 bits"}

iex> params = [
...>   param1: %Grizzly.ZWave.ParamSpec{name: :param1, type: :uint, size: :variable},
...>   param2: %Grizzly.ZWave.ParamSpec{name: :param2, type: :int, size: 16}
...> ]
iex> Grizzly.ZWave.CommandSpec.validate_param_list(params)
{:error, "Variable-length parameter without length specifier must be last"}

Commands

create_command(spec, params)

Create a command struct from the command spec and parameters.

validate_params(spec, params)

Validate a command's parameters according to the command spec.