17  Physical

org.arl.unet.Services.PHYSICAL

17.1 Overview

The PHYSICAL service is responsible for the transmission and reception of frames over the communication medium. An agent providing this service also provides the DATAGRAM service (Chapter 16) for single-frame datagrams.

Most acoustic modems support more than one type of frame, optimized for different purposes. UnetStack models these as channels, accessed as indexed parameters (Chapter 3). Four standard channels are defined (org.arl.unet.phy.Physical):

• the CONTROL channel (index 1), a low-rate but robust channel typically used for signaling and small control messages;
• the DATA channel (index 2), a higher-rate channel typically used for bulk data transfer;
• the AUX channel (index 3), an auxiliary channel often used for standardized communication schemes such as JANUS and SWiG; and
• the CUSTOM channel (index 4), reserved for user-defined use cases.

Channel parameters are accessed using an index, e.g. phy[CONTROL].dataRate or phy[DATA].MTU. Every modem provides the CONTROL and DATA channels; the remaining channels, and any modem-specific parameters, depend on the modem.

A frame is transmitted by sending a TxFrameReq to the physical agent, specifying the channel type and the data. The agent transmits the frame and reports completion with a TxFrameNtf. On the receiving node, a successfully decoded frame is delivered as a RxFrameNtf, while a frame that is detected but cannot be decoded is reported as a BadFrameNtf. Agents that need fine timing information (e.g. for ranging, Chapter 25) can also subscribe to the TxFrameStartNtf and RxFrameStartNtf notifications, which mark the exact start of transmission and reception.

The TxFrameReq is a subclass of DatagramReq, and the physical agent treats a plain-vanilla DatagramReq as a TxFrameReq with type=DATA. The RxFrameNtf is a subclass of DatagramNtf and is usually delivered to the Topics.DATAGRAM topic. The only exception is for snooped frames, which are delivered to the physical agent’s topic. For more details see Chapter 16.

Beyond plain frames, the physical service also supports transmitting at a precise time and embedding a transmit timestamp in the frame (Section 17.8), interoperable JANUS and SWiG1 frames (Section 17.9), and offline conversion between frames and baseband signals and software FEC decoding (Section 17.10). Each of these depends on a corresponding capability being advertised by the modem.

17.2 Capabilities

Optional features of a physical agent are advertised through capabilities (org.arl.unet.phy.PhysicalCapability), which can be queried with a CapabilityReq:

• TIMED_TX – transmission of frames at a specified time (txStartTime)
• TIMESTAMPED_TX – transmissions with a timestamp encapsulated in the frame (timestamped)
• JANUS – support for JANUS frames (TxJanusFrameReq, delivered as RxJanusFrameNtf)
• SWiG1 – support for SWiG1 frames (TxSWiG1FrameReq, delivered as RxSWiG1FrameNtf)
• SIGNALS – offline conversion between frames and baseband signals (FrameToSignalReq, SignalToFrameReq)
• FEC_DECODING – offline forward-error-correction decoding of soft-decision data (FecDecodeReq)

17.3 Messages

Agents providing this service honor the following request:

• TxFrameReq – transmit a frame

  Field	Type	Default	Remarks
  data	byte[]
  from	int	0	internal use only
  priority	Priority	NORMAL
  progress	boolean	false
  protocol	int	0
  reliability	boolean
  robustness	Robustness	NORMAL
  route	string
  shortcircuit	boolean	true
  timestamped	boolean	false	true for timestamped transmission
  to	int	0
  ttl	float	NaN	time-to-live in seconds
  txStartTime	long		transmission start time for scheduled/timestamped frames
  type	int	1	channel type (CONTROL/DATA/AUX/CUSTOM)
  wakeup	boolean	false

The request is answered with an AGREE once the frame is accepted for transmission, or a REFUSE if it cannot be honored (bad channel type, data longer than the frame capacity, or an unsupported option such as reliability). If the request fails in processing, a FAILURE response may be generated. The agent then generates the following notifications:

• TxFrameStartNtf – frame transmission started

  Field	Type	Default	Remarks
  to	int	-1
  txDuration	int
  txStartTime	long
  type	int	-1

• TxFrameNtf – frame transmission completed

  Field	Type	Default	Remarks
  location	double[]
  to	int	-1
  txStartTime	long
  type	int	-1

