@spec bacnet_protocol() :: BACnet.Stack.TransportBehaviour.transport_protocol()

Get the BACnet transport protocol this transport implements.

@spec child_spec(list()) :: Supervisor.child_spec()

Produces a supervisor child spec. It will call child_spec(callback, opts) with the given 2-element list elements.

See also Supervisor.child_spec/2 for the rest of the behaviour.

@spec child_spec(BACnet.Stack.TransportBehaviour.transport_callback(), Keyword.t()) ::
  Supervisor.child_spec()

Produces a supervisor child spec based on the BACnet transport open callback, as such it will take the callback and opts for open/2.

See also Supervisor.child_spec/2 for the rest of the behaviour.

@spec close(GenServer.server()) :: :ok

Closes the Transport module.

@spec configure(BACnet.Stack.TransportBehaviour.transport(), open_options()) ::
  :ok | {:error, term()}

Configures the transport.

Only some of the available open_options/0 can be configured, unsupported options can only be changed by re-starting the transport completely.

The following options are supported:

• baudrate
• log_communication
• log_communication_rcv
• max_info_frames
• max_master_address

For a description of each option, see open/2.

Note that reconfiguring the baudrate on the fly MAY lead to invalid frames! May also lead to dropping token.

@spec destination_routed?(GenServer.server(), destination_address() | term()) ::
  boolean()

Checks whether the given destination is an address that needs to be routed.

Returns true for any non-valid destination_address(), because they need to be routed by a BACnet router residing on this transport layer/network.

@spec disable_token_passing(BACnet.Stack.TransportBehaviour.transport()) ::
  :ok | {:error, term()}

Disables the transport's token passing (only if master node).

Disabling the token passing will try to pass on the token, if held, as soon as possible, but only if the successor is known. If the successor is unknown or a timeout occurrs, the token will be dropped. The consequence of dropping the token will be that the remaining MS/TP master nodes will notice the lost token and generate a new token.

Whether it transitions to IDLE or NO_TOKEN state depends on its current state and could even change later on from IDLE to NO_TOKEN. Once the transport reaches IDLE or NO_TOKEN, the transport can be safely shut down.

When the token passing is disabled, sending any frame that does not involve sending a reply is disabled and return an error.

After disabling the transport token passing, it can only be re-enabled by restarting the transport.

@spec get_baudrate(BACnet.Stack.TransportBehaviour.transport()) ::
  non_neg_integer() | {:auto, non_neg_integer()}

Get the current active baudrate.

{:auto, non_neg_integer()} is returned during autobaud detection, when it has not finished yet. The contained number is the current active baudrate. Once autobaud detection finishes, this function will return a plain number with the current active baudrate.

@spec get_broadcast_address(GenServer.server()) :: destination_address()

Get the broadcast address.

@spec get_local_address(GenServer.server()) :: source_address()

Get the local address.

@spec get_portal(GenServer.server()) :: GenServer.server()

Get the transport module portal for the given transport PID/port. Transport modules may return the input as output, if the same PID or port is used for sending.

This is used to get the portal before having received data from the transport module, so data can be sent prior to reception.

@spec get_state(BACnet.Stack.TransportBehaviour.transport()) ::
  :idle | :no_token | atom()

Get the current transport state.

This function is important when disabling token passing and waiting for the transport to transition to the IDLE or NO_TOKEN state, to then be able to shut down the transport gracefully.

See also disable_token_passing/1.

@spec max_apdu_length() :: pos_integer()

Get the maximum APDU length for this transport.

@spec max_ext_apdu_length() :: pos_integer()

Get the maximum extended APDU length for this transport, if the transport also supports a higher (extended) APDU.

@spec max_ext_npdu_length() :: pos_integer()

Get the maximum extended NPDU length for this transport, if the transport also supports a higher (extended) NPDU.

The NPDU length contains the maximum transmittable size of the NPDU, including the APDU, without violating the maximum transmission unit of the underlying transport.

Any necessary transport header (i.e. BVLL, LLC) must have been taken into account when calculating this number.

@spec max_npdu_length() :: pos_integer()

Get the maximum NPDU length for this transport.

The NPDU length contains the maximum transmittable size of the NPDU, including the APDU, without violating the maximum transmission unit of the underlying transport.

Any necessary transport header (i.e. BVLL, LLC) must have been taken into account when calculating this number.

@spec open(
  callback :: BACnet.Stack.TransportBehaviour.transport_callback(),
  opts :: open_options()
) ::
  {:ok, pid()} | {:error, term()}

