35 Virtual acoustic ocean

The simulator we met in Chapter 34 runs entire networks in software, using channel models (Section 34.8) that decide whether each frame is detected and decoded. That is perfect for developing protocols and agents, but nothing physical is exercised — the modem, its signal processing and the acoustic signals themselves are all abstracted away. The Virtual Acoustic Ocean (VAO) takes realism one step further: it simulates the ocean itself, at acoustic sample level and in realtime, and lets real modems transmit and receive through it. In this chapter we set up a small network of two real modems and a laptop, connect them through a virtual ocean, and explore what such hardware-in-the-loop simulation can and cannot do for us.

35.1 Hardware-in-the-loop simulation

Between simulation and a sea trial lies a wide gap. Sea trials are expensive and slow — boats, permits, weather windows, batteries, deck crews — and the ocean never gives you the same channel twice, so a failed run tells you little about whether your fix worked. Simulations are cheap and repeatable, but they only test your protocol logic; the modem hardware, firmware, drivers and physical-layer signal processing that you will actually deploy remain untested until you get wet.

Hardware-in-the-loop (HIL) simulation closes this gap. The idea: keep the real modems in the loop — real firmware, real network stack, real signal processing, real timing — and replace only the ocean with a simulation. Your frames are modulated into acoustic signals exactly as they would be at sea, but instead of being fed to a power amplifier and transducer, the signals travel through a simulated acoustic channel to the other modems.

The Virtual Acoustic Ocean is an open-source Julia package that provides exactly this: a realtime acoustic simulator that models the analog front-end (ADC/DAC) of each node, propagates transmitted signals through an acoustic propagation model, adds ambient noise, and streams the resulting received signals back to each node — over Ethernet.

What is real, and what is virtual?

With a VAO in the loop, everything above the analog front-end is real: the modem’s processor, firmware, physical-layer signal processing (modulation, synchronization, equalization, coding), the UnetStack agents, and all timing behavior. What is virtual: the power amplifier, transducer, hydrophone — and the ocean between them.

35.1.1 How it works

A software-defined modem does all of its signal processing in software; only a thin analog front-end — the data acquisition (DAQ) hardware that converts between samples and voltages — touches the water. In UnetStack-based modems, this front-end sits behind a well-defined DAQ interface: the physical layer hands passband samples to the DAQ for transmission, and receives a continuous stream of passband samples from it. Since the interface is just samples in and samples out, the DAQ can be swapped without the rest of the modem noticing.

That swap is exactly what the UASP2DAQ analog interface does. Instead of driving local DAQ hardware, it speaks the UASP2 protocol over the network: commands and transmitted signals are exchanged as JSON messages over a TCP connection, while received signals stream in as timestamped, sequence-numbered UDP packets. On the other side of that connection sits the virtual acoustic ocean, which implements the same protocol — one port per simulated node.

When a modem transmits, its passband samples are delivered to the VAO, which passes them through the configured propagation model to compute the received signal at every other node — multipath arrivals, propagation delay, and transmission loss, with the transmit and receive sensitivities modelled by two reference levels (txref, the source level of a full-scale DAC signal, and rxref, the ADC output for a unit acoustic pressure). The received signals are summed with modelled ambient noise and streamed continuously to each node at its ADC rate — by default 4× the carrier frequency (96 kSa/s for a 24 kHz carrier), with an 8× DAC rate on the transmit side. From where the modem stands, this is indistinguishable from a quiet ocean: it “hears” noise all the time, and receives whatever the other modems transmit, delayed and distorted by the channel.

35.2 Setting up a virtual acoustic ocean

To set up a HIL simulation, we need two UnetStack-based modems, an Ethernet switch, and a laptop (or any computer) to host the virtual ocean. Connect the modems and the laptop to the same subnet — a small isolated switch is ideal, keeping the high-rate signal streaming traffic away from your office network.

The laptop needs Julia installed, along with two packages:

using Pkg
Pkg.add("VirtualAcousticOcean")
Pkg.add("UnderwaterAcoustics")

A virtual ocean is described by a small Julia script. Here is a complete 2-node scenario (2-node-network.jl) that places two nodes 1 km apart in 40 m deep water:

