18  Link

org.arl.unet.Services.LINK

18.1 Overview

The LINK service provides single-hop datagram delivery between neighboring nodes. “Single-hop” is meant logically: a link over a UDP/IP network may traverse many routers and switches, but it counts as one hop in the Unet, because the datagram passes through no intermediate Unet node along the way. An acoustic link agent builds on the PHYSICAL service (Chapter 17) to offer capabilities that the raw physical layer does not; other link agents carry datagrams over entirely different media (IP networks, optical or satellite modems). In particular, a link agent can:

• deliver datagrams larger than a single physical frame, by transparently fragmenting them on transmission and reassembling them on reception (perhaps using the fragmentation framework in Section 33.6);
• provide reliable delivery, by acknowledging received data and retransmitting what is lost; and
• recover from errors efficiently, by combining error detection, forward error correction and selective retransmission.

Link agents provide the DATAGRAM service (Chapter 16), so datagrams are sent to them using a DatagramReq and received as a DatagramNtf, with delivery outcomes reported through the standard datagram notifications. A node may run more than one link agent (for example, an acoustic link and a UDP link), each providing connectivity to a different set of neighbors; the router (Chapter 21) can then choose between them per destination. The default underwater acoustic link agent is accessed as uwlink.

18.2 Capabilities

Link agents advertise one service-specific capability (org.arl.unet.link.LinkCapability):

• LINK_STATUS – the agent tracks link state and publishes LinkStatusNtf notifications

The quality-of-service features of a link — reliability, fragmentation, cancellation, compression, priority — are advertised through the datagram capabilities (Chapter 16), and vary between implementations (see the tables below).

18.3 Messages

Datagram transfer over a link uses the datagram messages (Chapter 16). In addition, a link agent that tracks the state of its links to neighbors reports changes — link up/down transitions and link quality — by publishing the following notification on its topic:

• LinkStatusNtf – link status update

  Field	Type	Default	Remarks
  quality	float		link quality metric
  to	int	0	peer node address
  up	boolean		true if link is up, false if down

18.4 Parameters

In addition to the datagram parameters MTU and RTU (Chapter 16), agents providing this service expose:

• MTU – maximum data transfer size
• RTU – recommended data transfer size
• dataRate :: float – data rate (bps)

18.5 Examples

If you start the 2-node-network and connect to node A’s shell, you can send a reliable datagram to node B (address 31) over uwlink and watch for its delivery acknowledgement. First subscribe to the link agent so its notifications are printed, then send the datagram with reliability requested:

> subscribe uwlink
> uwlink << new DatagramReq(to: 31, data: [1,2,3,4,5,6,7,8], reliability: true)
AGREE
uwlink >> LinkStatusNtf:INFORM[link:uwlink to:31 up:true]
uwlink >> DatagramDeliveryNtf:INFORM[id:019f4248-e802-745e-9714-29b551c038e8]

You can also check the status of the link to a neighbor through the indexed parameters, which report any transfer in progress to that peer:

> uwlink[31]
« UWLINK »

[org.arl.unet.link.ECLinkProgressParam]
  from ⤇ 0
  progress ⤇ 0
  size ⤇ 0
  status = UP
  to ⤇ 0

18.6 Implementations

UnetStack ships with several agents that provide the LINK service. The default underwater acoustic link is ECLink (uwlink), described in full below. UdpLink carries the link service over IP networks, and GenericLink simulates non-acoustic links in the simulator. The older ReliableLink is retained for backward compatibility, and two licensed drivers — HydromeaLink and IridiumLink — provide optical and satellite links respectively.

18.6.1 ECLink (uwlink)

Class	Services	Capabilities	Availability
ECLink	LINK, DATAGRAM	LINK_STATUS, RELIABILITY, FRAGMENTATION, CANCELLATION, COMPRESSION, PRIORITY	default stack

uwlink is the default single-hop underwater link, implemented by the erasure-coded link agent ECLink. It delivers datagrams (including ones larger than a single physical frame) to immediate neighbors, optionally reliably.

18.6.1.1 How it works