• RxFrameStartNtf – frame reception started

  Field	Type	Default	Remarks
  detector	float	0.0
  rxDuration	int
  rxStartTime	long
  type	int	-1

• RxFrameNtf – frame successfully received

  Field	Type	Default	Remarks
  bits	int	0
  bytes	byte[]
  cfo	float	NaN
  data	byte[]
  errors	int
  from	int	0
  location	double[]
  metrics	float[]
  priority	enum	NORMAL
  protocol	int	0
  rssi	float	NaN
  rxStartTime	long
  schemeCode	string
  to	int	0
  ttl	float	NaN
  txStartTime	long
  type	int	1

• BadFrameNtf – frame received with errors

  Field	Type	Default	Remarks
  bytes	byte[]
  location	double[]
  metrics	float[]
  rssi	float	NaN
  rxStartTime	long
  schemeCode	string
  type	int	-1

The TxFrameNtf is sent to the agent that requested the transmission, while the TxFrameStartNtf, RxFrameStartNtf and BadFrameNtf notifications are published on the physical agent’s topic. A received frame (RxFrameNtf, a DatagramNtf subtype) follows the datagram delivery convention (Chapter 16): frames addressed to this node (or broadcast) are published on the global Topics.DATAGRAM topic, while frames overheard for other nodes are published on the agent’s own topic — so subscribing to the physical agent lets you snoop on all traffic within earshot. TxFrameNtf is a subclass of DatagramTransmissionNtf, and is sent back only to the requester of the original transmission request.

Depending on the capabilities it advertises, an agent may honor additional requests: TxJanusFrameReq and TxSWiG1FrameReq for standardized frames (Section 17.9), and FrameToSignalReq, SignalToFrameReq and FecDecodeReq for offline signal processing (Section 17.10). These messages, and the notifications they generate, are described in the corresponding sections below. Physical agents also honor ClearReq (Chapter 16) — it aborts any ongoing or queued transmission and flushes the transmit queue, and is most conveniently sent using the pclr shell command.

17.4 Parameters

The following parameters are available on all modems. Additional modem dependent parameters may also be available.

• MTU – maximum transmission unit (MTU) in bytes
• RTU – recommended data transfer size in bytes
• rxEnable :: boolean – true if reception enabled
• timestampedTxDelay :: float – delay before TX of timestamped frames
• time :: long – physical layer time (microseconds)
• busy :: boolean – true if modem is TX/RX a frame, false if idle
• maxPowerLevel :: float – maximum supported power level (relative to reference)
• minPowerLevel :: float – minimum supported power level (relative to reference)
• baseband :: String – name of baseband service provider

The time parameter deserves special mention: it reports the physical layer’s own clock in microseconds, which timestamps all txStartTime/rxStartTime fields in the physical-layer messages. This clock is generally not synchronized to the system clock, but is precise, making it the time base for ranging and scheduled transmissions.

17.5 Channel parameters

In addition to the agent parameters above, each channel exposes a set of indexed parameters, accessed as phy[CONTROL], phy[DATA], etc.:

The following parameters are available on all modems. Additional modem dependent parameters may also be available.

• MTU – maximum transmission unit (MTU) in bytes

• RTU – recommended data transfer size in bytes

• dataRate :: float – effective frame data rate (bps)

• frameDuration :: float – frame duration (seconds)

• powerLevel :: float – transmission power level (dB re reference)

• frameLength :: int – frame length (bytes)

• maxFrameLength :: int – maximum settable frame length (bytes)

• fec :: String – forward error correction code

  A value of none indicates no error correction. Other values represent various FEC codes from the phy[].fecList.

