# `DSMR.OBIS`
[🔗](https://github.com/mijnverbruik/dsmr/blob/v1.1.0/lib/dsmr/obis.ex#L1)

OBIS code mappings used by the parser and serializer.

OBIS codes identify the values contained in a DSMR telegram. This module maps
known codes to `%DSMR.Telegram{}` fields and exposes the reverse mapping used
by `DSMR.Telegram.to_string/1`.

# `format`

```elixir
@type format() :: {non_neg_integer(), non_neg_integer()}
```

Spec-defined measurement value format as `{integer_digits, decimals}`.

For example the DSMR `F9(3,3)` energy register format is `{6, 3}`:
six integer digits and three decimals.

# `all_mappings`

```elixir
@spec all_mappings() :: %{required(atom()) => String.t()}
```

Returns all field-to-OBIS mappings as a map.

# `field_definitions`

```elixir
@spec field_definitions() :: [
  {atom(),
   {String.t() | nil,
    :string | :timestamp | {:measurement, format()} | :power_failures_log}}
]
```

Returns the ordered field definitions: `{field, {obis_string, value_type}}`.

This is the single source of truth for telegram fields; `DSMR.Telegram`
derives its struct and typespec from it at compile time.

# `field_order`

```elixir
@spec field_order() :: [atom()]
```

Returns the ordered list of telegram fields for serialization.

The order matches the DSMR specification and is used when converting
a Telegram struct to its string representation.

## Examples

    iex> fields = DSMR.OBIS.field_order()
    iex> hd(fields)
    :version
    iex> :electricity_delivered_1 in fields
    true

# `get_field`

```elixir
@spec get_field([non_neg_integer()]) :: atom() | nil
```

Returns the field name for a given OBIS code list.

Used by the parser to map OBIS codes to struct fields.
This function is called from Erlang code in dsmr_parser.yrl.

## Examples

    iex> DSMR.OBIS.get_field([1, 3, 0, 2, 8])
    :version

    iex> DSMR.OBIS.get_field([1, 0, 1, 8, 1])
    :electricity_delivered_1

    iex> DSMR.OBIS.get_field([99, 99, 99, 99, 99])
    nil

# `get_format`

```elixir
@spec get_format(atom()) :: format() | nil
```

Returns the spec-defined measurement format for a field, or `nil` when the
field is not a measurement.

## Examples

    iex> DSMR.OBIS.get_format(:voltage_l1)
    {3, 1}

    iex> DSMR.OBIS.get_format(:version)
    nil

# `get_obis`

```elixir
@spec get_obis(atom()) :: String.t() | nil
```

Returns the OBIS code string for a given telegram field.

Used by serialization logic (Telegram.to_string/1).

## Examples

    iex> DSMR.OBIS.get_obis(:version)
    "1-3:0.2.8"

    iex> DSMR.OBIS.get_obis(:electricity_delivered_1)
    "1-0:1.8.1"

---

*Consult [api-reference.md](api-reference.md) for complete listing*