The underwater acoustic channel has long propagation delays, so a protocol that acknowledges every fragment and waits for each one wastes a great deal of time. ECLink avoids this with erasure coding: it encodes a datagram into a set of coded fragments and transmits more of them than are strictly needed to reconstruct the data, so the receiver can rebuild the datagram as soon as it has collected enough fragments — it does not matter which ones were lost. The number of fragments needed is ceil(dataLength / fragmentLength); the number actually sent is that figure inflated by a redundancy fraction — reliableExtra for reliable transfers, unreliableExtra for unreliable ones, and robustExtra for the most robust mode. Higher redundancy means a better chance of first-pass delivery at the cost of more airtime.

Small datagrams that fit in a single frame are sent directly, without coding. Larger transfers begin with a setup PDU announcing the transfer (its length, fragment size and flags such as compression); the receiver only needs to acknowledge once the transfer exceeds setupAckThreshold fragments. Frames are sent in batches (at least minBatchSize at a time), and a reliable transfer ends with a short acknowledgement round so the sender can top up any still-missing fragments, retrying up to maxRetries times. Control traffic and bulk data can be sent on different physical channels (controlChannel and dataChannel) — robust transfers below robustControlThreshold bytes use the slow, robust control channel — and gzip compression can be enabled for large datagrams. When a MAC agent is configured, ECLink reserves the channel for each batch, sizing the reservation from the transfer time plus a guard interval set by macGuardTime and macGuardRatio, and allowing for the link’s maxPropagationDelay.

18.6.1.2 Parameters

• mac – medium access control (MAC) agent name to use (or ‘none’)
• phy – physical layer agent name to use
• controlChannel – channel to use for control frames (CONTROL/DATA)
• dataChannel – channel to use for data frames (CONTROL/DATA)
• macGuardTime – MAC reservation guard time (seconds)
• macGuardRatio – MAC reservation guard safety factor (default 0.1)
• maxPropagationDelay – maximum propagation delay (seconds)
• maxRetries – maximum retries for reliable delivery
• minBatchSize – minimum number of frames to send in each batch
• compress – enable data compression
• reliability – default reliability for datagrams
• reliableExtra – extra frames (fraction) for reliable TX
• unreliableExtra – extra frames (fraction) for unreliable TX
• robustExtra – extra frames (fraction) for robust TX
• robustControlThreshold – maximum size to use CONTROL frames for robust TX
• setupAckThreshold – maximum number fragments to send without ACK
• status – show status of ongoing TX/RX on all links

Ongoing transfers can be monitored through indexed parameters, accessed as uwlink[peer]:

Indexed parameters provide information about ongoing transfers per link. The ndx refers to the destination address.

• to – destination address of ongoing transfer
• from – source address of ongoing transfer
• size – size of ongoing transfer (bytes)
• progress – progress of ongoing transfer (0-100 %)
• status – status of the link (up/down)

18.6.1.3 Usage notes

• Raise reliableExtra on poor channels to trade airtime for a better chance of first-pass delivery; lower it on good channels for efficiency.
• Use controlChannel/dataChannel to keep robust control traffic and fast bulk data on the appropriate physical channels.

18.6.2 UdpLink

Class	Services	Capabilities	Availability
UdpLink	LINK, DATAGRAM	RELIABILITY	standard distribution (load manually)

A link over a UDP/IP wired or wireless network, useful when some nodes have Ethernet or WiFi connectivity — cabled seabed nodes, surface buoys on radio LANs, or simulated nodes on the same LAN.

18.6.2.1 How it works

Each UdpLink agent periodically advertises its presence by UDP broadcast (every advertise seconds), so peers on the same network segment discover each other automatically; on networks where broadcast does not work (VPNs, firewalled segments, multiple nodes on one host), peers can be registered manually. Datagrams are carried in UDP packets to the peer’s registered IP address and port, with optional acknowledged retransmission (timeout, retries) for reliable delivery (reliability is not available for broadcast datagrams). Since the underlying network is fast, the MTU is effectively unlimited.

18.6.2.2 Usage notes

• UdpLink is not loaded by default; add it to the stack with container.add 'udplink', new UdpLink().
• See Section 7.1 for worked examples, including manual peer registration and routing traffic over the UDP link.

