ArtNet.Packet (ArtNet v0.1.0)

View Source

Encodes and decodes complete Art-Net packets.

This module is the packet-level codec used by ArtNet. It handles the common Art-Net header and delegates payload handling to packet modules generated by ArtNet.Packet.Schema.

Decoding follows this flow:

  • validate the Art-Net\0 identifier.
  • read the little-endian OpCode and resolve the packet module through ArtNet.OpCode.
  • validate the OpCode and protocol version header for the selected module.
  • decode the payload with the packet module's generated body decoder.
  • run packet decode validation.

Encoding follows the reverse flow: validate the struct, build the common header from the packet module, encode the schema fields, and append the body.

Summary

Functions

decode(data)

Decodes a binary Art-Net packet.

decode(module, rest)

Decodes a binary Art-Net packet as the given packet module.

decode!(binary)

Decodes a binary Art-Net packet.

encode(packet)

Encodes an Art-Net packet struct into a complete Art-Net binary.

encode!(packet)

Encodes a binary Art-Net packet.

identifier()

Returns the Art-Net packet identifier.

validate_header(module, rest)

Validates the common Art-Net header for a packet module.

version()

Returns the Art-Net protocol version encoded in versioned packet headers.

Functions

decode(data)

@spec decode(binary()) :: {:ok, struct()} | {:error, ArtNet.DecodeError.t()}

Decodes a binary Art-Net packet.

Examples

iex> ArtNet.Packet.decode(<<0x41, 0x72, 0x74, 0x2D, 0x4E, 0x65, 0x74, 0x00, 0x00, 0x50, 0x00, 0x0E, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0xFF>>)
{:ok,
  %ArtNet.Packet.ArtDmx{
    sequence: 01,
    physical: 0,
    sub_universe: 0,
    net: 0,
    length: 1,
    data: [255]
  }}

iex> ArtNet.Packet.decode(<<0x41, 0x72, 0x74, 0x2D, 0x4E, 0x65, 0x74, 0x01, 0x00, 0x50, 0x00, 0x0E, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0xFF>>)
{:error, %ArtNet.DecodeError{reason: {:invalid_data, "Invalid identifier"}}}

iex> ArtNet.Packet.decode(<<0x41, 0x72, 0x74, 0x2D, 0x4E, 0x65, 0x74, 0x00, 0xff, 0x7f, 0x00, 0x0E, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0xFF>>)
{:error, %ArtNet.DecodeError{reason: {:invalid_op_code, 0x7fff}}}

iex> ArtNet.Packet.decode(<<0x01, 0x02>>)
{:error, %ArtNet.DecodeError{reason: {:invalid_data, "Invalid identifier"}}}

decode(module, rest)

@spec decode(module(), binary()) :: {:ok, struct()} | {:error, ArtNet.DecodeError.t()}

Decodes a binary Art-Net packet as the given packet module.

This variant is useful when the caller already knows the expected packet module. It still validates the Art-Net identifier, OpCode, and version header before decoding the payload.

decode!(binary)

@spec decode!(binary()) :: struct()

Decodes a binary Art-Net packet.

If the packet could not be decoded, the function raises an error.

Examples

iex> ArtNet.Packet.decode!(<<0x41, 0x72, 0x74, 0x2D, 0x4E, 0x65, 0x74, 0x00, 0x00, 0x50, 0x00, 0x0E, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0xFF>>)
%ArtNet.Packet.ArtDmx{sequence: 1, physical: 0, sub_universe: 0, net: 0, length: 1, data: [255]}

encode(packet)

@spec encode(ArtNet.packet()) :: {:ok, binary()} | {:error, ArtNet.EncodeError.t()}

Encodes an Art-Net packet struct into a complete Art-Net binary.

The packet module is taken from the struct itself. Encoding runs validate_encode/1, writes the common header, and then encodes the payload fields in schema order.

encode!(packet)

@spec encode!(ArtNet.packet()) :: binary()

Encodes a binary Art-Net packet.

If the packet could not be encoded, the function raises an error.

Examples

iex> ArtNet.Packet.encode!(%ArtNet.Packet.ArtDmx{sequence: 1, physical: 0, sub_universe: 0, net: 0, length: 1, data: [255]})
<<0x41, 0x72, 0x74, 0x2D, 0x4E, 0x65, 0x74, 0x00, 0x00, 0x50, 0x00, 0x0E, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0xFF>>

identifier()

@spec identifier() :: binary()

Returns the Art-Net packet identifier.

validate_header(module, rest)

@spec validate_header(module(), binary()) ::
  {:ok, binary()} | {:error, ArtNet.DecodeError.t()}

Validates the common Art-Net header for a packet module.

On success, returns the remaining payload binary after the identifier, OpCode, and optional protocol version header have been consumed.

version()

@spec version() :: pos_integer()

Returns the Art-Net protocol version encoded in versioned packet headers.