using VirtualAcousticOcean
using UnderwaterAcoustics
using Sockets

1env = UnderwaterEnvironment(seabed=SandyClay, bathymetry=40.0)
2pm = PekerisRayTracer(env)
3sim = Simulation(pm, 24000.0)
4addnode!(sim, (0.0, 0.0, -10.0), UASP2, 9809, ip"0.0.0.0")
5addnode!(sim, (1000.0, 0.0, -10.0), UASP2, 9819, ip"0.0.0.0")
6run(sim)
wait()

1: Describe the ocean: 40 m water depth over a sandy-clay seabed.
2: Choose a propagation model — here a Pekeris ray tracer, which models multipath in an iso-velocity shallow-water channel.
3: Create a realtime simulation with a nominal (carrier) frequency of 24 kHz.
4: Add node 1 at the origin, at 10 m depth (coordinates are (x, y, z) in meters, with z negative below the sea surface). The node is served over the UASP2 protocol on port 9809, bound to 0.0.0.0 so that modems elsewhere on the network can connect.
5: Add node 2, 1 km away in the x direction, on port 9819.
6: Start the simulation, and keep the script alive.

The VAO streams signals in realtime, so it should be run with multiple threads enabled:

$ julia --threads auto 2-node-network.jl

The virtual ocean is now up, waiting for modems to connect on ports 9809 and 9819.

Tip

Simulation accepts keyword arguments to customize the physics — noise (ambient noise model, default a red Gaussian noise), txref and rxref (transmit/receive reference levels, defaults 185 dB re µPa @ 1 m and −190 dB re 1/µPa), and irate/orate (ADC/DAC rates). The defaults work well with UnetStack modems, so you rarely need to touch them.

35.2.1 Propagation models

The channel physics comes from UnderwaterAcoustics.jl — an open-source Julia toolkit for underwater acoustic propagation modelling. It provides a unified API in which you describe an environment (bathymetry, sound speed profile, seabed, sea surface) and then pick a propagation model to solve it: fast analytical models such as the Pekeris ray tracer and mode solver, a general-purpose ray/Gaussian-beam tracer, and — through companion packages — wrappers around classical models such as Bellhop and Kraken. Because the VAO Simulation accepts any propagation model with this API, changing fidelity is a one-line change to the scenario script: develop against a fast ray model, then rerun the same network through a full mode solver when accuracy matters.

Caution

While any UnderwaterAcoustics.jl propagation model works with VAO in theory, in practice you need to ensure that you are running on a fast enough hardware that the model runs in real-time. If the model takes longer than the propagation delay to run, the timings you will see using VAO will be incorrect and protocols will fail!

Better still, the channel does not have to be synthetic at all. The ReplayChannelModel replays measured time-varying impulse responses through the virtual ocean, convolving each transmission with a channel recorded at sea:

pm = ReplayChannelModel("channel.mat")
sim = Simulation(pm, 24000.0)

A curated library of measured underwater acoustic channels — impulse responses and noise recordings from at-sea experiments around the world — is available at Underwater Acoustic Channel Library. Replaying a curated experimental channel through real modem hardware is about the most realistic test you can do without a boat: had you been on that experiment, with these modems, this is what your physical layer would have experienced.

35.3 Setting up the modems

Each modem must be told to use the virtual ocean, instead of its own analog electronics, as its front-end. This is done through the modem configuration file modem.toml, which selects the analog interface. On the first modem:

[input]
1analoginterface = "UASP2DAQ"
2ip = "192.168.42.10"
3port = 9809

[output]
4analoginterface = "UASP2DAQ"

[bb]
5fc = 24000

1: Take received (input) signals from a UASP2 server, rather than the local ADC.
2: IP address of the laptop running the virtual ocean.
3: UASP2 port of this node in the scenario script.
4: Send transmitted (output) signals to the same UASP2 server, rather than the local DAC.
5: Carrier frequency — must match the nominal frequency of the Simulation.

The second modem gets an identical file, with port = 9819. Place the modem.toml on each modem (e.g. upload it through the scripts folder in the modem’s web interface) and reboot the modem for it to take effect.

