TCP/IP Transport
================

Overview
--------

Networked ANURA transceivers (such as the TR1) expose the Transceiver API over a TCP/IP transport.
This transport provides reliable, stream-oriented communication over standard TCP/IP networks.

Connection Parameters
---------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Value
   * - Protocol
     - TCP
   * - Port
     - 7645
   * - IP Address
     - Dynamic (obtain via e.g. mDNS or DHCP lease table)

.. admonition:: Frog Fact
   :class: note

   At the time the port number was selected, amphibiaweb.org listed 7645 species in the order Anura (frogs and toads).

Message Framing
---------------

CBOR-RPC messages are transmitted over the TCP stream with a simple length-prefixed framing protocol:

1. **Length Prefix**: Each message begins with a 16-bit unsigned integer in big-endian byte order, indicating the length of the following CBOR payload in bytes.
2. **CBOR Payload**: Immediately following the length prefix is the CBOR-encoded message payload.

The maximum message size supported by the framing protocol is 65,535 bytes (2¹⁶ - 1).
In practice, this is further limited by device-specific constraints.

Framing Format
^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Field
     - Size
     - Description
   * - Length
     - 2 bytes
     - Big-endian uint16 indicating payload length
   * - Payload
     - N bytes
     - CBOR-encoded message (N = value of Length field)

Connection Lifecycle
--------------------

Transceiver implementations expect a single client connection that remains open indefinitely for the duration of monitoring operations.

1. **Connect**: Client establishes TCP connection to transceiver on port 7645.
2. **Keep-Alive**: Client must send a request at least once every 5 seconds. The transceiver will close the connection if no message is received within this interval. (The :cborrpc:meth:`ping` method exists for this purpose.)
3. **Exchange Messages**: Client and server exchange length-prefixed CBOR-RPC messages.
4. **Disconnect**: Either party may close the TCP connection at any time.

.. note::

   While the transceiver accepts multiple concurrent client connections, this is not a supported use case for production deployments.
   Concurrent connections may be useful for debugging purposes, such as using a CLI test client to probe a transceiver that is otherwise managed by a monitoring system.

Example Message Frame
---------------------

Consider a simple request to call the :cborrpc:meth:`ping` method:

**CBOR Message**: ``[0, 1, "ping", null]``

**Encoded CBOR** (hexadecimal): ``84 00 01 64 70 69 6E 67 F6``

**Complete TCP Frame**:

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - Data (hexadecimal)
     - Description
   * - ``00 09``
     - Payload Length (big-endian): 0009h = 9 bytes
   * - ``84 00 01 64 70 69 6E 67 F6``
     - CBOR Payload: ``[0, 1, "ping", null]``