• fecList :: String[] (nullable) – list of available forward error correction codes

  ldpc-1/1 - 1-rate LDPC FEC code
  ldpc-2/3 - 2/3-rate LDPC FEC code
  ldpc-1/2 - 1/2-rate LDPC FEC code
  ldpc-1/3 - 1/3-rate LDPC FEC code
  ldpc-1/4 - 1/4-rate LDPC FEC code
  ldpc-1/5 - 1/5-rate LDPC FEC code
  ldpc-1/6 - 1/6-rate LDPC FEC code
  ldpcv3-1/1 - 1-rate LDPC FEC code (compatible with UnetStack3)
  ldpcv3-1/3 - 1/3-rate LDPC FEC code (compatible with UnetStack3)
  ldpcv3-1/4 - 1/4-rate LDPC FEC code (compatible with UnetStack3)
  ldpcv3-1/5 - 1/5-rate LDPC FEC code (compatible with UnetStack3)
  ldpcv3-1/6 - 1/6-rate LDPC FEC code (compatible with UnetStack3)
  iconv-1/2 - 1/2-rate interleaved convolution code
  janus-spec - 1/2-rate interleaved convolution code as per JANUS specifications
  janus-ref - 1/2-rate interleaved convolution code as per JANUS reference impl.
  bch-1/3 - 1/3-rate BCH code
  bch-1/4 - 1/4-rate BCH code
  bch-1/5 - 1/5-rate BCH code
  

  The 1-rate LDPC code is only useful for OFDM, where unused bits in the last OFDM block are used to provide FEC redundancy without loss in data rate. The above list is for illustration purposes only; the actual list of available FEC codes may vary depending on the modem implementation.

• framing :: String – framing type name (from phy[].framingList)

• framingList :: String[] (nullable) – list of available framing types

• modulation :: String (nullable) – modulation type name (from phy[].modulationList)

  A value of none indicates no modulation. Other values represent various modulation types from the phy[].modulationList.

  Additional channel parameters may be available for specific modulation types.

• modulationList :: String[] (nullable) – list of available modulation types

• schemeCode :: String – short code encoding all modulation/fec details

A few relationships between these parameters are worth knowing. The frameLength is the physical frame size — the MTU plus the frame header, whose size depends on the device and its configuration (for example, the address size, node.addressSize). To change the frame size, set frameLength; the channel’s MTU is derived from it. The advertised dataRate counts all the bits in the frame, header included, so the effective user data rate is a little lower. And powerLevel is constrained to lie between the modem’s minimum and maximum power levels (see the baseband parameters, Chapter 27).

NoteCommunication schemes

What a channel actually puts in the water is defined by its scheme — the combination of framing, modulation and fec (forward error correction) configured on that channel. Each is a channel parameter, and the companion framingList, modulationList and fecList parameters advertise what the modem supports. The available choices and their detailed parameters (rates, bandwidths, code strengths) are modem-specific, so consult your modem’s documentation when tuning them; standardized framings such as JANUS and SWiG1 (Section 17.9) are usually carried on the AUX channel. Modems may also expose a schemeCode parameter that captures a channel’s entire scheme (modulation, frame length and FEC) in a single value — handy for noting a working configuration and restoring it later. Whatever scheme you choose, configure it identically on every node: modems speaking different schemes detect each other’s frames but cannot decode them.

17.6 Commands

• pclr – clear PHY queues

• plvl – get/set TX power level for all PHY channel types

  Examples:

  plvl                       // get all power levels
  plvl -10                   // set all power to -10 dB
  plvl(-10)                  // alternative syntax
  plvl = -10                 // alternative syntax
  

• aux – setup auxiliary channel

  Examples:

  aux none                   // disable PHY[AUX]
  aux janus                  // set phy[AUX] to JANUS
  aux janus()                // set phy[AUX] to JANUS
  aux janus(19000, 320)      // set PHY[AUX] to JANUS fmin=19kHz, fstep=320Hz
  aux janus('E')             // set phy[AUX] to JANUS band E
  aux swig1                  // set PHY[AUX] to SWiG1
  aux swig1()                // set PHY[AUX] to SWiG1
  aux swig1(9000, 320)       // set PHY[AUX] to SWiG1 fmin=9kHz, fstep=320Hz
  aux swig1(3, 4)            // set PHY[AUX] to SWiG1 extended fc code 3 rate 4
  aux DATA, janus()          // set PHY[DATA] to JANUS
  aux DATA, swig1()          // set PHY[DATA] to SWiG1

17.7 Examples

Connect to a node’s shell and inspect the physical agent and its CONTROL channel:

> phy
« Half-duplex modem »

Generic half duplex modem simulator.

[org.arl.unet.DatagramParam]
  MTU ⤇ 123
  RTU ⤇ 123