Opens/starts the Transport module. A process is started, that is linked to the caller process.

See the BACnet.Stack.TransportBehaviour documentation for more information.

In the case of this BACnet MS/TP transport, the transport PID/port is a GenServer receiving and sending RS485 data. The portal is the same transport PID/port, as access to the MS/TP network must be coordinated.

This transport takes the following options, in addition to GenServer.options/0:

• baudrate: non_neg_integer | :auto - Optional. The baud rate to use (defaults to 38400). See the module documentation regarding the autobaud feature.

• local_address: source_address() - Required. The address to use - must be unique in the BACnet MS/TP network. Addresses 0-127 are for master nodes, while 128-254 are for slave nodes.
• log_communication: boolean() - Optional. Logs all communication (debug), excluding receive states.
• log_communication_rcv: boolean() - Optional. Logs all communication (debug) of receive states.
• max_info_frames: pos_integer() - Optional. This value specifies the maximum number of information frames the node may send before it must pass the token (defaults to 1).
• max_master_address: 1..127 - Optional. The maximum master address that is used in the MS/TP network. This is used for polling and successor determination (defaults to 127).
• port_name: binary() - Required. Name of the serial port (use Circuits.UART.enumerate/0).
• supervisor: Supervisor.supervisor() - Optional. The task supervisor to use to spawn tasks under. Tasks are spawned to invoke the given callback. If no supervisor is given, the tasks will be spawned unsupervised.

@spec reply_postponed(
  BACnet.Stack.TransportBehaviour.portal(),
  source_address(),
  Keyword.t()
) ::
  :ok
  | {:error, term()}
  | {:error, :slave_mode}
  | {:error, :no_reply_pending}
  | {:error, :destination_is_not_expecting_reply}

Sends a Reply-Postponed Frame to the destination.

Sending an explicit Reply-Postponed Frame is necessary, when the reply is to be segmented. A segmented Complex-ACK APDU can only be transmitted when we hold the token (ASHRAE 135 Clause 9.8).

There are no options at this time.

@spec send(
  GenServer.server(),
  destination_address(),
  BACnet.Stack.EncoderProtocol.t() | iodata(),
  send_options()
) ::
  :ok
  | {:error, term()}
  | {:error, :slave_mode}
  | {:error, :token_passing_disabled}

Sends data to the BACnet network.

Please note that not all MS/TP devices support extended APDUs (max. 1476 bytes) and thus you should make sure they do when sending large APDUs, or always default to the maximum as defined by ASHRAE 135-2012 (before 135-2016).

See the BACnet.Stack.TransportBehaviour documentation for more information. The option skip_headers has no effect.

In addition, the following options are available:

• allow_extended_apdu: boolean() - Optional. Allow to send APDUs up to 1476 bytes, instead of 501 bytes. Extended APDUs require support of ASHRAE 135-2016 and newer.
• use_extended_apdu: boolean() - Optional. Uses the extended APDU frame type to send the APDU (APDU length must be min. 5 bytes) - allow_extended_apdu must be true.
• raw: boolean() - Optional. Sends raw data to the transport layer. The data MUST be BACnet MS/TP conform data.

@spec send_test(BACnet.Stack.TransportBehaviour.portal(), source_address(), iodata()) ::
  {:ok, iodata()}
  | {:error, term()}
  | {:error, :invalid_frame_response}
  | {:error, :slave_mode}
  | {:error, :token_passing_disabled}

Sends a Test-Request APDU to the specified destination.

If the destination exists and is reachable, it will send the data back unchanged (or no data at all, if it for some reason unable to read the data). The destination must not be 255 (broadcast). The data must be less than 502 bytes long.

This function will block until the Test-Response APDU has arrived or the timeout triggers.

@spec set_maintenance_pfm(BACnet.Stack.TransportBehaviour.transport(), boolean()) ::
  :ok

Enables or disables maintenance POLL_FOR_MASTER in the case the successor node is known. If the successor node is unknown, POLL_FOR_MASTER will be regardless done.

This function is only for development and testing purpose. It must not be used in production. Periodic maintenance polling for masters is required to find new nodes in between this node and the next current successor node. Nodes may come up and go down any time, which the BACnet specification accounts for and thus includes a POLL_FOR_MASTER mechanism.

@spec valid_destination?(destination_address() | term()) :: boolean()

Verifies whether the given destination is valid for the transport module.