@spec encode(module(), values(), keyword()) :: {:ok, map()} | {:error, String.t()}

Encode values per the mapping without actually writing them.

This can be useful in test scenarios and enables values to be encoded in bulk without actually being written via Modbus.

Returns a map with keys of the form {type, address} and encoded_value as values.

Opts

• :context — a map of arbitrary data that will be included in the ModBoss.Encoding.Metadata struct passed to encode functions (when using 2-arity encoders). Defaults to %{}.

Example

iex> ModBoss.encode(MyDevice.Schema, foo: "Yay")
{:ok, %{{:holding_register, 15} => 22881, {:holding_register, 16} => 30976}}

@spec read(module(), atom() | [atom()], read_func(), keyword()) ::
  {:ok, any()} | {:error, any()}

Read from modbus using named mappings.

This function takes either an atom or a list of atoms representing the mappings to read, batches the mappings into contiguous addresses per type, then reads and decodes the values before returning them.

For each batch, read_func will be called with the type of modbus object (:holding_register, :input_register, :coil, or :discrete_input), the starting address for the batch to be read, and the count of addresses to read from. It must return either {:ok, result} or {:error, message}.

If a single name is requested, the result will be an :ok tuple including the single result for that named mapping. If a list of names is requested, the result will be an :ok tuple including a map with mapping names as keys and mapping values as results.

Opts

• :max_gap — Allows reading across unrequested gaps to reduce the overall number of requests that need to be made. Results from gaps will be retrieved and discarded. This value can be specified as a single integer (which applies to all types) or per object type. Only readable ModBoss mappings will be included in gap reads. To opt a readable mapping out of gap reads, specify gap_safe: false on that mapping. See the :gap_safe option in ModBoss.Schema for details.
• :debug — if true, returns a map of mapping details instead of just the value; defaults to false
• :decode — if false, ModBoss doesn't attempt to decode the retrieved values; defaults to true. This option can be especially useful if you need insight into a particular value that is failing to decode as expected.
• :max_attempts — maximum number of times each read_func callback will be attempted before giving up. Defaults to 1 (no retries). Only {:error, _} triggers a retry; exceptions are not retried.
• :context — a map of arbitrary data that will be included in the ModBoss.Encoding.Metadata struct passed to decode functions (when using 2-arity decoders) and in telemetry event metadata. Defaults to %{}. Useful for conditionally decoding values based on runtime information like firmware version or hardware revision, and for identifying which device or connection a request belongs to in telemetry handlers.

schema do
  holding_register 1, :temp, as: {ModBoss.Encoding, :signed_int}
  holding_register 2, :status, as: {ModBoss.Encoding, :unsigned_int}
  holding_register 3, :error_count, as: {ModBoss.Encoding, :unsigned_int}, gap_safe: false
  holding_register 4, :mode, as: {ModBoss.Encoding, :unsigned_int}
  holding_register 5, :humidity, as: {ModBoss.Encoding, :unsigned_int}
end

Examples

read_func = fn object_type, starting_address, count ->
  result = custom_read_logic(…)
  {:ok, result}
end

# Read one mapping
ModBoss.read(SchemaModule, :foo, read_func)
{:ok, 75}

# Read multiple mappings
ModBoss.read(SchemaModule, [:foo, :bar, :baz], read_func)
{:ok, %{foo: 75, bar: "ABC", baz: true}}

# Read *all* readable mappings
ModBoss.read(SchemaModule, :all, read_func)
{:ok, %{foo: 75, bar: "ABC", baz: true, qux: 1024}}

# Enable reading extra registers to reduce the number of requests
ModBoss.read(SchemaModule, [:foo, :bar], read_func, max_gap: 10)
{:ok, %{foo: 75, bar: "ABC"}}

# …or allow reading across different gap sizes per type
ModBoss.read(SchemaModule, [:foo, :bar], read_func, max_gap: %{holding_register: 10})
{:ok, %{foo: 75, bar: "ABC"}}

# Get "raw" Modbus values (as returned by `read_func`)
ModBoss.read(SchemaModule, [:foo, :bar], read_func, decode: false)
{:ok, %{foo: [75], bar: [16706, 17152]}}

@spec write(module(), values(), write_func(), keyword()) :: :ok | {:error, any()}

Write to modbus using named mappings.

ModBoss automatically encodes your values, then batches any encoded values destined for contiguous objects—creating separate batches per object type.

For each batch, write_func will be called with the type of object (:holding_register or :coil), the starting address for the batch to be written, and a list of values to write. It must return either :ok or {:error, message}.

Opts

• :max_attempts — maximum number of times each write_func callback will be attempted before giving up. Defaults to 1 (no retries). Only {:error, _} triggers a retry; exceptions are not retried.
• :context — a map of arbitrary data that will be included in the ModBoss.Encoding.Metadata struct passed to encode functions (when using 2-arity encoders) and in telemetry event metadata. Defaults to %{}. Useful for conditionally encoding values based on runtime information like firmware version or hardware revision, and for identifying which device or connection a request belongs to in telemetry handlers.

Example

write_func = fn object_type, starting_address, value_or_values ->
  custom_write_logic(…)
  :ok
end

iex> ModBoss.write(MyDevice.Schema, [foo: 75, bar: "ABC"], write_func)
:ok