[org.arl.unet.UnetParam]
  queueLength ⤇ 0

[org.arl.unet.bb.BasebandParam]
  adcChannels ⤇ 1
  adcrate ⤇ 96000.0
  analogInterface ⤇ HalfDuplexModem
  basebandRate = 24000.0
  bbsblk ⤇ 0
  bbscnt ⤇ 0
  bbsport ⤇ 0
  busy ⤇ false
  carrierFrequency = 24000.0
  clockCalib ⤇ 1.0
  dacChannels ⤇ 1
  dacrate ⤇ 96000.0
  depthToConsiderInWater ⤇ 0.0
  enable = true
  fullduplex ⤇ false
  gain ⤇ [0.0]
  ip ⤇ 0.0.0.0
  maxInAirPowerLevel ⤇ 0.0
  maxPowerLevel = 0.0
  maxPreambleID ⤇ 8
  maxSignalLength = 65536
  minPowerLevel = -96.0
  mute ⤇ true
  noise ⤇ [96.1236]
  pbsblk ⤇ 0
  pbscnt ⤇ 0
  pbsport ⤇ 0
  powerLevel = [-10.0]
  record ⤇ false
  refPowerLevel = 185.0
  rxSensitivity = -185.0
  standby ⤇ 0.0
  syncBasebandTime ⤇ null
  syncSystemTime ⤇ null
  time ⤇ 1882390162
  wakeupDelay ⤇ 0

[org.arl.unet.phy.PhysicalParam]
  baseband ⤇ phy
  busy ⤇ false
  maxPowerLevel = 0.0
  minPowerLevel = -96.0
  rxEnable = true
  time ⤇ 1882388162
  timestampedTxDelay = 1.0

[org.arl.unet.sim.HalfDuplexModemParam]
  clockOffset = 1880.9872

> phy[CONTROL]
« PHY »

[org.arl.unet.DatagramParam]
  MTU ⤇ 13
  RTU ⤇ 13