When the modem boots, its physical layer connects to the virtual ocean. You can verify this from the modem’s log file:

Connecting to UASP2 DAQ at 192.168.42.10:9809...

Once both modems are connected, you have a 2-node underwater network on your bench — real modems, virtual ocean.

35.4 Talking through the virtual ocean

Time for the fun part. Open the web shell of the first modem, and transmit a message:

> plvl 0
OK
> tell 0, 'hello sea!'
OK

About two-thirds of a second later — the time sound takes to travel 1 km — the message shows up on the second modem’s shell:

[174]: hello sea!

That message was modulated by real modem firmware, propagated (virtually) through 1 km of shallow water complete with multipath and noise, and demodulated by real modem firmware on the other side. Setting plvl 0 asks the modem to transmit at full power — with the default txref, a comfortable source level for a 1 km virtual link.

Since the propagation delay is faithfully modelled, ranging (Chapter 25) works too. On the second modem:

> range 174
1000.03

The range estimate matches the geometry we set up in the scenario script — the two nodes are 1 km apart in the virtual ocean.

And that is the point of HIL simulation: from here on, everything in this handbook works unchanged. You can run UnetSocket applications against these modems (Chapter 9), transfer files, set up routes, measure link performance, or test the agents you developed in Chapter 33 — on real modem hardware, under a controlled and repeatable acoustic channel.

35.5 Advantages & limitations

Compared to the network simulator of Chapter 34, a VAO-based HIL setup tests the system you will actually deploy: modem hardware, firmware, physical-layer signal processing and your network stack, end-to-end, at acoustic sample level. Compared to a sea trial, it is cheap, always available, and — most valuable of all — repeatable: the same channel, every run, so you can tell whether performance changed because of your code or because of the ocean. The environment is fully controllable, from a benign deep-water channel to a harsh replayed experimental one, making it ideal for regression-testing modem firmware, evaluating physical-layer algorithms under realistic propagation, and rehearsing AUV missions or operations in waters you cannot easily access.

But a virtual ocean is not the ocean, and it pays to know where the fidelity ends:

The channel is only as good as its model. A Pekeris ray tracer captures multipath structure and transmission loss, but not the full richness of a real ocean. Replayed measured channels narrow this gap considerably, but only for the conditions under which they were recorded.
Motion is quasi-static. Node positions may change slowly, but motion during a transmission — and hence platform-induced Doppler — is not modelled.
The analog chain is not exercised. Power amplifiers, transducers, impedance matching, saturation and cavitation effects are precisely what has been virtualized away; problems there will only show up in water.
Realtime is a budget. Every transmission must be convolved through the channel to every receiver as it happens. Complex propagation models or large networks can exceed what the laptop can compute in realtime (the VAO warns when this happens); channels are cached for static geometries, which helps.

In short: use the simulator (Chapter 34) to develop protocols, the VAO to validate the real system under realistic and repeatable acoustics, and the sea trial to confirm what only the sea can tell you.

35.6 Beyond two modems

Nothing in this setup is specific to two nodes. Each addnode! call adds one node to the virtual ocean, on its own UASP2 port — so a 5-node network is just five addnode! lines in the scenario script, and five modems each configured with the laptop’s IP address and its own port. The VAO computes the channel between every pair of nodes, so all the multi-node behavior — overhearing, interference, hidden nodes, routing over multiple hops — emerges naturally. The practical limit is compute: the number of acoustic paths grows quadratically with the number of nodes, so large networks call for a beefier ocean host or a simpler propagation model.

Nodes need not be single-transducer modems either: passing relpos to addnode! (see documentation) gives a node multiple hydrophones at specified relative positions — useful for testing receiver arrays and direction-of-arrival estimation against a simulated wavefront.

UnetCube & UnetCloud

For HIL testing at scale, Subnero offers UnetCube — essentially a modem without the analog electronics, i.e., the same processor and firmware as a real modem, packaged for the lab bench and made to be paired with a virtual ocean. If you would rather not host any hardware, UnetCloud provides a cloud-hosted network of UnetStack modems with a VAO built in, letting you develop and test against a realistic multi-node network from a browser.