@spec add(KNXex.GroupAddress.t(), String.t(), Keyword.t()) :: :ok

Adds the given group address with the datapoint type (DPT) to the group address list. Unknown group addresses can not be used to send or receive telegrams.

The DPT is in the form of "x.yyy" where x and y are numbers, i.e. 1.001.

The following options are additionally supported:

• hydrate: boolean() - Optional. Specifies whether the group address should be read to hydrate the value (defaults to false).

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec create_ets_table() :: :ets.tid()

Creates the ETS table. The current process will be the owner of the table.

The table should be created before starting the server, if multiple are started. This would prevent losing the whole table if one server crashes.

The ETS table will be automatically created in the server process, if it does not exist, however.

If the ETS table already exists, the table identifier will be returned. The owner is not modified.

@spec filter_gpa_hydration_by_read_flag(KNXex.EtsProject.t(), Keyword.t()) :: [
  group_address :: String.t()
]

This is a helper function that takes an ETS project struct, optionally the path to the ETS project file, and whether group addresses which have an unknown read flag should be read from the KNX bus.

The ETS project file MUST exist, as it must be read from disk to read the manufacturer data.

As output you will receive a list of group addresses that can be read from the KNX bus, optionally with group addresses that may be readable.

The following optional options can be given:

• allow_nil: boolean() - Whether group addresses that have an unknown read flag should be read from the KNX bus (defaults to true).

• manufacturer_map: map() - A map from KNXex.ProjectParser.parse_manufacturers/2, if it has already been done before. This helps not having to parse the ETS project file again. If not given, it will be parsed from the ETS project file.

• path: String.t() - The path to the ETS project file. If not given, the path from the ETS project struct is used.

All other given elements in opts are passed to KNXex.ProjectParser.parse_manufacturers/2.

@spec get_group_addresses() :: [KNXex.GroupAddressServer.GroupAddressData.t()]

Gets all group addresses from the ETS table.

@spec read(KNXex.GroupAddress.t(), Keyword.t()) ::
  {:ok, KNXex.GroupAddressServer.GroupAddressData.t()} | {:error, term()}

Reads the group address from the ETS table.

If specified, the value will be read from the KNX bus, if the value is nil. The function can also be instructed to read the value from the KNX bus, regardless whether the value is available or not.

The following options are additionally supported:

• force_value_read: boolean() - Optional. Specifies whether the group address must be read from the KNX bus before returning it (defaults to false).
• read_value_on_nil: boolean() - Optional. Specifies whether the group address is read from the KNX bus before returning, if the value is nil (defaults to false).

@spec remove(KNXex.GroupAddress.t()) :: :ok

Removes the given group address from the group address list.

@spec start_link(Keyword.t()) :: {:ok, pid()} | {:error, {:already_started, pid()}}

Starts a new Group Address Server.

The group addresses with their name and type is read from the ETS project file (.knxproj export).

The following options are available (some are required):

• ets_project: KNXex.EtsProject.t() | path :: binary() - Required. The ETS project to use, or the path to the ETS project file.

• hydrate_on_start: boolean() | [address :: binary()] - Optional. Whether to hydrate the group addresses state on startup, by reading the group addresses from the KNX bus. If true, all group addresses are read. If a list of group addresses is given (in x/y/z format), only those are read.

• hydration_state: [hydration_state_item()] - Optional. The hydration state to use when hydrating the group addresses state on startup. If not given and hydrate_on_start is given, the hydration state is read from the KNX bus.
• hydration_timeout: pos_integer() - Optional. The timeout used when hydrating the state from the KNX bus (defaults to 5000ms).

• knx_interface: module() | {module(), atom() | pid()} - Required. The KNX interface to use. The module name or a tuple of module name and PID/registered name. The only supported KNX interface modules are MulticastClient and TunnelClient currently.

@spec subscribe(pid(), Keyword.t()) :: :ok

Sets the subscriber to the given PID. The PID is not checked for aliveness.

Only a single subscriber is supported. This function is used with the GenStageProducer.

@spec to_hydration_state() :: [hydration_state_item()]

Converts the current ETS table state into an usable hydration state. Group addresses without a value are skipped.

@spec unsubscribe(any(), Keyword.t()) :: :ok

Unsets the subscriber. The first argument is ignored and only for compatibility.

This function is used with the GenStageProducer.

@spec wait_for_startup(Keyword.t()) :: :ok

Waits for the startup sequence to complete. This will block indefinitely until the server replies. This is useful during hydration, to wait until the hydration is completed and available to answer requests.

@spec write(KNXex.GroupAddress.t(), term(), Keyword.t()) :: :ok | {:error, term()}

Writes the group address. The value is written to the KNX bus and then stored in the ETS table.