[org.arl.unet.bb.BasebandDetectorParam]
  capture ⤇ 13488
  coherence ⤇ 0
  inhibit ⤇ 0
  metricStatistics ⤇ 0.0
  preamble = [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0 ... , 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  stride ⤇ 1
  threshold ⤇ 0.0

[org.arl.unet.phy.PhysicalChannelParam]
  dataRate = 247.42267
  fec ⤇ default
  fecList ⤇ null
  frameDuration ⤇ 0.582
  frameLength = 18
  framing ⤇ default
  framingList ⤇ null
  maxFrameLength = 128
  modulation ⤇ default
  modulationList ⤇ null
  powerLevel = -10.0
  schemeCode ⤇ null

Transmit a frame on the CONTROL channel and watch for the completion notification:

> subscribe phy
> phy.signalPowerLevel = -6;
> phy << new TxFrameReq(type: CONTROL, data: [1, 2, 3, 4])
AGREE
phy >> TxStartNtf:INFORM[preamble:1 txStartTime:1322147017 txDuration:582000]
phy >> TxFrameStartNtf:INFORM[type:CONTROL to:0 txStartTime:1322147017 txDuration:582000]
phy >> TxEndNtf:INFORM[preamble:1 txStartTime:1322147017]
phy >> TxFrameNtf:INFORM[type:CONTROL to:0 txStartTime:1322147017]

On a node within range, a successfully decoded frame is delivered as an RxFrameNtf:

phy >> DetectionNtf:INFORM[preamble:1 rxStartTime:555826740 rxDuration:582000]
phy >> RxFrameStartNtf:INFORM[type:CONTROL rxStartTime:555826740 rxDuration:582000]
phy >> RxBasebandSignalNtf:INFORM[rxStartTime:555826740 preamble:1 fc:24000.0 fs:24000.0 (13968 baseband samples)]
phy >> RxFrameNtf:INFORM[type:CONTROL from:232 rxStartTime:555826740 rssi:-72.6 (4 bytes)]
  01020304

Warning

Sending a TxFrameReq directly to phy bypasses medium access control — the frame goes out without consulting the MAC agent, and may collide with other traffic the MAC is coordinating. That is fine for a quick test on a quiet channel, but an agent or application transmitting regularly should reserve the channel through the MAC service first (Chapter 19), or hand its data to a higher-layer agent (uwlink and above) that does so on its behalf. Undisciplined direct transmissions can degrade the performance of the whole network.

17.8 Timed & timestamped transmissions

The physical service offers two independent timing features that are the foundation of coordinated channel access and one-way ranging: transmitting a frame at a precisely chosen instant, and embedding the transmit time within the frame itself.

Timed transmission (TIMED_TX capability). By default, a TxFrameReq is transmitted as soon as the channel is free. Setting txStartTime to a value on the physical-layer clock (phy.time, in microseconds) instead defers the transmission until exactly that instant. This lets several nodes agree in advance on when each will transmit — the basis for TDMA-style slotting (Chapter 19), for synchronized array transmissions, and for replying a fixed, known delay after a received frame (as in two-way ranging).

Here we schedule a CONTROL frame to be transmitted one second (10⁶ µs) in the future; the resulting TxFrameNtf reports a txStartTime matching the requested instant:

> phy << new TxFrameReq(type: CONTROL, data: [1, 2, 3], txStartTime: phy.time+1000000)
AGREE
phy >> TxFrameNtf:INFORM[type:CONTROL to:0 txStartTime:1449814333]

Timestamped transmission (TIMESTAMPED_TX capability). Setting timestamped = true asks the modem to encode the actual moment of transmission into the frame. The receiver recovers this instant and reports it as a txStartTime field on the RxFrameNtf, alongside its own local rxStartTime. Having both timestamps — the departure time on the sender’s clock and the arrival time on the receiver’s clock — is what one-way ranging and clock synchronization build on (Chapter 25). The two features are independent and may be combined: txStartTime on the request controls when the frame leaves, while timestamped controls whether the frame carries its own departure time.

Two caveats. The embedded timestamp is not free: it takes 6 bytes out of the frame, so a timestamped frame carries 6 bytes less payload than the channel’s advertised MTU. And the two timestamps on a received frame are on different clocks — the txStartTime is on the sender’s physical-layer clock, the rxStartTime on the receiver’s — so they cannot be compared directly; relating them requires an estimate of the clock offset between the nodes, which is exactly what the RANGING service’s synchronization machinery provides (Section 25.6.2).

We transmit a timestamped CONTROL frame from node A; its TxFrameNtf reports the transmit time:

> phy << new TxFrameReq(type: CONTROL, data: [1, 2, 3], timestamped: true)
AGREE
phy >> TxFrameNtf:INFORM[type:CONTROL to:0 txStartTime:1646040041]

At node B, the received frame’s RxFrameNtf now carries a txStartTime — the transmit instant recovered from the frame, matching the value the sender reported — in addition to the local rxStartTime (an ordinary, non-timestamped frame’s RxFrameNtf has no txStartTime):

phy >> RxFrameNtf:INFORM[type:CONTROL from:232 rxStartTime:2938870500 txStartTime:1646040041 rssi:-72.6 (3 bytes)]
  010203

17.9 JANUS & SWiG1

Alongside its native waveforms, a modem may support standardized frame formats that allow interoperability with equipment from other vendors. UnetStack supports two, each gated by its own capability and carried on the AUX channel:

• JANUS — the international standard (NATO STANAG 4748 / ANEP-87) for interoperable underwater acoustic signaling. Any two modems that implement JANUS can exchange a well-defined baseline packet even without sharing a proprietary waveform. Requires the JANUS capability.
• SWiG1 — a frame format defined by the Subsea Wireless Group (SWiG) for use in the offshore energy industry. Requires the SWiG1 capability.

17.9.1 JANUS

A JANUS packet carries a compact application data block (ADB) together with standardized header fields: a classUserID and appType that identify the meaning of the payload, mobility and forwarding (canForward) flags, and optional channel-reservation (reservationDuration) or repeatInterval scheduling. It may optionally carry a cargo of user data. A JANUS frame is transmitted with a TxJanusFrameReq:

• TxJanusFrameReq – transmit a JANUS frame

  Field	Type	Default	Remarks
  appData	long	0	application data block (ADB)
  appType	int	0	application type, as defined by class user
  canForward	boolean		forwarding-capability flag, null to derive from routing availability
  classUserID	int	42	class user ID (ANEP-87 Annex A)
  data	byte[]
  from	int	0
  mobility	boolean		mobility flag, null to derive from node mobility
  priority	enum	NORMAL
  progress	boolean	false
  protocol	int	0
  reliability	boolean
  repeatInterval	float	0.0	repeat interval in seconds, 0 for non-periodic (only if no cargo)
  reservationDuration	float	0.0	channel reservation in seconds (only if no cargo)
  robustness	enum	NORMAL
  route	string
  shortcircuit	boolean	true
  timestamped	boolean	false
  to	int	0
  ttl	float	NaN
  txRxFlag	boolean	true
  txStartTime	long
  type	int	3
  wakeup	boolean	false

A received JANUS frame is delivered as a RxJanusFrameNtf (a RxFrameNtf subtype), which decodes the standardized fields:

• RxJanusFrameNtf – received JANUS frame

  Field	Type	Default	Remarks
  appData	long	0
  appType	int	0
  bits	int	0
  bytes	byte[]
  canForward	boolean	false
  cfo	float	NaN
  classUserID	int	0
  data	byte[]
  errors	int
  from	int	0
  location	double[]
  metrics	float[]
  mobility	boolean	false
  priority	enum	NORMAL
  protocol	int	0
  repeatInterval	float	0.0
  reservationDuration	float	0.0
  rssi	float	NaN
  rxStartTime	long
  schemeCode	string
  to	int	0
  ttl	float	NaN
  txRxFlag	boolean	false
  txStartTime	long
  type	int	3

To see this in action, we transmit a minimal JANUS frame — its baseline packet, carrying no cargo — from node A:

> phy << new TxJanusFrameReq()
AGREE
phy >> TxFrameNtf:INFORM[type:AUX to:0 txStartTime:326461655]

On node B, it is decoded and delivered as a RxJanusFrameNtf, complete with the standardized header fields:

phy >> DetectionNtf:INFORM[preamble:3 rxStartTime:3066706193 rxDuration:820000]
phy >> RxFrameStartNtf:INFORM[type:AUX rxStartTime:3066706193 rxDuration:820000]
phy >> RxBasebandSignalNtf:INFORM[rxStartTime:3066706193 preamble:3 fc:24000.0 fs:24000.0 (19680 baseband samples)]
phy >> RxJanusFrameNtf:INFORM[type:AUX classUserID:42 appType:0 appData:0 mobility:false canForward:true txRxFlag:true rxStartTime:3066706193 rssi:-72.6]

17.9.2 SWiG1

A SWiG1 frame carries an ADB of up to 49 bits. It is transmitted with a TxSWiG1FrameReq and received as a RxSWiG1FrameNtf:

• TxSWiG1FrameReq – transmit a SWiG1 frame

  Field	Type	Default	Remarks
  appData	long	0
  data	byte[]
  from	int	0
  priority	enum	NORMAL
  progress	boolean	false
  protocol	int	0
  reliability	boolean
  robustness	enum	NORMAL
  route	string
  shortcircuit	boolean	true
  timestamped	boolean	false
  to	int	0
  ttl	float	NaN
  txStartTime	long
  type	int	3
  wakeup	boolean	false

• RxSWiG1FrameNtf – received SWiG1 frame

  Field	Type	Default	Remarks
  appData	long	0
  bits	int	0
  bytes	byte[]
  cfo	float	NaN
  data	byte[]
  errors	int
  from	int	0
  location	double[]
  metrics	float[]
  priority	enum	NORMAL
  protocol	int	0
  rssi	float	NaN
  rxStartTime	long
  schemeCode	string
  to	int	0
  ttl	float	NaN
  txStartTime	long
  type	int	3

Usage mirrors JANUS — phy << new TxSWiG1FrameReq(data: adb) on the sender, with the receiver seeing a RxSWiG1FrameNtf. SWiG1 support is modem-specific and is not provided by the simulator, so no runnable example is shown here.

17.10 Signal-frame conversion & FEC decoding

These are offline operations: they process signals and frames within the modem without transmitting or receiving anything over the channel. They require the SIGNALS and FEC_DECODING capabilities, which are available on modem hardware but not in the simulator.

17.10.1 Signal-frame conversion

With the SIGNALS capability, a modem can convert between the byte content of a frame and the baseband signal that represents it on the wire:

• FrameToSignalReq asks the modem to synthesize the baseband signal it would transmit for a given frame, returning it as a RxBasebandSignalNtf (Chapter 27). This is useful for capturing a reference waveform, or for feeding the signal to an external transmitter.
• SignalToFrameReq does the reverse: it decodes a supplied baseband signal into a frame, replying with a RxFrameNtf (or a BadFrameNtf if the signal cannot be decoded). The preamble field selects which frame type to decode against, and must be set even if the signal was not originally detected via a preamble. This lets a previously recorded signal (Chapter 27) be re-decoded in software.

• FrameToSignalReq – convert a frame to a baseband signal

  Field	Type	Default	Remarks
  bytes	byte[]
  data	byte[]
  from	int	0
  protocol	int	0
  to	int	0
  type	int	1

• SignalToFrameReq – decode a baseband signal into a frame

  Field	Type	Default	Remarks
  channels	int	1
  fc	float	-1.0
  fs	float	-1.0
  location	double[]
  preamble	int	0
  preambleLength	int	0
  rssi	float	NaN
  rxStartTime	long
  signal	float[]
  signal__isComplex	boolean	false

17.10.2 FEC decoding

When a frame arrives too corrupted for the modem to decode in hardware, the soft-decision (log-likelihood) data from the failed decode can be handed back to the physical agent as a FecDecodeReq for a second attempt at forward-error-correction decoding in software. On success the agent replies with a RxFrameNtf; on failure, with a BadFrameNtf. In both cases the notification’s inReplyTo field is set to the request’s message ID. The type field selects the channel whose FEC code should be used.

• FecDecodeReq – software FEC decoding of soft-decision data

  Field	Type	Default	Remarks
  location	double[]
  metrics	float[]		soft-decision (log-likelihood) data to decode
  rssi	float	NaN
  rxStartTime	long
  type	int	2	channel for FEC code selection (CONTROL/DATA)

17.11 Implementations

Unlike most services, the PHYSICAL service is not loaded by setup.groovy; it is provided by the modem itself. Either way, the higher layers see the same PHYSICAL service contract described above.

17.11.1 Modem firmware (phy)

Class	Services	Capabilities	Availability
modem firmware	PHYSICAL, DATAGRAM	modem-dependent	commercial modems

On a commercial modem, the physical layer is provided by the modem firmware, which runs its own agents on the modem’s signal-processing hardware. From the rest of the stack’s point of view, there is simply a phy agent providing PHYSICAL. The available channels, modulation and FEC schemes, and the advertised capabilities depend on the modem model and configuration; query them through the channel parameters (framingList, modulationList, fecList) and a CapabilityReq.

Real modems may provide additional parameters that are useful in testing and field operations; ask for help phy on the modem for the full list. On Unet modems, the firmware’s physical layer provides the following agent-specific parameters.

17.11.1.1 Parameters

In addition to the service-level parameters documented earlier in this chapter, each channel supports:

• detector – baseband detector number

• test – enable test mode

• valid – true if the channel parameters are valid, false otherwise

• preambleGap – preamble gap in baseband samples

• scrambler – scrambler seed (0 to disable)

• combining – spatial diversity combining mode (channel #, auto, best, all)

  If combining is set to a channel number, only that channel will be used for reception. If it is set to ‘best’, a single channel with the best SNR will be used for reception. When set to ‘all’, all channels are combined for reception. When set to ‘auto’, a performant subset of the channels will be automatically selected for combining.

  Example:

  phy[2].combining = 2       // use only channel 2
  phy[2].combining = 'auto'  // auto select channels for combining

17.11.1.2 Modulation parameters

Each channel’s modulation scheme is selected through its modulation parameter (from among modulationList). Scheme-specific parameters then become available on that channel.

17.11.1.2.1 OFDM (ofdm)

Orthogonal Frequency Division Multiplexing (OFDM) is a modulation technique that is widely used in many wireless communication systems including underwater acoustic communication. OFDM is especially well-suited to deal with multi-path propagation and frequency selective fading.

When phy[].modulation is set to ‘ofdm’, the following modulation parameters are available:

• nc – number of carriers (power of 2)
• np – cyclic prefix length
• ns – cyclic suffix length
• bw – bandwidth fraction (0-1)
• bitsperblk – bits per block (readonly)
• dc0 – placement of DC carrier
• psk – 2 for BPSK, 4 for QPSK
• backoff – backoff in dB
• sync – length of sync signal for Doppler estimation
• syncsps – baseband samples per sync symbol
• windowed – true for windowed OFDM, false otherwise

17.11.1.2.2 FHBFSK (fhbfsk)

FHBFSK (Frequency Hopping Binary Frequency Shift Keying) modulation is commonly used to achieve reliable communication underwater. The default parameters provide robust low-rate communication in most environments. Some of the parameters can be adjusted to optimize performance for specific conditions.

When phy[].modulation is set to ‘fhbfsk’, the following modulation parameters are available:

• fmin – minimum frequency (Hz)

• fstep – frequency step (Hz)

  fstep controls the frequency spacing between hops. Each hop uses 2 frequencies for bit 0 and bit 1. Therefore each hop is 2*fstep wide. The total bandwidth used by the signal is 2 * fstep * hops.

• hops – hopping sequence

  The hopping sequence determines the frequency hopping pattern. The sequence can be specified as a list of integers or a symbol that represents a predefined hopping sequence. If only the number of hops is specified, a random sequence is generated using the specified seed.

  Example:

  phy[2].hops = 7                 // generate a random 7-hop sequence
  phy[2].hops = 'janus'           // use the JANUS hopping sequence
  phy[2].hops = [3,1,2,4,0]       // use a custom 5-hop hopping sequence
  

• offset – hop offset (hop number for the first symbol)

  FHBFSK based schemes such as JANUS use the hopping sequence to generate a preamble and then continue the hopping for the data symbols. An offset is required in such cases to account for the number of hops in the preamble.

• chiplen – chip length (symbols, default: 1)

  Longer chip lengths can improve the robustness of the signal against multipath and noise, but reduce the data rate.

• sync – true to enable Doppler compensation, false to disable

• guard – true to insert a guard interval after the preamble

  The guard interval prevents inter-symbol interference from the preamble. However, if the preamble also uses the same hopping sequence, a guard interval may not be necessary.

17.11.1.2.3 Probe (probe)

The probe modulation is a generalized m-sequence modulated BPSK signal used for channel probing.

When phy[].modulation is set to ‘probe’, the following modulation parameters are available:

• fc – center frequency (Hz)
• repeats – number of m-sequence repeats (1 to 16)
• spec – m-sequence specifier (2 to 30, length is 2^spec - 1)
• sps – baseband samples per symbol (1 to 16)

17.11.2 HalfDuplexModem (phy)

Class	Services	Capabilities	Availability
HalfDuplexModem	PHYSICAL, DATAGRAM, BASEBAND, DOA	TIMESTAMPED_TX, TIMED_TX, JANUS	simulator

In simulation, the HalfDuplexModem agent stands in for the modem. It models transmission/reception timing, half-duplex operation, path loss, interference and SNR-based frame errors using a pluggable channel model, so that the same higher-layer agents run unchanged against a simulated channel. All four standard channels are provided, with per-channel data rate, frame length and power level configurable through the simulation’s modem settings — the simulation-specific parameters and channel models are documented in Chapter 34.

17.11.3 Popoto (modem driver)

Class	Services	Capabilities	Availability
Popoto	PHYSICAL, DATAGRAM	—	commercial license

A physical-layer driver for Popoto acoustic modems, allowing a Popoto modem to be used as the physical layer beneath the rest of the stack.

17.11.3.1 How it works

The agent connects to the modem over TCP and exchanges JSON commands and responses. It supports two channels — control and data — each with selectable modulation (FSK at 80 bps, or PSK at 640–10240 bps) and configurable transmit power, and manages transmission and reception state machines with timeout monitoring and automatic reconnection.

17.11.3.2 Parameters

• Per-channel [1, 2]: Modulation (fsk, psk1–psk5), PowerLevel (−80 to 0 dBm), and read-only DataRate, FrameDuration, Fec.
• Global: read-only MTU/RTU (255 bytes), RxEnable, Busy, Time, and power-level limits.