Macros for establishing Modbus schema.

The schema allows names to be assigned to individual modbus objects or groups of contiguous modbus objects along with encoder/decoder functions. It also allows objects to be flagged as readable and/or writable.

Naming a mapping

You create a ModBoss mapping with this format:

holding_register 17, :outdoor_temp, as: {ModBoss.Encoding, :signed_int}

This establishes address 17 as a holding register with the name :outdoor_temp. The raw value from the register will be passed to ModBoss.Encoding.decode_signed_int/1 when decoding.

Similarly, to set aside a group of registers to hold a single logical value, it would look like:

holding_register 20..23, :model_name, as: {ModBoss.Encoding, :ascii}

This establishes addresses 20–23 as holding registers with the name :model_name. The raw values from these registers will be passed (as a list) to ModBoss.Encoding.decode_ascii/1 when decoding.

Mode

All ModBoss mappings are read-only by default. Use mode: :rw to allow both reads & writes. Or use mode: :w to configure a mapping as write-only.

Automatic encoding/decoding

Depending on whether a mapping is flagged as readable/writable, it is expected that you will provide functions with encode_ or decode_ prepended to the value provided by the :as option.

For example, if you specify as: :on_off for a writable mapping, ModBoss will expect that the schema module defines either:

• encode_on_off/1 — accepts the value to encode
• encode_on_off/2 — accepts the value to encode and a ModBoss.Encoding.Metadata struct

Use the 2-arity version when you need access to metadata (e.g. address count, mapping name, or user-provided context). Both must return either {:ok, encoded_value} or {:error, message}.

The same applies to decode functions: define either decode_on_off/1 (accepts the encoded value) or decode_on_off/2 (accepts the encoded value and metadata).

If the function to be used lives outside of the current module, a tuple including the module name can be passed. For example, you can use built-in encoders from ModBoss.Encoding.

Example

defmodule MyDevice.Schema do
  use ModBoss.Schema

  schema do
    holding_register 1..5, :model, as: {ModBoss.Encoding, :ascii}
    holding_register 6, :outdoor_temp, as: {ModBoss.Encoding, :signed_int}
    holding_register 7, :indoor_temp, as: {ModBoss.Encoding, :unsigned_int}

    input_register 200, :foo, as: {ModBoss.Encoding, :unsigned_int}
    coil 300, :bar, as: :on_off, mode: :rw
    holding_register 301, :setpoint, as: :scaled, mode: :w
    discrete_input 400, :baz, as: {ModBoss.Encoding, :boolean}
  end

  # 1-arity: no metadata needed
  def encode_on_off(:on), do: {:ok, 1}
  def encode_on_off(:off), do: {:ok, 0}

  def decode_on_off(1), do: {:ok, :on}
  def decode_on_off(0), do: {:ok, :off}

  # 2-arity: uses metadata.context for runtime behavior
  def encode_scaled(value, metadata) do
    case metadata.context do
      %{unit: :fahrenheit} -> {:ok, round((value - 32) * 5 / 9)}
      _ -> {:ok, value}
    end
  end
end