18.6.3 GenericLink

Class	Services	Capabilities	Availability
GenericLink	LINK, DATAGRAM	RELIABILITY, FRAGMENTATION1	simulator

A simulated link for modelling non-acoustic connectivity — RF links between gateway buoys, WiFi to a surfaced AUV, or cabled links between bottom nodes — directly at the LINK service level, without a modem or channel model. The link’s data rate, MTU, reliability and connectivity (including range- or state-dependent connectivity via a shouldReceive closure) are configured when the agent is created. See Chapter 34 for details and examples.

18.6.4 ReliableLink

Class	Services	Capabilities	Availability
ReliableLink	LINK, DATAGRAM	LINK_STATUS, RELIABILITY, FRAGMENTATION	deprecated

WarningDeprecated

ReliableLink is deprecated and retained only for backward compatibility. For new deployments, use the default uwlink agent (ECLink, Section 18.6.1), which delivers data faster and more robustly over the same channels.

A simple single-hop underwater link offering reliability and fragmentation/reassembly. Where ECLink uses erasure coding to avoid acknowledgement round-trips, ReliableLink uses straightforward acknowledged retransmission.

18.6.4.1 How it works

Outgoing datagrams are fragmented to fit the physical MTU and transmitted in sequence. For reliable delivery, the receiver returns an acknowledgement bitmap indicating which fragments arrived, and the sender retransmits the missing ones (up to maxRetries). It can optionally request a channel reservation from a MAC agent before transmitting, accounting for data and control frames, propagation delay and a guard time.

18.6.4.2 Parameters

• maxRetries – number of retries for reliable delivery
• reservationGuardTime – guard time for channel reservation (seconds)
• maxPropagationDelay – maximum propagation delay (seconds)
• controlChannel – control channel number
• dataChannel – data channel number
• acks – number of acknowledgements for reliable delivery
• mac – MAC agent name (‘none’ for no MAC)
• phy – PHY agent name

18.6.5 HydromeaLink (optical)

Class	Services	Capabilities	Availability
HydromeaLink	LINK, DATAGRAM	RELIABILITY	commercial license

A link driver for Hydromea optical underwater modems, providing high-speed (1–10 Mbps) optical communication.

18.6.5.1 How it works

The agent drives the modem over its HTTP/REST API (caching parameter reads briefly to limit request traffic), and exposes the optical link’s settings as parameters — link speed, transmit power, receiver gain, forward error correction and so on — alongside read-only status such as temperature, throughput and ambient noise.

18.6.5.2 Parameters

• deviceIP — modem IP address.
• linkSpeedMbps — optical link speed (1, 4, 6, 8 or 10 Mbps).
• powerLevel — transmit (LED) power level (0–100%).
• leds — number of transmit LEDs (1–5).
• gainControl — enable automatic gain control.
• fec — enable forward error correction.
• keepAlive — send keep-alive packets.
• Read-only status: temperature, throughput, amplitude, ambient, gain, status, versionInfo, deviceID, active.

18.6.6 IridiumLink (satellite)

Class	Services	Capabilities	Availability
IridiumLink	LINK, DATAGRAM	CANCELLATION, PRIORITY, FRAGMENTATION, COMPRESSION	commercial license

A link driver for the Iridium 9603 satellite modem, providing low-rate (~250 bps) but global connectivity — useful as a backhaul link for a surface gateway node.

18.6.6.1 How it works

The agent manages Iridium Short Burst Data (SBD) sessions over a serial connection or HTTP (mobile or cloud) interface. Outgoing datagrams are queued and sent in satellite sessions; large messages are gzip-compressed and fragmented (up to 256 fragments) with a small header, and reassembled at the far end. In cloud mode, messages are retrieved from the Iridium cloud by polling (poll / pollInterval).

18.6.6.2 Parameters

• poll – poll count (-1 for infinite)
• pollInterval – poll interval (seconds)
• signalQuality – signal quality (0-5)

---

1. Advertised depending on configuration: RELIABILITY when the link is configured as reliable, FRAGMENTATION when RTU < MTU.