Unet

Turning a Multi-Receiver Modem into a USBL Transceiver

Wed, 22 Apr 2026 00:00:00 +0000

Picture this: You are running a mission with a mobile underwater node. You have a multi-receiver acoustic system on your surface vessel ensuring a robust, high-speed communication link. But as the autonomous underwater vehicle (AUV) navigates the mission, you also need to know exactly where it is. What if you didn’t need to deploy a completely separate tracking system for this? What if the exact same hardware you are using to talk to your AUV could also be used to track it?

Space, weight, and budget are always at a premium in subsea deployments. If you are using a multi-receiver communication system running UnetStack, it is highly likely that you have access to the raw acoustic data and the timing information from all your receiving channels. Because UnetStack natively supports these multi-receiver architectures, it is possible to use your existing communication hardware for the localization and tracking of targets too.

Take the Subnero multi-receiver modem as a practical example. We are frequently asked if this system can be used as a USBL transceiver. The short answer is yes. While the primary purpose of its multi-receiver architecture is to enhance communication performance through spatial diversity, the hardware requirements for localization are almost identical. Therefore, converting it into an Ultra-Short Baseline (USBL) transceiver is remarkably straightforward.

The resulting setup is basically a modern USBL system approached “from the other side.” Most traditional USBL systems available today provide some basic communication capability in addition to their primary tracking functions. Conversely, a UnetStack-powered multi-receiver modem allows you to add tracking capabilities on top of the communication link.

In this blog post, we will demonstrate how two minor modifications, some rigid scaffolding for the modem’s hydrophones and a script run on your laptop, are all that stand between you and a fully functional USBL system. Specifically, we will first walk you through the concrete steps required to configure a multi-receiver modem as a transceiver, and then we will peek under the hood to explain in detail how this system works. But before all that, let us begin with a quick refresher on USBL systems.

USBL transceiver ready to be lowered onto the seabed.

USBL transponder attached to a diver tank.

USBL Basics

The basic working principle of a USBL system is that a transceiver sends out an interrogation signal and waits for a response from a transponder unit attached to the tracking target. The overall delay between the interrogation and its response then informs the tracker about the range to the target, and the small differences in arrival times across an array of hydrophones on the transceiver allow it to estimate the bearing. Together, these two pieces of information pinpoint a unique target location in three-dimensional space.

+ =

Installing the Dependencies

Our goal in this post is to replicate such a USBL system using a pair of UnetStack modems and a few Julia scripts available from the unet-contrib GitHub repository. Therefore, as a first step please download the repository and then run the provided ./install script to install a Julia runtime plus a few Julia packages. Note that your modems must be running UnetStack v5 or later for the following scripts to work.

Setting Up the Multi-Receiver Modem

To convert arrival times into arrival direction, the USBL modem must know the precise arrangement of its receiving elements. Therefore, its transducer and the three hydrophones must be attached to some rigid structure (e.g. a frame, a boat or an AUV) and then their precise locations must be made available to the USBL software. When attaching the hydrophones, care should be taken not to obstruct the main bulb of the hydrophones, and the overall geometry should be close to tetrahedral with a side length as large as possible but at least 15 cm (6 inches) for a modem with a center frequency of 24kHz.

Subnero multi-receiver modem with a 3D-printed frame to secure the hydrophones.

The provided script performs localization in the body frame of reference given by the receiver geometry. Therefore, if your transceiver setup is mobile then you may have to attach an attitude heading reference system (AHRS) sensor to your transceiver to support conversion from the body reference frame to an East-North-Up coordinate system. Subnero modems can be equipped with an internal AHRS sensor as an optional upgrade.

If your focus is more on software development rather than hardware and real-world tracking, then the unet-contrib repository also contains a turnkey script to deploy your modems in a virtual acoustic ocean. Please see the appendix at the end of this post for details. Regardless of which path you choose, we will assume for the remainder of this post that you now have a setup equivalent to the following.

Launching the USBL Script

With the hardware now in place, the final step on our journey towards a USBL transceiver is to launch a helper script that does the USBL computation. To this end, please write the receiver geometry into a text file, starting with one line containing the whitespace-separated (x,y,z) coordinates of the transducer followed by three analogous lines for each hydrophone in the order of the labels on their cables.

# Example geometry file for a tetrahedron with a side length of 15cm
  0.0         0.0     0.0        # Transducer
  0.0866025   0.0    -0.122474   # Hydrophone 1
 -0.0433013   0.075  -0.122474   # Hydrophone 2
 -0.0433013  -0.075  -0.122474   # Hydrophone 3

Once the geometry file is ready, we can then launch the USBL script using the following command.

# Abstract command
./usbl <transceiver IP address> <geometry file>
# Concrete example
./usbl 192.168.42.123 geometry.txt

Finally, we can exercise the USBL functionality by running the following commands on the Unet shell.

subscribe topic(ranging)
subscribe topic('bearings')
subscribe topic('locations')
range <transponder Unet address>

Note that depending on your setup, you may have to increase the power level on both the transceiver and transponder modem for the ranging to be successful; the default power level of -42 is very weak and will not be detectable except at very short ranges. We recommend a power level of -10 as a safe default, and 0 if you need to communicate over long distances. You can change the power level using plvl <new power level>, and you can make the new setting persistent across reboots by adding this command to your startup.groovy file.

If you have managed to follow along until here, then congratulations: you have just successfully located the transponder modem using nothing but sound! As the above screenshot shows, your modem now reports three pieces of location information.

For each incoming signal, it shows a BearingNtf reporting in degrees the azimuth (horizontal direction, 0° is positive x-axis and 90° is positive y-axis) and elevation (vertical direction, 90° is positive z-axis).
For each execution of range, it shows a RangeNtf reporting the range in meters to node to.
Whenever we have both a Bearing and RangeNtf, the modem also shows a PeerLocationNtf.

You can selectively toggle each of these notifications using the corresponding subscribe and unsubscribe commands. Also, remember that bearing and peer location are reported in the body frame of reference given by the geometry file and that an AHRS sensor may be needed to convert these quantities to world coordinates.

USBL UI

To make it easier to interpret the USBL output, the unet-contrib repo provides a UI extension that visualizes the ranges, bearings and location estimates.

To activate this UI, please proceed as follows.

Upload ui/dist/USBL.html to the scripts/ folder of your modem.
Refresh the UI, then go to Dashboards > USBL.html

How Does This Work?

Now that we have a working USBL transceiver, let us take a closer look at how it actually works. As you may have noticed, there are two topics that require further explanation.

How do we trigger the transponder modem to send us a signal, and how do we use this signal to measure the range?
How do we estimate the bearing of the incoming signal.

The remainder of this post will answer these two questions.

Estimating the Range

UnetStack modems constantly monitor the input audio stream for special signals called preambles, and upon detecting a preamble they emit a DetectionNtf that lets other software components know about and react to this situation. This setup makes it very easy to measure the distance between two modems.

On the transponder side, we set up a script to listen for DetectionNtf and then reply with a matching response signal after some predefined delay $\Delta T > 0$.
On the transceiver side, we emit an interrogation signal at time $T_1$, then wait for a matching DetectionNtf and read from it the time of arrival $T_2$. The range between the transceiver and transponder is then given by
\[r = \tfrac{c}{2} \, (T_2 - T_1 - \Delta T)\]
where $c$ is the speed of sound in water.

This logic is built into UnetStack in the form of the range() command. Therefore, no additional code is required to realize the ranging part of our USBL system.

Estimating the Bearing

Slightly more work is required to get the bearing estimation up and running. At a high level, the algorithm for doing so consists of two steps.

Upon receiving a DetectionNtf, we determine the precise arrival times $t_i$ on each channel $i \in \{0,1,2,3\}$.
Given these arrival times and the known receiver positions $x_i \in \mathbb{R}^3$, we can then compute a corresponding direction of arrival $u \in \mathbb{R}^3$.

The second of these steps is quite straightforward. In fact, all it takes to convert arrival times $t_i$ into a bearing estimate $u$ is to evaluate

\[u = - \frac{\Delta x^{-T} \Delta t}{\| \Delta x^{-T} \Delta t \|_2}\]

where

\[\Delta x = \big[\, \Delta x_1 \,\,\, \Delta x_2 \,\,\, \Delta x_3 \, \big] \qquad\text{with}\qquad \Delta x_i = x_i - x_0\]

is a square matrix with the spatial offsets $\Delta x_i$ between the hydrophones and the transducer as its columns, and similarly

\[\Delta t = \big[\, \Delta t_1 \,\,\, \Delta t_2 \,\,\, \Delta t_3 \bigr]^T \qquad\text{with}\qquad \Delta t_i = t_i - t_0\]

is a vector consisting of the differences in arrival times $\Delta t_i$.

The above formula is derived from the observation that the time it takes for the wavefront to move from a hydrophone to the transducer is given by

$$ \Delta t_i = - \frac{\Delta x_i^T \, u}{c} . $$

The suggested formula is then obtained by collecting these individual equations into a combined system, solving for $u$ and finally normalising the result to eliminate the dependence on the sound speed $c$.

Estimating the Arrival Times

The last remaining piece in our USBL puzzle is to devise an algorithm for estimating the precise arrival times from the recorded audio signals. Mathematically, this amounts to finding offsets $o_i$ such that the signal $r_i$ recorded on channel $i \in \{0,1,2,3\}$ shifted by the offset $o_i$ matches the expected preamble $p$, i.e.

\[r_i[o_i + k] \approx p[k] \qquad \text{for all} \qquad k \in \{0, \ldots, N-1\} ,\]

where $N$ denotes the length of the preamble. A standard way to tackle this problem is to determine the offsets $o_i$ by maximising the absolute value of the cross-correlation,

\[o_i = \argmax \, \bigl| c[o] \bigr| \qquad \text{where} \qquad c[o] = \sum_{k=0}^{N-1} r_i[o + k] \, \overline{p[k]} .\]

(We assume here that $r_i$ and $p$ represent complex-valued baseband samples and hence apply complex conjugation $x \mapsto \overline{x}$ to one of the factors when evaluating the cross-correlation.)

Our USBL code is based on this correlation maximization idea but applies two further refinements.

Rather than looking for the strongest arrival, our algorithm looks for the earliest arrival by locating the earliest peak that reaches at least half of the maximum correlation. This modification makes the algorithm more robust against echoes from nearby reflectors.
We subsample the correlation signal by a factor eight to increase the precision of the estimated arrival times.

That’s it! With these modifications, we now have a complete set of algorithms for tracking a target underwater. If you’d like to know more about how to implement these algorithms, then we encourage you to take a look at the usbl-julia folder in unet-contrib. As you will see, UnetStack’s open architecture makes it very easy to extend a modem’s functionality using just a few lines of code!

Appendix: Setting Up a VirtualAcousticOcean Test Environment

Setting up a USBL mount and deploying it in a body of water large enough to support USBL testing can be logistically challenging. To facilitate testing in a lab, the unet-contrib repository contains a script that allows you to deploy your modems in a VirtualAcousticOcean simulation environment. This script reconfigures the very lowest layers of the modems’ networking stacks such that rather than transmitting and receiving signals via the attached physical hardware, they instead communicate via a simulator that imitates the distortions that would have been observed if the modems had been deployed in a real ocean. All that is needed to activate this environment is to run the following command.

# Abstract command
./vao <transceiver IP address> <transponder IP address>
# Concrete example
./vao 192.168.42.123 192.168.42.45

Among other things, this command will reboot your modems. Once they are back online, you can test that everything is set up correctly by running the following commands on the Unet shell of one modem and verifying that the other modem receives the message.

plvl 0
tell <peer Unet address>, 'hello world'

Please note that after activating a VirtualAcousticOcean configuration, the modems will remain in this configuration until it is actively removed. You can return the modems to transmitting and receiving via their onboard hardware by deleting the modem.toml files in their respective scripts/ folders.

Please also see our earlier blog post for more information on using UnetStack modems with VirtualAcousticOcean.

Acoustic Communication and Navigation for Subsea Robotics — Part 2

Wed, 17 Dec 2025 00:00:00 +0000

In part 1, we discussed the first three levels, technology choices, integration hygiene, and deployment planning. Those alone get you most of the way to confident connectivity. In this post, we’ll describe the last two levels, where systems adapt in real time and missions flex slightly to help communication.

Level 4: Adaptive communication links

Once a vehicle is in the water, the ocean reveals its true character. Conditions change with depth, movement, and even the passing of ships. Instead of locking parameters before deployment, we can let the modem adapt in real time. Adaptive modulation schemes allow the system to step down to more robust modes when multipath or Doppler is high, and step up again when the channel clears to deliver higher throughput. Similarly, error control coding can be tuned dynamically: adding more redundancy when losses rise, and trimming it back to recover data rate when the link is clean. Erasure codes are particularly useful underwater; they let us transmit a little extra upfront, so the receiver can reconstruct the message even if several frames are lost, without the delay of waiting for acknowledgements. Together, these adaptive techniques turn a static link into one that bends with the ocean instead of breaking against it.

Adaptivity is not only about modulation; it’s also about choosing the right link at the right time. Most vehicles today carry more than one communication interface, Wi-Fi or 4G when surfaced, satellite on a mothership or shore station, optics for short range underwater, and acoustics for longer ranges. A smart stack can switch among these automatically, routing different types of data to the most suitable link. For instance, video streams can go over Wi-Fi when the vehicle is near the surface, low-rate telemetry can flow over acoustics while submerged, and large files can transfer over optical when in close range. By declaring the content type, time-to-live, and priority of each data stream, operators can leave the decision-making to the stack instead of micromanaging links. UnetStack, for example, allows this kind of policy-based routing, so vehicles can focus on their mission while the communication system quietly optimizes delivery.

All of these adaptive behaviours—whether changing modulation and coding in real time, dynamically routing across multiple links, or delivering content based on link availability—are already supported in UnetStack. In this article, we’ve focused on the why and what of adaptive communication, but in future blogs, we’ll dive into the how: demonstrating how these ideas are implemented in UnetStack.

Level 5: Adaptive command and control

The highest level of confidence comes when vehicles themselves adapt their missions based on feedback from the communication system. Instead of treating comms as an independent subsystem, we can use information about link quality to make small but meaningful changes in behaviour. For example, if the modem detects that the channel is degrading, the vehicle might pause bulk transfers, climb or dive a few metres to escape a dead zone, or slightly adjust its course to maintain better connectivity. These interactions are illustrated in Figure 1, which shows how different onboard agents—command and control (C2), network, and sensing—communicate with each other to adjust plans dynamically. By keeping this feedback loop lightweight and local, vehicles can preserve their mission goals while still giving the communication system a chance to perform optimally. This idea of adaptive mission execution moves connectivity from being a fragile dependency to becoming an active part of mission planning.

Figure 1: Schematic of adaptive mission execution. The C2 agent manages node placement and motion planning, the sensor agent handles data acquisition and processing, and the network agent oversees inter-node communication. Feedback from the network agent informs the C2 agent about link quality, prompting small plan adjustments that keep missions robust without human intervention. From M. Chitre, “A holistic approach to underwater sensor network design,” in Proceedings of Naval Technology Seminar (NTS) 2011, May 2011. (Invited).

Recent work (M. Chitre and K. Li, “Physics-informed Data-driven Communication Performance Prediction for Underwater Vehicles,” in The 6th Underwater Communications Networking (UComms 2022), (Lerici, Italy), 2022.) has shown that we can go even further by predicting what lies ahead using lightweight, physics-informed, data-driven models. The idea is simple but powerful: as an autonomous vehicle moves, it measures acoustic signal strength along its path and uses those observations to predict what the field will look like in the region just ahead. Rather than relying purely on machine learning, which struggles to extrapolate beyond the data it has seen, this method embeds the underlying physics of acoustic propagation directly into the learning process. Each measurement is treated as a combination of rays arriving from different directions, and a sparse optimization algorithm estimates which ray angles and amplitudes are most likely to explain the observed field. By constraining the learning to the acoustic wave equation, the algorithm can make physically realistic predictions even with very little data.

In the study, a simulated AUV travelled along a 100 m segment at a depth of 100 m, taking signal-strength readings every metre while communicating with a surface ship 2 km away (Figure 2). Using only those 100 measurements as input, the model then predicted the acoustic field across a 250 m × 50 m region in front of the vehicle. The ground-truth field computed with the BELLHOP propagation model is shown in Figure 3, while Figure 4 shows the model’s predictions using the physics-informed approach. The resemblance between the two fields is striking: even fine-scale interference patterns and “dark zones” of low signal strength are reproduced well enough to guide adaptive path-planning. Because the model learns from multiple frequencies simultaneously and enforces sparsity across ray arrivals, it generalizes far better than traditional data-driven methods. In practice, this means a vehicle can predict where the link will hold and where it will fade, and adjust its trajectory before the connection is lost—all in real time and with modest onboard computing resources.

Figure 2: Simulation setup

Figure 3: Ground truth signal strength integrated over the 9–14 kHz band, as obtained from BELLHOP over the region of interest. The AUV path is shown in blue, with solid dots showing the measurement locations. The white rectangle shows a region marked for closer inspection.

Figure 4: Predicted signal strength integrated over the 9– 14 kHz band, over the region of interest. The AUV path is shown in blue, with solid dots showing the measurement locations. The white rectangle shows a region marked for closer inspection

This work demonstrates how data and physics can come together to make underwater communication systems proactive rather than reactive. Instead of waiting for a link to fail and then compensating, vehicles can now anticipate when and where communication will degrade, and adjust before it happens. These predictions close the loop between perception and control—turning what was once a static channel model into a living part of the mission logic. Combined with the adaptive mission behaviours discussed earlier, such models make it possible for underwater vehicles to plan smarter routes, schedule transfers more intelligently, and ultimately operate with a level of confidence that was previously out of reach.

Putting it all together

When you add adaptation to the first three levels, the operating picture changes. Operators declare intent and monitor goodput, not tweak knobs. Vehicles help themselves with minor depth or timing shifts. Multi-link stacks exploit whatever the environment offers. Most importantly, the link stops being an unreliable afterthought, and starts being trusted.

The message is simple, physics still sets the limits, but if we respect it, plan for it, and adapt intelligently, those limits work for us. Once we have that confidence, we can design missions and systems that rely on the link instead of avoiding it.

Acoustic Communication and Navigation for Subsea Robotics — Part 1

Wed, 17 Dec 2025 00:00:00 +0000

This two-part article is based on the talk “Connectivity with Confidence: Acoustic Communication and Navigation in Practice,” delivered by Professor Mandar Chitre (National University of Singapore). The blog was written to distill the key ideas from that presentation into a written form for a wider audience.

When we ask a room of subsea robotics developers and users how many have used underwater acoustic communications, we often see a good number of hands. But when we follow up and ask how many feel confident that, when they put a vehicle in the water, the acoustic link will “just work,” the show of hands drops dramatically. That gap is what we want to address in this two-part series. It’s time to move from treating communication as a nice-to-have, something added reluctantly and not relied upon, to building connectivity with confidence.

For a long time, skepticism about acoustic links was justified. They were fragile, unreliable, and unpredictable. But technology has evolved. With the right choices and a bit of discipline, it is now possible to achieve robust, dependable connectivity that not only supports communication but also navigation. In fact, when we use the word connectivity, we mean both. Acoustics underpins them together. Aerial drones exploded in use partly because of easy communication and GPS navigation. Underwater vehicles, by contrast, have been held back because we lacked the same level of confidence in connectivity. We believe that can change.

The Basics

Why Acoustics?

Radio and most light simply don’t travel well underwater. Even visible light in clear water only gets you tens of meters; in turbid coastal waters like Singapore, it is even less. Acoustics, on the other hand, propagate hundreds of meters, to tens of kilometers. Frames typically contain a preamble, data modulated onto a carrier, error correction, and checksums. Robust incoherent modulation schemes work well for commands and telemetry, while coherent modulation schemes are needed for images and high-rate data. Forward Error Correction (FEC) and erasure codes add robustness without long feedback cycles. This is critical because sound travels so much slower than light.

Acoustic communication

When we talk about frames and packets underwater, it is useful to be precise. A packet is a unit of data, but modems often fragment it into smaller frames for transmission. Each frame has its own preamble, data, and error check. On the receiving side, fragments are reassembled into the original packet. Because underwater channels lose frames more often, we need mechanisms to deal with the loss. Automatic Repeat Request (ARQ) is one approach: the receiver asks for specific lost fragments to be re-sent. But given the long propagation delays, this can waste valuable time. Erasure correction coding provides another option: by adding some extra parity frames at the start, the receiver can reconstruct the whole packet as long as it collects enough of the transmitted frames, even if a few are missing. This avoids the need to wait for a round-trip of acknowledgements, which can often take long underwater.

Next, there are also some terms that we need to define clearly. Robustness refers to the chance that a packet crosses cleanly the first time, without errors. Reliability, on the other hand, is the end-to-end guarantee that comes from feedback and retransmission if needed. Both are useful, but they come with different costs. Similarly, we care not about raw link rate, which is the number printed in the datasheet, but about throughput or “goodput”: the actual amount of useful data delivered correctly. A link claiming tens of kilobits per second may in practice give you only a fraction of that once protocol overheads and frame loss are accounted for. Understanding these distinctions avoids confusion when comparing modems or planning missions.

Navigation is built on the same acoustic signals. The simplest method is two-way travel time ranging: one device transmits, the other responds, and the round-trip time divided by two gives you a range. With synchronized clocks, we can also do one-way travel time ranging, which halves the time taken for ranging, and reduces energy usage (but requires very stable oscillators). Using several surface nodes with GPS, we can build long-baseline (LBL) systems, where either the topside knows the vehicle’s location or the vehicle computes it itself in “inverse LBL.” With a single beacon, compact Ultra-Short Baseline (USBL) systems estimate bearing and range together, and again, they can be configured in normal or inverse modes depending on where you want the computation to happen. These methods are mature and well-proven in underwater systems, but they still face practical challenges in real deployments—from multipath and synchronization drift to environmental variability—so it’s important to account for these factors early in your system design.

Why doesn’t it “just work”?

Many people are surprised when an underwater modem doesn’t “just work.” The reason is that the ocean is an entirely different medium from the air or fiber networks we are used to. Bandwidth is scarce, signals bounce off the surface and seabed creating echoes, vehicle motion causes Doppler, and noise from ships or even snapping shrimp can overwhelm weak signals. On top of this, sound travels 200,000 times slower than light, so protocols designed for the Internet break down. Unless these realities are accounted for, what looks good on paper quickly fails at sea.

One of the most useful ways we have found to explain the pitfalls is through a simple list of don’ts and do’s. The don’ts are the traps that catch many first-time users—but each of them has a simple alternative. Don’t assume you can simply replace a tether with modems and expect the same reliability; acoustic networks require new ways of thinking about timing and robustness. Don’t use internet protocols blindly, because the assumptions of fast feedback and low loss don’t hold underwater; purpose-built protocols handle this far better. Don’t ignore the physics of bandwidth, absorption, and Doppler; knowing these limits helps you plan within what the ocean can actually support. Don’t overload the channel by pushing it to its theoretical maximum; leave headroom for retries and environmental fluctuations. Don’t reinvent decades of work already built into frameworks like UnetStack; start with proven foundations and tune from there. And finally, don’t try to optimize everything before you have a stable link—get it working robustly first, then improve it. We’ll come back to how each of these “do’s” map into the five levels of confidence that follow.

These are practical steps starting from the technology choices you make, through integration and planning, and extending into advanced adaptive techniques that, if followed, can transform underwater communication from a gamble into something you can rely on.

The five levels of confidence

These five levels capture the progression from basic design decisions to advanced adaptive techniques that push performance further. The first three are essential; the last two are advanced. In this first part, we’ll cover the first three.

Level 1: Technology choices

Before you even build or buy, the technology choices you make set the upper bound for what your system can achieve. The first and most important is the frequency band. Higher frequencies in the hundreds of kiloHertz give you short-range but high-rate links, suitable for a few hundred meters and applications like image or file transfer. Mid-range frequencies in the tens of kiloHertz are the workhorse for kilometre-scale missions. At the other end, only a few kiloHertz will carry over tens of kilometres, but at the cost of data rate. Every choice is a trade-off between absorption, ambient noise, and usable bandwidth, so you need to pick the sweet spot that matches your mission profile. As shown in Figure 1, sound attenuation in warm shallow waters increases steeply with frequency. This relationship is what drives the trade-off between range and data rate when selecting an operating band.

Figure 1: Sound attenuation in warm shallow waters

Transmit source levels are another key decision. These are not just about the hardware spec sheet. They are limited by environmental regulations on noise, by cavitation thresholds when operating shallow or with small vehicles, and by whether your power system can actually supply the transient peaks that the transducer draws. Directivity is equally important. Omnidirectional transducers are simple to deploy, but if you know the geometry of your mission, directional transducers can make the most of your energy. On the receiver side, adding spatial diversity is often an overlooked but powerful option. Just as Wi-Fi access points benefit from multiple antennas, a small array of hydrophones can significantly improve robustness, and it is usually inexpensive to add on a surface platform or larger vehicle. Finally, consider modulation and coding. It is tempting to chase the highest bit rates, but robustness almost always matters more. Choose the lowest rate that still meets your data needs, and use forward error correction or erasure coding to carry you through challenging conditions. Navigation is also part of the early design stage. Decide whether you will rely on simple two-way ranging, or if your system can support synchronized clocks for one-way measurements. Think about whether your setup favours long baseline (LBL), inverted LBL, Ultra-Short Baseline (USBL), or inverted USBL. These are not afterthoughts, they fundamentally shape what your system can deliver once it is in the water.

Figure 2: The typical sound levels of ocean background noises at different frequencies, as measured by Wenz (1962). This graph is therefore also referred to as the Wenz curves. The sound levels are given in underwater dB summed over 1 Hz wide frequency bands, which is often written as dB re 1 µPa2/Hz. Adapted (after National Research Council, 2003) from Wenz, G. M. (1962). Acoustic ambient noise in the ocean: Spectra and sources. The Journal of the Acoustical Society of America, 34(12), 1936–1956.

Beyond frequency, power, and modulation, there are also important choices in how multiple users share the channel and how higher-level data is handled. Medium access control (MAC) is a prime example: if you can synchronize your devices, a time-division scheme (TDMA) often provides the most predictable performance; if traffic is bursty or unpredictable, random-access approaches like CSMA or MACA may be better, though they come with higher overhead. At higher layers, think about how your system expresses priorities and deadlines. Some data is time-sensitive (like vehicle position), while other data may be large but delay-tolerant. A modem or stack that allows you to configure quality of service, set time-to-live values, and even declare content types (e.g. image, telemetry, audio) can make smarter transmission decisions on your behalf. The overall configurability of the technology is therefore not just a “nice-to-have”, it is a core part of making sure the link adapts to your mission requirements instead of forcing your mission to adapt to the link.

And if navigation is part of your mission, you also need to decide upfront whether the system should support ranging and localization, whether it can provide synchronized time across nodes, and how stable the clocks are in practice. These capabilities determine not just how you communicate, but how you localize vehicles underwater, so they must be considered at the same stage as frequency bands and modulation schemes.

Level 2: Integration hygiene

When it comes to mechanical integration, factors such as the placement of the transducer plays an important role. Simply mounting it wherever there is space on a vehicle rarely works well. Thrusters generate noise and, more critically, microbubbles that persist in the water and scatter sound, destroying coherent links even when SNR looks good. Flow noise from fast-moving vehicles, vibrations from mechanical structures, and even the rigidity of the mounting bracket all contribute to degraded performance. We have seen vehicles that lost their link whenever they moved away from the ship, only to recover it as soon as they turned slightly, simply because their thruster wake sat directly in the acoustic path. The wake was filled with microbubbles that scattered and distorted the sound waves, severely degrading the signal even though the signal-to-noise ratio appeared good. Paying attention to transducer location and characterizing flow and thruster noise early in the integration process prevents many of these headaches. Ambient noise in the operating environment can also vary dramatically, shipping lanes, construction sites, and even biological sources like snapping shrimp can raise the noise floor and reduce performance. On top of this, interference from other acoustic systems, whether they are echo sounders, sonars, or other modems, can overlap with your own signals if frequencies are not coordinated. Factoring these acoustic neighbours into integration and deployment decisions is critical.

Electrical integration is just as critical. Modems draw sharp bursts of current during transmission, and if the power bus is noisy or poorly filtered, that noise couples back into the receiver front end. Clean power supplies and proper filtering are essential to ensure consistent source levels and avoid self-interference. Once integrated, it is important to measure actual source levels in situ, because cabling, mounts, or limited current draw from a vehicle’s battery system may reduce output below specification. Shallow-water operation at high source levels can also cause cavitation, producing bubbles that not only damage transducers but also severely degrade signals. Regularly checking for cavitation thresholds and logging ambient noise levels in your deployment area helps ensure that electrical and acoustic integration issues do not compromise the system. Beyond hardware, it is equally important to evaluate communication performance after integration: measure diagnostics such as packet delivery ratios, latency, and ranging accuracy in realistic conditions. These checks often reveal integration flaws that would otherwise remain hidden until deployment. Synchronization and ranging performance must also be verified, since even small timing errors can undermine both communication and navigation functions if not properly accounted for.

Software integration is the third pillar of hygiene. Too often, teams treat the modem as a transparent pipe and push raw bytes across. This wastes much of what modern stacks can offer. In UnetStack, for example, applications can attach metadata such as robustness level, reliability, time-to-live, priority, and MIME type to each message, allowing the modem to make smarter delivery decisions. A short snippet shows how this works:

Example AUV code snippet:

sock = UnetSocket('192.168.0.42', 1100)
sock.connect(sock.host('TOPSIDE'), 32)
sock.ttl = sock.TTL_MAILBOX
sock.mailbox = 'STATUS'
sock.mimeType = 'application/json+auvstatus'    // facilitate application-specific compression
while (true) {
  status = c2.getStatus()
  sock.send(status.toJson().bytes)
  sleep(1000)
}

Example TOPSIDE code snippet:

sock = UnetSocket('192.168.0.27', 1100)
sock.bind(32)
while (true) {
  rx = sock.receive()
  ui.showStatus(json.parse(rx.data))
}

By tagging data this way, we give the modem the context it needs to adapt to current conditions, compressing an image if bandwidth is poor, discarding stale telemetry instead of wasting airtime, or prioritizing urgent commands. This transforms software integration from a simple “pipe” to a smarter, adaptive communication framework that supports confident operation in real-world deployments.

Level 3: Deployment planning

Deployment planning is where theory meets the ocean, and it makes a huge difference to communication performance. Many users ask a simple question: what range will I get with this modem? Unfortunately, the answer is never a single number. Communication performance depends on much more than just distance. It is shaped by depth, bottom type, water column properties, and geometry. Acoustic energy refracts, reflects, and cancels in ways that create “hot spots” and “dark zones.” A link that looks strong at 500 meters might vanish entirely at 800 meters, only to return at 1,200 meters. Planning missions without considering this variability often leads to surprises in the field.

One of the most effective ways to plan is through propagation modeling. Physics-based models, if you have good knowledge of the environment (sound speed profile, seabed composition, depth, and bathymetry), can predict where signals will carry well and where they will fail. Even with limited data, these tools can produce maps of expected signal-to-noise ratio that guide decisions such as when to run telemetry updates or attempt bulk transfers. If modeling or measurements are not possible, rules of thumb can still be applied to avoid known traps, like the Lloyd mirror effect.

The Lloyd mirror is a particularly important phenomenon to account for. Near the surface, acoustic signals arrive via both a direct path and a surface-reflected path. The reflection undergoes a 180° phase shift, so when the two signals overlap, they can cancel each other out and create a dark band of poor reception. This effect shows up consistently in field tests and models alike. The solution is simple: increase the combined depth of the transmitter and receiver. That could mean mounting the transducer deeper on a vehicle, or placing the surface modem further below the waterline. Small changes in depth can move the system out of destructive interference zones and into regions of strong signal, dramatically improving reliability. Planning missions with this in mind, whether through detailed modeling, in-situ measurements, or rules of thumb, turns deployment from guesswork into an informed exercise.

Do these three levels well, and you are already far ahead. You will have a link you trust for commands and telemetry, predictable windows for heavier data, and navigation updates at the cadence you need. In part 2, we’ll explore levels four and five, adaptive links and adaptive missions, where the system and the vehicle adjust in real time.

Running Hardware-in-the-Loop Simulations Using UnetStack Modems

Wed, 11 Jun 2025 00:00:00 +0000

Underwater wireless communication is difficult to design, test, and deploy. The ocean is an unforgiving test environment, with dynamic and often unpredictable propagation characteristics. Access to vessels, dive teams, and favorable weather windows often restrict testing frequency, making rapid iteration nearly impossible.

For researchers, engineers, and system integrators working on underwater networks, simulation is an essential first step. It enables protocol design and debugging, visualizes network behavior, and allows performance evaluation under varying conditions. Most importantly, simulation helps reduce risk before committing to expensive deployments.

Why Hardware-in-the-Loop (HIL)?

While pure software simulation (where all nodes run on a single computer) is useful, it falls short in certain cases, particularly when real-time behavior, hardware driver integration, and system compatibility are important.

Imagine you are a researcher developing a large scale underwater network. You want to validate not only your algorithms but also the performance of the modems you plan to use in the field. Before investing time and money into an offshore campaign, you want confidence that your system behaves correctly, both in logic and in timing. You also want to try out multiple configurations quickly.

This is where HIL simulations shine. By keeping your real hardware in the loop, you:

Test the actual modem hardware, drivers, and firmware.
Verify timing behavior and interface compatibility of your algorithms in the modems.
Run real world network software with simulated acoustic links.

If your modem is software-defined and open-architecture, such as Subnero’s modems, HIL offers a development experience that closely mirrors actual deployment.

The Foundation: UnetStack v5 + Virtual Acoustic Ocean

Modems running UnetStack v5 — such as those offered by Subnero — are fully software-defined and follow an open architecture. This enables users to customize physical and network layers, extend built-in components, and use the exact same software stack in both simulated and real-world deployments.

Virtual Acoustic Ocean (VAO) is an open-source acoustic channel simulator. It supports standard propagation models, and allows users to define node positions, protocol stack parameters, and environmental conditions. Simulations can be run in interactive mode, making VAO suitable for everything from basic tests to complex protocol validation.

With a modem running UnetStack v5 and VAO, users are now able to unlock scalable, reproducible HIL simulations that can closely mirror real-world underwater communication scenarios while enabling rapid, repeatable testing without going to sea.

Typical Use Cases

This simulation setup supports a variety of scenarios. Researchers can use it to develop and validate new communication algorithms such as those at the physical or network layers, under realistic acoustic conditions. Commercial teams can evaluate performance for AUV-based data harvesting or remote sensing missions before heading to the field. Defense teams can rehearse complex mission scenarios virtually, especially in environments where access or testing is restricted.

Step-by-Step Guide to HIL Simulation

Before beginning the simulation, ensure you have the following setup:

Two Subnero M25M series modems running UnetStack v5.
A laptop or mini-PC with Julia installed, capable of running the Virtual Acoustic Ocean (VAO) simulator.
An Ethernet switch to connect all devices to the same network.

All components — modems and the VAO-running machine — should be on the same subnet to be able to reach each other using their IP address.

TIP: Use an isolated network switch (without internet access) to avoid interference from unrelated network traffic during simulation.

Note: This example uses Subnero M25M (MF-band) modems, but the same steps apply to Subnero’s LF and HF modems. The simulation script provided is just one example — please refer to the VAO GitHub repository for the latest examples, which may differ. This guide shows how to connect two Subnero modems, but more nodes can be added by extending the script with additional addnode! lines.

1. Install VAO and Packages

At a Julia terminal:

using Pkg
Pkg.add(name = "VirtualAcousticOcean", version = "0.8.1")
Pkg.add("UnderwaterAcoustics")
Pkg.add("Sockets")

2. Add Example Scenario

Copy the 2-node-network.jl file from the GitHub repo examples folder to your working directory.

Example content:

using VirtualAcousticOcean
using UnderwaterAcoustics
using Sockets

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

println("Simulation running with these nodes:")
for (idx, node) in enumerate(sim.nodes)
    println("  - Node $(idx) at position $(node.pos) receiving on UDP port $(node.conn.port)")
end

wait()

Note: The example shown here is representative. The version available in the VAO GitHub repository may differ slightly depending on updates or version changes. Run it from the terminal:

> julia --threads auto 2-node-network.jl
Simulation running with these nodes:
  - Node 1 at position (0.0, 0.0, -10.0) receiving on UDP port 9809
  - Node 2 at position (1000.0, 0.0, -10.0) receiving on UDP port 9819

3. Configure Subnero Modems

Each modem needs to be configured to redirect its baseband interface to VAO. Access each modem’s web UI and upload this modem.toml to the Scripts folder:

[input]
analoginterface = "UASP2DAQ"
ip = "192.168.42.10"
port = 9809

[output]
analoginterface = "UASP2DAQ"

Ensure this matches the VAO machine’s IP and each modem uses the correct port (e.g. 9809). Additionally, the [output] section is optional and typically used when configuring a physical modem.

Verify the setup via modem shell:

bb

Expected output:

> bb
« Baseband »

Baseband service for UASP2DAQ.AnalogInterface
...

Also check modem logs for an entry similar to:

1750584190212	INFO	UASP2DAQ@27:UASP2DAQ@1:57	Connecting to UASP2 DAQ at 192.168.42.10:9809...

That’s it. Now you have 2 nodes deployed 1 km apart and connected through VAO. With the nodes now connected via VAO and properly configured, you can begin interactive testing and messaging between the modems.

4. Set Transmit Power

Since the modems are deployed 1 km apart, set full transmit power:

plvl 0

5. Test the Link

Send a test message from either of the modem’s shell:

tell 0, "Hello Sea"

You should see the message on the receiving modem’s shell, confirming that the simulated link is working.

UnetCube (UnetStack OEM Edition) + VAO

If you do not have Subnero modems, you can still simulate the system using UnetCube (UnetStack OEM Edition) on single-board computers (e.g., Jetson Orin Nano). The simulation behavior will be the same, enabling rapid prototyping.

Contact info@subnero.com for more information.

Additional Resources

Running Unet audio on Apple silicon

Wed, 14 Feb 2024 00:00:00 +0000

Unet audio is a great educational tool for using and testing Unet implementations using UnetStack. Unet audio uses your computer’s sound card as an acoustic modem. Almost the entire functionality of UnetStack is available in Unet audio, so you can easily develop and test Unet Agents, try out communications algorithms, and even test your scripts and programs written to interact with UnetStack without needing any extra hardware.

Unet audio binds to your computer’s operating system and uses the built-in audio services to send and receive audio from the sound card. This means that some of the libraries used by Unet audio need to be compiled for the specific operating system and architecture.

Until UnetStack 3 Community release v3.4.3, Unet audio was only supported on Linux and macOS on the Intel x86 architecture. However, with the release of Apple Silicon, and the popularity of Mac computers with the M1/2/3 chips, we have been working to make Unet audio available on the ARM architecture.

We are happy to announce that Unet audio is now available on macOS running on Apple Silicon, from Unet Community v3.4.4 onwards.

Setup Unet audio on Macs with Apple Silicon

Unet audio comes as a part of UnetStack 3 Community releases. You can download the latest release from the UnetStack 3 downloads section.

Pre-requisites

UnetStack 3 requires Java 8 to be installed on your computer. With the macOS on Apple Silicon, you can run Java 8 compiled for x86 architecture using Rosetta 2 or run Java 8 compiled for ARM (aarch64) architecture natively.

Unet audio additionally requires portaudio to be installed on your computer. Homebrew is a great package manager for macOS, and you can use it to install portaudio.

The architecture of Java 8 that you have installed on your computer will determine which version of portaudio you need to use. The following table shows the compatibility between the architecture of the Mac, Java 8, and portaudio:

Computer CPU	Java 8 Architecture	Portaudio Architecture
Intel x86	x86	x86
Apple Silicon (aarch64)	aarch64	aarch64
Apple Silicon (Rosetta)	x86	x86

Java

We recommend using the aarch64 version of Java 8 and other dependencies on your Apple Silicon Mac. Azul Systems provides a great build of Java 8 for ARM, and you can download it from here. If you use the sdkman tool, you can install the ARM version of Java 8 using the following command:

sdk install java 8.0.322-zulu

To check which version of Java 8 you are using, you can run the following command:

> java -version
openjdk version "1.8.0_`XXX`"
OpenJDK Runtime Environment (Zulu 8.`A`.`B`.`C`-CA-macos-aarch64)

Homebrew and Portaudio

The version of portaudio installed by Homebrew will depend on the version of Homebrew that was installed on your computer. By default, Homebrew installs the native (ARM) version, but it is possible to have an x86 version of Homebrew installed (with Rosetta 2). Check which version of Homebrew you are using by running the following command:

> which brew
/opt/homebrew/bin/brew

An x86 version of Homebrew will return /usr/local/bin/brew instead. If you are running an x86 version of Homebrew, we recommend that you switch to the native version of Homebrew.

Once you are using the native version of Homebrew, you can install portaudio using the following command:

> brew install portaudio

You can ensure that the correct version of portaudio is installed by running the following command:

> file /opt/homebrew/lib/libportaudio.dylib
/opt/homebrew/lib/libportaudio.dylib: Mach-O 64-bit dynamically linked shared library arm64

Note the arm64 in the output.

Running Unet audio

Once you have installed the correct version of Java 8 and portaudio, you can run Unet audio by unzipping the UnetStack 3 Community release and running the following command in the unet-v3.4.4 directory:

bin/unet audio

Accepting Security Permissions on macOS for running Unet audio

When you run Unet audio for the first time, macOS will flag the dynamic libraries that Unet audio uses as being from an unidentified developer.

You will need to permit running these libraries. You can do this by going to System Preferences -> Security & Privacy -> General and clicking on Allow Anyway next to the message that says that the libraries were blocked from running.

When you run Unet audio again, you will be prompted to permit running the libraries. Click on Open to permit running the libraries.

You might have to run the bin/unet audio command again after permitting the libraries to run. You should only have to do this once, and Unet audio will run without any issues after that.

Photo by Ales Nesetril on Unsplash

A Step-by-Step Guide to Deploying and Operating an Acoustic Modem running UnetStack to Achieve the Best Performance

Mon, 03 Apr 2023 00:00:00 +0000

Deploying and configuring an acoustic modem during a field deployment to achieve the best performance can be a challenging task, especially for those who are new to the process. However, with the right tools and techniques provided with UnetStack, it can be accomplished smoothly and efficiently. In this blog, we will provide you with a step-by-step guide on how to deploy and verify a pair of acoustic modems running UnetStack in the field to ensure that it is working correctly and reliably during field deployment. Whether you are setting up a new pair of acoustic modems or troubleshooting an existing one, this guide will provide you with the essential steps to ensure that your wireless system is up and running correctly.

Let’s say you are deploying two acoustic modems (modem A and B) in water to establish a communication link between them. For this article, we use the example of a Subnero S60H series acoustic modem. After installing and powering up both modems, you can access the modems’ web interface (over the Ethernet interface) by connecting to their respective IP addresses using a web browser. Once you have logged into the modem’s web interface, the landing dashboard shows the current settings along with a web shell.

Landing dashboard of a Subnero S60H series modem

Depending on the distance between the devices, the first thing you may want to adjust is the power level setting of the two modems to avoid saturating the receiving modem. There is a slider in the landing page that you can use for this (default value set to -42) or you can use the plvl command in the web shell.

NOTE: We recommend using the following power levels (plvl) as the starting values for different distances - 42 to -20 for distances under 10 meters or in air, -20 to -10 for distances between 10 and 100 meters, and -10 and above for distances over 100 meters.

The `ping` & `tell` commands

Once the power levels are set, the next thing is to test the basic connectivity between the modems, before tuning them to achieve the best performance. First, note the node address of both the modems which we will be using to address each of them. In this example, modem A has a node address of 100, and modem B’s address is 120.

Now, we can test the connectivity between both modems using the ping command. You can type the following in the web shell of modem A:

> ping 120
PING 120
Response from 120: seq=0 rthops=2 time=13974 ms
Response from 120: seq=1 rthops=2 time=12246 ms
Response from 120: seq=2 rthops=2 time=12478 ms
3 packets transmitted, 3 packets received, 0% packet loss

This shows that modem A was able to ping modem B and get the response back. It has transmitted 3 ping packets and got a response for all of them.

The ping command uses the CONTROL channel, which is the robust communication channel provided by UnetStack, typically used to exchange control information between the modems.

The CONTROL channel is meant for low-rate robust data transmission, whereas the DATA channel is typically configured for higher-rate data transmission. You can read more about these in the unet handbook.

However, most of the actual payload transmissions are done using the DATA channel. So, our next step is to verify that the DATA channel works fine between the modems. This can be achieved using the tell command. Type the following command in the web shell of modem A.

> tell 120, 'hi!'
AGREE

On successful reception on modem B, you will see the following:

[100]: hi!

You can repeat the same from modem B to modem A or use the “Messages” section in the lower right corner of the Overview dashboard. The tell command uses a combination of CONTROL and DATA channels to transfer the payload.

You can find more about the tell command in section 2.6. Using acoustic modems in the unet handbook.

File transfer using `fput`

Now that we have a working link, you can transfer data or files between the modems. To transmit data, the UnetSocket APIs are a good starting point. These are supported in a variety of languages and levels.

To transmit a file, we can use the fput command. First, you will need to enable the remote agent in the receiving modem. On modem B, type the following:

> remote.enable = true
true

Then, use the fput command in modem A to transfer the file abc.txt:

> fput 120, 'abc.txt'
AGREE

Upon completion of the file transfer, you will receive a notification once the transfer is complete on the receiving modem.

remote >> RemoteFileNtf:INFORM[from:100 filename:abc.txt (4 bytes)]

Speedtest

Once you establish connectivity, you are ready to test the performance of the link. This can be achieved using the speedtest agent.

Typing speedtest on the shell shows the following:

> speedtest
« SpeedTest »

[org.arl.unet.utils.SpeedTest.Param]
  dutyCycle = 0.5
  nowDuration = 10
  nowput ⤇ 0
  rx ⤇ 0
  throughput ⤇ 0
  tx = 0

To run a speedtest between the modems, simply type the following on modem A:

> speedtest.tx=100
100

This will run the speedtest with 100 packets with the peer modem.

NOTE: The value calculated by the speedtest agent is the effective throughput seen by the user which includes the delays between each packet transmission and any lost packets. E.g. if you have a perfect link with no packet loss, the effective throughput will be half of the link rate due to the default value of 0.5 for the dutyCycle.

Once the test is completed, you can check the throughput using the throughput parameter.

> speedtest.throughput
12390

The maximum value of throughput you can achieve is the per-packet signaling rate or link rate that is configured for the device. This can be verified by using the following command:

> uwlink.dataRate
24780.055

For more details on each of the parameters, you can use the help text by typing help speedtest.

Tuning the link

Now that you have a working communication link, we want to tune the link to achieve the best performance. There are three ways to do this.

Link Tuner: A link tuner agent will make the required measurements and recommend the setting to achieve the best performance for a given link.
Communication Profiles: A set of preset configurations called communication profiles that the user can select from, depending on the environment.
Manual tuning: Users have complete control over each of the parameters for a communication scheme that they can modify to achieve the best performance for a given environment. However, this will require an understanding of what each of the parameters means and how they affect communication performance. Hence, this is recommended only for advanced users.

Link Tuner

The Link Tuner agent automatically makes channel measurements and provides the user with a recommended setting that works best in a given environment. To use the Link Tuner, navigate to the Link Tuner dashboard from the side menu. It shows the current scheme code which is a hexadecimal representation of all the current settings and the current link rate. Click the Tune button to begin the process. Once it is completed, a new scheme code is recommended that will provide the best performance in a given environment.

Link Tuner dashboard

Communication Profiles

A communication profile is a set of preconfigured settings that are appropriate for different types of environments. To set a communication profile, navigate to the Dashboards menu and select the Profiles link. That will give you the following screen with the supported profiles on your device. You can select one that closely matches the environment that you are working on. Once your chosen profile is set, you can verify that the link speed is updated by using the uwlink.dataRate command. Run the speed test again to verify the effective throughput you can achieve using the new settings.

Communication Profiles dashboard

Basic Troubleshooting

1. The landing dashboard is not loading

Check the connection to the modem by pinging the modem’s IP address from your laptop.
Make sure the modems are powered and the current drawn shown in the power supply corresponds to the published values.

2. `ping` is not working

Try adjusting the power levels of both modems.
Try adjusting the deployment depth of the modem as deploying very close to the surface may create challenging environments.
Check the logs (from the logs menu) to see if there are any error messages.

3. `tell` is not working (`ping` is working)

This indicates that the CONTROL channel is working and the DATA channel is having issues.

You can start with the Link Tuner or use a profile that is configured for a robust link.
Try adjusting the power levels.

In general, you can use logs or unsolicited notification messages to understand what is going on. This can be achieved by using the subscribe command. E.g. you can subscribe to physical layer events by:

> subscribe phy

This will print the various notifications generated by the agent that can be used for troubleshooting. E.g. when receiving packets, the following notifications will be printed in the shell while the ping command is used.

phy >> RxFrameStartNtf:INFORM[type:CONTROL rxTime:1765508396]
phy >> RxFrameNtf:INFORM[type:CONTROL from:100 rxTime:1765508396]

Low-cost DIY underwater modem using COTS components and Unet audio

Wed, 14 Sep 2022 00:00:00 +0000

Introduction

In the article titled Converting your laptop into a JANUS modem using Unet audio, we saw how UnetStack, a Software-Defined Open Architecture Modem (SDOAM), can be used to turn your laptop into an acoustic modem. A true SDOAM can easily be extended to run on various hardware platforms with different types of physical layers (e.g. Acoustic, optical, RF) with minimal efforts to address different use cases. In this article, we will show how you can build a low-cost (< USD 300) , DIY underwater acoustic modem using only Commercial Off-The-Shelf (COTS) components and Unet audio. The goal of this article is to demonstrate the approach and basic steps one can use to build a low cost acoustic modem using Unet audio. We encourage the reader to build on these principles to build your own versions of the DIY modem.

Motivation and Approach

Most commercially available modems are beyond the reach of a technology enthusiast or a hobbyist underwater roboticist, due to their price point. However, applications such as DIY underwater vehicles (e.g. for The Singapore AUV Challenge), low-cost swarms, etc. need low-cost underwater modems to realize their true potential. While there have been projects like the AHOI modem, SeaModem, Seatrac, all of them have custom hardware associated with them. This means the user needs to spend time building the hardware, which can be cumbersome and time-consuming. Adding additional hardware to a micro-AUV can be challenging due to space and power limitations. Ensuring long-term support for these can also be tricky, depending on the creator’s other commitments.

These are some of the challenges for anyone looking to use one of the existing projects to build on.

Unet audio being a true SDOAM addresses these by using a commonly available hardware platform such as Raspberry Pi and using its sound card to transmit and receive using an underwater speaker and microphone. This approach allows the user to run Unet audio in their single board computer (SBC) thereby avoiding the need for dedicated digital hardware (e.g. SBC, FPGA). The audio amplifiers can then be chosen based on the use case. By using Unet audio, the user gets access to all the developer tools and the extendability to build their protocols on top of the DIY modem. Long term support is guaranteed since UnetStack is actively developed by both academia (ARL) and industry (Subnero).

Workshop on building a DIY underwater modem during The Singapore AUV Challenge

Overview of the DIY modem

A modem has three main functions

Convert user-given data to a signal and transmit it to the receiver.
Decode the signal received at the receiver to recover the original data.
Configure various parameters to get the best communication performance.

To transmit a message, the user can use the various interfaces provided by Unet audio such as the web interface, shell, or various APIs in a variety of computer languages such as Java, Groovy, Python, C, Julia, Javascript, etc. The same interfaces can be used to configure various communication parameters to achieve the best performance in a given environment.

NOTE: UnetStack refers to a collection of technologies for extending networks underwater of which Unet audio is one of the components. An interested user may refer to the Unet handbook to gain a deeper understanding of it.

The user-provided data is then converted to passband signals in Unet audio. This includes transport and network layer processing (as required), fragmentation and reassembly, forward error correction (FEC), modulation, and demodulation depending on the communication scheme used. The passband signal (digital) is then converted to an analog signal using a sound card and passed through a power amplifier before being fed to the transducer/underwater speaker for transmission through the medium.

On the receive side, the signal is received using a hydrophone/underwater mic, converted to a digital signal using a sound card’s mic in port, and digitally processed to detect and decode the data from the signal using Unet audio. On successful decoding, the data is passed back to the user. If the decoding fails, an appropriate notification is provided to the user.

So the main hardware components of an SDOAM will be an SBC to run Unet audio, a sound card (with speaker out and mic in), audio amplifiers, and speaker and mic. The following sections list the hardware chain for both the transmit and receive chains.

Transmit chain

Connect the speaker output from the sound card (either a discrete or USB sound card connected to an SBC) to the amplifier module input. The amplifier output is then connected to the underwater speaker. Depending on the amplifier used, it can be powered using the USB output of the RPi or a 12V battery.

Transmit chain

Receive chain

For the receiver side, the underwater microphone is connected directly to the mic in of the soundcard of the SBC.

Receive chain

Hardware Selection

Digital Hardware

One of the most important hardware components of an SDOAM is the digital hardware that runs Unet audio. We have selected a Raspberry Pi (3b+) due to its popularity, low cost, ease of availability, and community support to be the digital hardware to run Unet audio. This can easily be swapped with any similar SBCs that have an arm processor running Linux on it. A USB sound card connected to the Raspberry Pi is used as the data acquisition system.

NOTE: The internal audio output was not used as it is disabled by default during setup.

Raspberry Pi

USB soundcard

Transmit Chain

The next step is the selection of the amplifier and the transducer/underwater speaker. To keep the costs down, we have chosen an underwater speaker JH001 for the transmitter.

JH001 Underwater Speaker

Most standard TDA series (e.g. TDA2030) mono amplifiers should work fine as the audio amplifier. We have selected the TDA2030A for use with our DIY setup. The user may choose an amplifier that meets your application.

Power Amplifier

Receive Chain

For the receive chain, we have used a simple electret microphone, waterproofed with household materials, connected to the sound card to receive signals.

Electret Microphones

The items used to waterproof the mic are listed below:

Chair bush: To be used as the backing for the mics. Choose a size that fits the electret microphone tightly. These are usually available in local hardware stores.
Cling wrap: For waterproofing the front of the electret microphone. The thinner the better.
Glue gun with glue stick: Used for waterproofing.
3.5mm mono audio jack: Connector for the sound card. If unable to find a mono jack, we can use a standard stereo jack as well. Either use only the left channel or short both the channels. Both schemes work.
Wires: To connect the mic to the sound card.

Components for waterproofing

Waterproofing

One of the terminals of the electret microphone is connected to the case and is the ground terminal. Connect that to the audio jack ground. The other terminal is output and is connected to the other two (or one in case of mono) connectors of the audio jack.

Mic pinout

Connection diagram

To waterproof the microphone, use a chair bush of size that fits tightly around it. Make a hole in the closed part of the bush just large enough for the wire. Put the wire through the hole and then pour a sufficient quantity of hot glue to create a good seal and push in the microphone. The microphone should be pushed in in a way that it protrudes out a bit, just enough for the black diaphragm at the front to protrude out a bit from the bush. Let the hot glue dry.

Next, wrap some cling wrap to waterproof the front portion. You can pour some hot glue on the outside surface of the bush and then wrap the cling wrap over the front of the microphone making sure that there is no gap between the cling wrap and the black diaphragm. If there is an air gap, then the performance might be affected.

Waterproofed mic

Bill of materials

Item	Qty	Cost (USD)
Raspberry Pi	1	129.00
USB sound card for RPi	1	0.87
Power amplifier	1	0.45
Underwater speaker	1	95.50
Electret microphone	1	0.99
3.5mm audio jack	2	1.36
Bush, glue gun, glue stick, cling wrap,	1	< 20
Total		292.72

NOTE: It is recommended to get more than 1 for the electret microphone, audio jacks, etc. in case of damage during assembly

Software installation

Requirements

Raspberry Pi 3+
USB Sound Card
Headphones/Loudspeaker
Microphone

Setup

OS

Install the latest Raspbian on your Raspberry Pi

Audio

Plug the USB audio card into your Raspberry Pi
Power on your Raspberry Pi
Ensure that the USB Audio Card is detected using aplay -l

> aplay -l
card 0: ...
card 1: Audio [USB Audio], device 0: USB Audio [USB Audio]
  Subdevices: 0/1
  Subdevice #0: subdevice #0

Disable the RaspberyPi onboard sound card, by commenting out the line dtparam=audio=on in /boot/config.txt

> sudo nano /boot/config.txt

# Enable audio (loads snd_bcm2835)
# dtparam=audio=on

Make the USB Audio card the default device in alsa by updating defaults.ctl.card and defaults.pcm.card to 1 in /usr/share/alsa/alsa.conf

defaults.ctl.card 1
defaults.pcm.card 1

Reboot your Raspberry Pi and verify that card 0: is not enumerated by aplay -l

> aplay -l
card 1: Audio [USB Audio], device 0: USB Audio [USB Audio]
  Subdevices: 0/1
  Subdevice #0: subdevice #0

You can test if your audio setup works properly using speaker-test -c2

Dependencies

Install Java8

wget https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u265-b01/OpenJDK8U-jdk_arm_linux_hotspot_8u265b01.tar.gz
tar xzf OpenJDK8U-jdk_arm_linux_hotspot_8u265b01.tar.gz
rm jdk8u265-b01/src.zip
sudo mkdir -p /usr/lib/jvm/java-8-openjdk-armhf
mv jdk8u265*/* /usr/lib/jvm/java-8-openjdk-armhf/
rm -r jdk8u265*
rm OpenJDK8U-jdk_arm_linux_hotspot_8u265b01.tar.gz
echo "export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-armhf" >> $HOME/.bashrc
echo "export PATH=\$PATH:/usr/lib/jvm/java-8-openjdk-armhf/bin" >> $HOME/.bashrc

Download portaudio for Linux
Build and install Portaudio

sudo apt-get install libasound-dev

...

./configure && make

...

sudo make install

...

sudo ldconfig

Run UnetStack

Get the UnetAudio Community distribution for RaspberryPi from here
Copy the unet-community-3.x.x.tgz file to the Raspberry Pi
Unzip the file tar -xvzf unet-community-pi-3.x.x.tgz
Go to the ~/unet-3.x.x directory
Run UnetAudio using bin/unet -c audio

This will give you a command shell for the user to interact with Unet audio.

Taking it for a spin

Once the Raspberry PI is set up as above, connect the various hardware components to form the transmit and receive chains. For our testing, we have one setup for transmission and one for the reception.

Transmitter and Receiver Components

Once we have both setups ready, we need to make sure we are generating the frequencies that the hardware can transmit. If we look at the frequency response of the underwater speaker (provided by the vendor), we can see that the frequency response is from 2 kHz to 8 kHz.

Frequency response of JH001

We will need to configure Unet audio to use a frequency band within this space so that the speaker can convert the signals generated by Unet audio to acoustic energy. Unet audio uses frequency hopping BFSK as its default communication scheme. The default parameters are as follows:

> phy[1]
« PHY »

...

[org.arl.unet.phy.fhbfsk.ModulationParam]
  chiplen = 1
  fmin = 9440
  fstep = 160
  hops = 13
  offset = 0
  sync = true

The first tone denoted by fmin starts at 9440 Hz, with 13 hops of 160 Hz each. This will be outside the frequency band of our underwater speaker. Hence, we will need to configure it to start after 3.5 kHz and end before 6 kHz. To achieve this, the frequency band of operation will need to be shifted slightly lower. This can be done by setting the fc to 6000 in etc/modem.conf file (The default value is set to 12000).

Next, we set the following parameters in the command line.

> phy[1].fmin = 4700
4700
> phy[1].fstep = 80
80

You will need to apply the same settings to phy[2] to ensure that the higher layer features utilizing phy[2] such as tell functions correctly.

> phy[2].fmin = 4700
4700
> phy[2].fstep = 80
80

This will give us a starting frequency of 4700 Hz and a bandwidth of 1920 Hz. Now we are ready to transmit and receive.

Depending on the environment of deployment, the transmit power level can also be adjusted as follows (A value of 0 denotes the maximum power).

> plvl -15
OK

To get a notification of a reception, use the following command on the receiver side.

> subscribe phy

Now we can transmit a simple byte stream of 1,2,3 using the following command on the shell.

> phy << new TxFrameReq(data:[1,2,3])
AGREE
phy >> TxFrameNtf:INFORM[type:CONTROL txTime:71663975]

You will also be able to hear the transmission from the underwater speaker.

Once received and decoded, the following message will be printed in the shell of the receiver side.

phy >> RxFrameStartNtf:INFORM[type:DATA rxTime:79709541 rxDuration:3880000 detector:0.27]
phy >> RxFrameNtf:INFORM[type:CONTROL from:1 rxTime:78466374 rssi:-29.8 cfo:0.0 (3 bytes)]

The data can be verified by typing the following.

> ntf.data
[1, 2, 3]

Congratulations, you have successfully made the first transmission and reception using your DIY acoustic modem.

Synchronizing physical clocks among different UnetStack-based modems

Mon, 28 Jun 2021 00:00:00 +0000

All UnetStack enabled modems have a Real-time Clock (RTC) to keep track of modem’s system time. A separate microsecond counter is provided by phy.time for Physical agent in UnetStack.

Although the clock (i.e., the hardware source of phy.time) is reasonably stable, it is impossible to guarantee that all the crystals of different computers will operate at exactly the same frequency. A crystal oscillator (XO) is an electronic circuit that uses the mechanical resonance of a vibrating piezoelectric crystal to create an electrical signal with the desired frequency. The resonant frequency depends on size, shape, elasticity, and the speed of sound in the material. Due to manufacturing tolerances, these properties are not identical across manufactured crystals, and so different crystals designed for the same nominal frequency produce slightly different frequency signals. Furthermore, as the operating temperature of the crystal changes, its material properties change, and so does its resonant frequency. These differences in frequency are tiny, but over long periods, the differences accumulate and cause the clocks to drift.

There are different oscillator types that exist to chose from including OCXOs, TCXOs, and XOs. The crystal controlled clock oscillator (XO) is a device that achieves its temperature stability from the quartz crystal’s inherent temperature stability. A temperature compensated crystal oscillator (TCXO) is a crystal oscillator with a temperature-sensitive reactance circuit in its oscillation loop to compensate the frequency-temperature characteristics inherent to the crystal unit. An OCXO is a crystal oscillator which is temperature controlled by a mini internal oven. This type of oscillator has a temperature controlling circuit to maintain a consistent temperature of the crystal and other key components. OCXOs are typically used when greater temperature stability is required. While this type of oscillator has a tenfold improvement over a TCXO for temperature vs. frequency stability, the OCXO tends to be higher in price and consumes more power.

NOTE: For example, UnetStack-based Subnero modems can be optionally upgraded to use low-drift clocks. Such clocks provide much better time stability and are suitable for such applications where time synchronization over long periods of time is critical.

Now, when there is a possibility of clock drift, it is not easy for having multiple spatially separated modems with synchronized physical clocks. So the question arises, if the synchronization of physical clocks across different UnetStack enabled modems is needed, how do we synchronize them with each other?

There are two major problems to be addressed to synchronize clocks among different modems:

Modems start at different times so there may be a clock offset as shown in figure below:

Modem clocks tick at different rates causing a clock drift as shown in figure below:

NOTE: The 20% clock drift shown in the figure is for illustration purpose only. In practice, the clock drift is expected to be much smaller in parts per million.

Compensating for clock offset

The Ranging agent in UnetStack running on the modem generates the clock offset information based on the message exchanges when range measurement is performed on the modem that initiates ranging. The clock offset between the two modems is populated in the ranging agent’s parameter ranging[host('B')].offset. Where host('B') is the node address of modem B. More details on this can be found here.

Once, the clock offset is known, it can be used to adjust the time locally to synchronize the physical time (phy.time). However, if a low-drift clock is not used, there is a possibility that the clocks tick at different rates, and clocks drift faster. Let us take a look at how we can compensate for the clock drift next.

Compensating for clock drift

Since the modems might tick at different rates, one modem’s clock may be faster than the other. An example is shown in the figure above where Modem A’s clock is faster than Modem B, i.e., a slope of 1.2 on Modem A’s clock. To compensate for this, the user of the modem can utilize a phy.clockCalib parameter. This parameter is a multiplier on the physical clock. So its default value is 1. If you set it to 1.2 the clock will run at 1.2x the rate of the actual hardware clock.

Therefore, to compensate Modem A’s clock to run slower so that it matches Modem B’s clock, we can set phy.clockCalib = 1/1.2 = 0.83.

The users of the modem should make measurements to figure out the nomimal values that they should set for phy.clockCalib.

An example of calibrating clock

We will consider two modems A and B for this example. To synchronize modem A’s clock with the modem B’s clock the following procedure may be followed:

Make a measurement of system time and physical clock time on modem A.

To measure system time, open modem’s web shell and type the following:

> phy.rtc.getTime()

To measure physical clock time, open modem’s web shell and type the following:

> phy.time

phy.rtc.getTime() returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this Date object (phy.rtc). The phy.time returns time in microseconds. Make a record of both these measurements in the same unit.

Repeat Step 1 after 1 hour and make another measurement. This step should be repeated hourly until the desired number of hours.
Plot a graph with measurements of system time on x-axis and physical clock time on y-axis.
Fit a straight line among these measurements.
Compute the slope of the line, say mA.
Repeat Steps 1-5 on modem B.
Compute the slope of the line, say mB.
To match the clocks to tick at the same rate, set modem A’s clock calibration parameter to following:

phy.clockCalib = mB/mA

We show here a simple code snippet to run on two modems (say A & B) to measure the slope and compute the calibration factor to set phy.clockCalib parameter. The code presented makes measurements every hour and runs for 24 hours.

On modem A:

def interval = 3600*1000 // 1 hour in ms
def noOfMeasurments = 24
def phy = agent('phy')
def systime = []
def phytime = []
noOfMeasurments.times {
	systime.append(phy.rtc.getTime())
	phytime.append(phy.time/1000)
	delay(interval)
}
// compute slope based on measurements
mA = (phytime[noOfMeasurments-1] - phytime[0])/(systime[noOfMeasurments-1] - systime[0]) 

On modem B:

def interval = 3600*1000 // 1 hour in ms
def noOfMeasurments = 24
def phy = agent('phy')
def systime = []
def phytime = []
noOfMeasurments.times {
	systime.append(phy.rtc.getTime())
	phytime.append(phy.time/1000)
	delay(interval)
}
// compute slope based on measurements
mB = (phytime[noOfMeasurments-1] - phytime[0])/(systime[noOfMeasurments-1] - systime[0]) // slope

Now, based on the computed slopes (mA and mB), the modem A’s clock can be set to the following to match the clocks to tick at the same rate:

phy.clockCalib = mB/mA

NOTE: The RTCs are long-term synchronized through mechanism such as Network Time Protocol (NTP) and therefore provide stability for clock calibration.

Calibrating clock without relying on RTC

In the earlier section we relied on NTP to provide stability to the RTC clock which was used as a reference for clock calibration. However, in cases where there is no such means (e.g. NTP) to provide long-term synchronization for RTC, we can measure and compare the clocks of the two modems directly. In this section, we describe through a simple python script on how one can achieve this.

On user’s machine:

import time
from unetpy import *

# open a UnetSocket to modem A
modemA = UnetSocket("modemA-IP", 1100)

# open a UnetSocket to modem B
modemB = UnetSocket("modemB-IP", 1100)

# get physical agent ids on modem A and B
phyA = modemA.agent("phy")
phyB = modemB.agent("phy")

# measure phy.time on both modem A and modem B

interval = 3600 # 1 hour in seconds

noOfMeasurements = 24

phytimeA = []
phytimeB = []

for i in range(noOfMeasurements):
	phytimeA.append(phyA.time)
	phytimeB.append(phyB.time)
	time.sleep(interval)

# compute slope based on measurements
m = (phytimeB[noOfMeasurments-1] - phytimeB[0])/(phytimeA[noOfMeasurments-1] - phytimeA[0]) # slope

Now based on the computed slope (m), we can set either modem A or modem B’s clockCalib parameter to match the clock rate of the other modem. Therefore, we can either set phy.clockCalib = m on modem A (or) set phy.clockCalib = 1/m on modem B to match the clock rates.

NOTE: The parameters used in all the code snippets shown in this blog such as interval and noOfMeasurements can be varied as per the user’s need. The code snippets are to serve as reference only.

Scheduling transmissions intelligently in UnetStack enabled modems

Mon, 31 May 2021 00:00:00 +0000

UnetStack powered acoustic modems provide extreme flexibility to the user to automate processes such as the transmission of data frames (e.g. position updates) or signals, decision making after the reception, etc. enabling a hands-off approach to test various deployment scenarios. If you are using a program or a script to transmit and receive from your software-defined open architecture acoustic modem (SDOAM), it is often good to know your location (latitude, longitude, and depth), to make decisions such as when to transmit, what power level to use, etc. This is not a big problem if your acoustic modem is deployed in a fixed location. However, if the modem is installed in a mobile underwater asset like an autonomous underwater vehicle (AUV), such decisions are crucial.

Since transducers are electromechanical devices, transmitting at high power closer to the water surface will cause cavitation that will result in a bad communication link. This may even damage the transducer. Additionally, if you are close to a receiving modem, transmitting at high power may saturate the receiver thereby causing the receiver to not being able to decipher your messages.

Some SDOAMs like the Subnero modems in standalone configuration come with a depth sensor (with the option to add more sensors like GPS, compass etc.). Let us take a look at how a user would use this information to decide when to transmit and when not to, from a modem that is installed in an AUV.

Figure 1: AUV internal connection

Figure 1 shows our assumptions on how the various components are connected within the AUV for this article. A single-board computer (SBC) in the AUV is connected to the modem over an Ethernet interface. Both the AUV’s SBC and the modem are in the same network.

To start with, let us assume the user would like to send periodic updates from AUV as a broadcast message. There are mainly two ways to do this.

Run a program in the SBC and connect to the modem using a UnetStack Gateway to send periodic commands to the modem, using Unet socket APIs. This can be done using any of the programming languages supported by UnetStack such as C, Java, Groovy, Python, Julia, etc. as detailed here. In this case, the user has access to various sensors of the AUV directly.
Running a groovy script in the modem to do the periodic transmissions. The advantage of this method is that you now have direct access to the modem and can deploy your own fjåge agents. This is a lot more flexible as compared to what is offered by the APIs.

To send a simple broadcast message once, you can use the tell command as follows.

tell 0, 'OK'

To execute this from a script, you can create a new file from the scripts tab in the UnetStack’s web interface.

Figure 2. UnetStack's web interface

To repeat this 100 times, once every second, the script can be updated to:

100.times {
  tell 0, 'OK'
  delay (1000)
}

The next step is to determine the current depth at which the device is, then decide whether to transmit or not.

In UnetStack, the NODE_INFO service provides a single place to collate node-related information that is commonly needed by many agents. One of the parameters of this service is the location which tracks the location of the modem are (x, y, z) in meters if the origin set, otherwise (latitude, longitude, z). If your modem has a depth sensor, the z value of node.location contains the depth information. You can update the script to transmit only at a depth less than -2 m, as follows.

100.times {
    depth = node.location[2]
    if (depth < -2) tell 0, 'OK'
    delay(1000)
}

NOTE: Depth is indicated as 0 (at water surface), -1 (1 m below the water surface), -2 (2 m below the water surface), and so on. See Section 5.6 of the unet handbook for a discussion on origin, location, and coordinate systems.

What if your modem does not have a depth sensor (e.g. embedded configuration) and you would like to use the sensor data from your AUV? In this case, you will have to run a program in the AUV’s SBC to get the location data from AUV’s sensors and use Unet socket APIs to update the node.location parameter, periodically. A pseudo-code (in python) for doing this is as follows.

from unetpy import *
import time

port = 1100
ip_address = 'modem IP'

# Open a unet socket connection to modem
sock = UnetSocket(ip_address, port)

# Get the agent which provide NODE_INFO service
node = sock.agentForService(Services.NODE_INFO)

# Update depth when available
while get_auv_depth() < 0:
  depth = get_auv_depth()
  lat = get_auv_lat()
  lon = get_auv_lon()
  node.location=[lat, lon, depth]
  time.sleep(1)

# Close the socket
sock.close()

The above code can easily be adapted in other languages such as C. A pseudo-code (in C) for the same is as follows:

#define BUF_SIZE 12

unetsocket_t sock;
fjage_aid_t node;
int port = 1100
const char* ip_address = 'modem IP'

// Open a unet socket connection to modem
sock = unetsocket_open(ip_address, port);
fjage_gw_t gw = unetsocket_get_gateway(sock);

// Get the agent which provides SHELL service
fjage_aid_t aid = unetsocket_agent_for_service(sock, "org.arl.fjage.shell.Services.SHELL");

// Update depth when available
while (get_auv_depth() < 0) {

  // NOTE: get_auv_depth(), get_auv_lat(), get_auv_lon() to be implemented by user
  char depth[BUF_SIZE] = {0};
  char lat[BUF_SIZE] = {0};
  char lon[BUF_SIZE] = {0};
  snprintf(depth, BUF_SIZE, "%f", get_auv_depth());
  snprintf(lat, BUF_SIZE, "%f", get_auv_lat());
  snprintf(lon, BUF_SIZE, "%f", get_auv_lon());
  
  char* cmd;
  asprintf(&cmd, "node.location=[%s, %s, %s]", lat, lon, depth);
  fjage_msg_t msg = fjage_msg_create("org.arl.fjage.shell.ShellExecReq", FJAGE_REQUEST);
  fjage_msg_set_recipient(msg, aid);
  fjage_msg_add_string(msg, "cmd", cmd);
  fjage_msg_t rsp = fjage_request(gw, msg, 1000);
  if (rsp != NULL) fjage_msg_destroy(rsp);
  free(cmd);
}

fjage_aid_destroy(aid);

// Close the socket
unetsocket_close(sock);

NOTE: The user will have to replace the above code with appropriate function calls to get the AUV sensor data.

The above examples can easily be adapted to check the range to a receiver (using range command) and adjust the transmit power level accordingly, to avoid saturating a receiver.

Conclusion

While acoustic modems were traditionally used as simple devices to transmit and receive data, UnetStack enabled SDOAMs to provide features to intelligently manage transmission and reception of data frames as well as signals based on various deployment scenarios.

Simulating motion in Unet Simulator

Tue, 27 Apr 2021 00:00:00 +0000

The Unet simulator supports various ways of simulating the motion of the simulated nodes, from simple dynamics models to completely custom functions that can generate motion updates. Let’s look at how one can go about simulating the motion of nodes in the Unet Simulator.

Dynamics Model

The NodeInfo agent (which is typically run in each simulated node) implements a basic dynamics model. The functionality can be turned on using the mobility parameter which can be set in a simulation script or directly on the NodeInfo agent in a running simulation.

When mobility is enabled, the NodeInfo agent automatically updates its location parameter based on motion parameters such as speed and heading using the simple dynamics model. This can be handy to simulate the motion of a node, for example, an AUV swimming away from an underwater modem.

Let’s try this out by manually updating the parameters of one of the nodes in a simulation, using the 2-node-network example from Unet IDE. The map view of the IDE can be used to visualize the motion of the nodes. Connect to the WebShell of Node B and set the mobility, heading, and speed parameters. As the simulation continues, the location of Node B will continue to be updated based on the speed and heading that you set.

For example, setting these values in the shell will cause the simulated node to as shown in the map view.

// On Node B's shell, set heading to 45deg and speed to 10m/s
node.mobility = true
node.heading = 45
node.speed = 10

Most channel models in UnetStack take into account the distance between the nodes for calculating successful receptions. Hence simulating the motion of nodes in a network simulation can be very useful to measure and verify network behavior and performance more accurately.

Setpoints

While the NodeInfo agent only exposes a basic dynamics model, the Unet simulation scripts allow for much more control by letting the user set a series of Setpoints of motion parameters on a node. This is done using the motionModel parameter on the node Object in the simulation script. The Unet Handbook has a few examples of this in Chapter 30.

Setting motionModel to a List of Maps with various motion properties for each of the Setpoint will automatically set the properties onto the NodeInfo agent in the simulated node at/for the appropriate time/duration. This in turn drives the dynamics model in the NodeInfo agent, giving the interpolated location between the Setpoints.

For example, a node moving in a square can be simulated using this simulation script using 4 Setpoints in the 2-node-network example. Note that the motion automatically stops after the last Setpoint.

def n = node 'B', location: [ 1.km, 0.km, -15.m], web: 8082, api: 1102, stack: "$home/etc/setup", mobility: true
n.motionModel = [
  [time:     0.minutes, heading:  0.deg, speed:   1.mps],
  [time:     1.minutes, heading:  -90.deg, speed: 1.mps],
  [time:     2.minutes, heading:  180.deg, speed: 1.mps],
  [time:     3.minutes, heading:  90.deg, speed:  1.mps],
]

The utility method MotionModel.lawnmower helps to generate this List for a set of Setpoint Map of properties for a lawnmower pattern of motion.

Custom motion model

Finally, if even more fine-grained motion control is required, one can set the property motionModel of the simulated node to a Groovy Closure. The closure is called by the simulator with the current simulation timestamp and is expected to return a single Setpoint in form of a Groovy Map.

For example, a similar logic to a square pattern can be implemented with this closure assigned to motionModel in the 2-node-network example.

def n = node 'B', location: [ 1.km, 0.km, -15.m], web: 8082, api: 1102, stack: "$home/etc/setup", mobility: true
startTime = -1
n.motionModel = { ts -> 
  def setpoint = [speed: 10.mps, duration: 1.minutes]
  if (startTime < 0) startTime = ts
  if (ts <= startTime+1.minutes){
    setpoint["heading"] = 0.deg
  } else if (ts <= startTime+2.minutes){
    setpoint["heading"] = -90.deg
  } else if (ts <= startTime+3.minutes){
    setpoint["heading"] = 180.deg
  } else if (ts <= startTime+4.minutes){
    setpoint["heading"] = 90.deg
  } else {
    setpoint = [speed:0.mps]
  }
  return setpoint
}

NOTE: Once a Setpoint is returned with its duration set to null, then it is assumed that the motion is complete and the simulator will stop calling the motionModel closure.

More complex logic can also be implemented inside such closures including communicating with other Agents and even other nodes.

Finally, the closure based approach can also allow one to override the builtin dynamics model in the NodeInfo agent by simply returning a Setpoint with a location property which will allow the location of the node to be updated directly from the closure instead of going through the dynamics model. In such a mode, however, since there is no interpolation of motion parameters, the duration of each Setpoint would have to be small.

For example, we can implement a similar pattern as our first example by updating the location of the node every second.

def n = node 'B', location: [ 1.km, 0.km, -15.m], web: 8082, api: 1102, stack: "$home/etc/setup", mobility: true
  n.motionModel = { ts -> 
    def l = agentForService(org.arl.unet.Services.NODE_INFO).location
    if (l != null){
        l[0] += 10*Math.sqrt(2)
        l[1] += 10*Math.sqrt(2)
    }
    return [duration: 1.seconds, location: l]
  }

Frequency band control using UnetStack

Wed, 21 Apr 2021 00:00:00 +0000

Acoustic modems transmit physical sound waves via a transducer, typically a piezoelectric device. Such sound emitters have an ideal resonance frequency F and a Q factor of the order of 0.3. This means that the efficient region of the frequencies it can transmit centers around the resonance frequency with a bandwidth of about 0.3 x F. Q may be higher or lower depending on the exact transducer.

The transducer in the Subnero M25M series modems has a resonance close to 26 kHz. The computationally possible bandwidth is 24 kHz, but not all of this bandwidth is feasible for the transducer. Thus the recommended default bandwidth is B = 12 kHz, which is half of the total possible. Thus an effective transmit modulation scheme can be set such that the center C = 26 kHz and B = 12 kHz.

Another reason may be due to acoustic underwater channel characteristics. A most basic property is that higher frequencies get absorbed more and in general have a lower transmission range. For this or other reasons related to the channel, the modem user may want to customize the frequencies transmitted by the modem.

Multiple Access is another case where users may want to control the band used in each modem. One common multiple access method is Frequency Domain Multiple Access (FDMA). In this scheme, different modems or modem pairs may be allocated a different frequency band for transmission to avoid a collision. Simultaneous transmission-reception by two or more different and colocated modem pairs is possible using FDMA.

Sometimes, there may be a frequency band the user may want to exclude from usage, due to it being occupied by other sources, noise, etc.

The reader may wish to install Unet audio and try out some basic examples in the following sections.

OFDM frequency band control

OFDM is one of the main modulation schemes provided with UnetStack-based modems. It is the default DATA channel in UnetStack modems. Controlling the bandwidth and center of the frequency band used is very simple for this scheme.

OFDM uses several carriers to modulate the baseband data and the number is specified via phy[2].nc. These carriers span the total available bandwidth (24 kHz for Medium Frequency Subnero modem variants), i.e., from 12 kHz to 36 kHz.

The parameter phy[2].bw. controls a reduction in the usage of this total bandwidth. I.e., if we specify phy[2].bw = 0.5, it reduces the bandwidth used by half, i.e, 24 kHz / 2 = 12 kHz.

The other parameter involved in bandwidth control is phy[2].dc0. This controls the starting carrier number.

dc0 >= -nc/2 || dc0 <= nc/2

This can be used to shift the center of the frequency band “left” or “right”.

As mentioned above, to set the band to match the transducer, we need C = 26 kHz and B = 12 kHz.

The default modem parameters are set as follows to achieve this.

> phy[2]
  ...
  bw = 0.5
  dc0 = 85
  nc = 1024

phy.dc0=85 shifts the center by approximately 2000 Hz. Carriers go from -512 to +512 to span the band from 12 kHz to 36 kHz. 85/512 ~= 1/6, so the center will shift roughly by 1/6 of 12 kHz = 2000 Hz (the positive half band) to 26 kHz from 24 kHz.

phy[2].bw = 0.5 will reduce the active carriers by half, so a bandwidth of 12 kHz. Thus together, the used bandwidth will go from 20kHz to 32kHz.

For Unet audio, the same settings will shift the center by 1 kHz to 13 kHz with a bandwidth of 6 kHz. Therefore from 10kHz to 16kHz, this is seen below (plvl = -25, trigger -70, may vary for user).

Note that if there is a frequency band to be avoided, we can position the used band to the “left” or “right” of it by adjusting nc, dc0, and bw. Note that going far away from the ideal transducer resonance region will reduce transmission efficiency.

The usage and meaning of parameters can be found in Command Reference

FHBFSK frequency band control

For FHBFSK scheme, the parameter phy[3].fmin specifies the starting frequency. phy[3].fstep specifies the frequency steps and phy[3].hops the total number of frequencies used.

By default, you may see in the Unet audio modem

> phy[3]
  ...
  fmin = 9520.0
  fstep = 160.0
  hops = 13

So it starts from 9520 Hz and goes to 9520 + 160 x (13-1) x 2 = 13360 Hz as seen below. The effective bandwidth can be roughly taken as fstep x hops x 2.

We can alter the above parameters to use a band anywhere between 6 kHz and 18 kHz, which is the computationally feasible band of the Unet audio modem.

Note that just as in OFDM, if there is a frequency band to be avoided, we can position the used band to the “left” or “right” of it by adjusting fmin, fstep and hops.

The default CONTROL channel in UnetStack-based modems is such an FHBFSK scheme.

Control of Preamble bandwidth

To complete the picture of bandwidth control, it must be noted that the signal that is transmitted not only has a data modulated portion, but also a detection preamble at the start. This is usually a signal that has good autocorrelation properties like a pseudo-random noise signal or m-sequences, hyperbolic chirp (HFM), etc.

The Preamble class provides both the above types of preambles via the methods such as mseq(..), hfmUpSweep(..), hfmDownSweep(..). It allows controlling the bandwidth and center frequency of the preamble.

Let’s look at one of them

public static Preamble hfmDownSweep(int len, int sps, float fc)

len is the number of baseband samples
sps controls the bandwidth Preamble bandwidth = baseband bandwidth/sps. Note that sps must be an integer. Thus for Unet audio, sps = 4 creates a bandwidth of 12 kHz / 4 = 3 kHz.
fc controls the center frequency. This is normalized to the baseband rate. So for Unet audio, fc = 0.25 will shift the carrier by 12 kHz x 0.25 = 3 kHz. i.e., from 12 kHz to 15 kHz.

E.g., the following creates an HFM down sweep signal with 1000 baseband samples, a bandwidth of 3 kHz, centered at 15 kHz.

> phy[3].preamble = org.arl.yoda.Preamble.hfmDownSweep(1000, 4, 0.25)
(1000 samples)

To transmit this preamble alone (with no additional signal)

> phy << new TxBasebandSignalReq(preamble: 3)

In the Diagnostic Scope dashboard, let us look at the passband PSD. With an appropriate trigger, you may get something as follows. It clearly shows the center of 15 kHz and the bandwidth of 3 kHz.

The user can also generate and set custom preambles.

NOTE: Details of the custom preamble are available in section 16.4. Transmitting and detecting preambles` of the Unet handbook.

Conclusion

There is a need to control the frequency band of operation in acoustic modems and we have seen how easy it is to control it in both OFDM and FHBFSK schemes in the UnetStack-based modems.

What's new in UnetStack 3.3?

Thu, 01 Apr 2021 00:00:00 +0000

It is April again, and that means it is time for the next release of UnetStack! We are excited to bring several new features to you – a new JSON event logging framework for automated analysis of multi-agent protocols, support for signal strength and ambient noise level reporting in the Unet simulator, and experimental support for Julia agents! In addition, UnetStack 3.3 also incorporates numerous enhancements, bug fixes and performance improvements.

Let’s take a brief look at the key new and exciting features:

1. JSON event tracing framework

When Unet simulator was first developed, we adopted the trace.nam file format from NS2 for event logging, since many users in the community were already familiar with it. While it served its purpose in the initial days, as agents became more sophisticated and interactions between agents more complicated, we received feedback from many users that they wanted a richer trace format that can be used for automated analysis of multi-agent protocols. We are happy to announce a new JSON trace format that provides a much richer trace that can be easily analyzed using most modern languages with JSON support.

When running a simulation, a JSON trace file trace.json is automatically generated in the logs folder. This file contains a detailed trace for every event in the network stack, on each node. You can even enable trace file generation on real modems and other Unet nodes (using EventTracer.enable()), and later combine the traces from multiple nodes to analyze network protocol operation and performance.

A small extract from a typical trace file is shown below:

{"version": "1.0","group":"EventTrace","events":[
 {"group":"SIMULATION 1","events":[
  {"time":1617877446718,"component":"arp::org.arl.unet.addr.AddressResolution/B","threadID":"0bfb305d-4920-4df0-af95-5282b048b5ec","stimulus":{"clazz":"org.arl.unet.addr.AddressAllocReq","messageID":"0bfb305d-4920-4df0-af95-5282b048b5ec","performative":"REQUEST","sender":"node","recipient":"arp"},"response":{"clazz":"org.arl.unet.addr.AddressAllocRsp","messageID":"3e421e28-89ca-44ec-bc65-16cc404d3703","performative":"INFORM","recipient":"node"}},
  {"time":1617877446718,"component":"arp::org.arl.unet.addr.AddressResolution/A","threadID":"04f5b1b9-9178-4e27-aae7-e2a0c4ffcd89","stimulus":{"clazz":"org.arl.unet.addr.AddressAllocReq","messageID":"04f5b1b9-9178-4e27-aae7-e2a0c4ffcd89","performative":"REQUEST","sender":"node","recipient":"arp"},"response":{"clazz":"org.arl.unet.addr.AddressAllocRsp","messageID":"e0fe806d-625d-4261-b24c-6655b90cc06a","performative":"INFORM","recipient":"node"}},
      :
      :
 ]}
]}

The trace is organized into a hierarchy of groups, each describing a simulation run or the execution of specific commands. A group consists of a sequence of events, with each event providing information on time of event, component (agent running on a node), thread ID, stimulus and response. The stimulus is typically a message received from another agent, and response a message sent to another agent. The thread ID ties multiple events, potentially across multiple agents and nodes, but with the same root cause together.

Integrating the event tracing framework into your own agents is simple. All you need to do is to wrap messages that you generate in response to a stimulus with a trace() call. Some examples:

send trace(stimulus, new DatagramDeliveryNtf(stimulus))
request trace(stimulus, req), timeout

All the default agents in UnetStack 3.3 are now compliant with the JSON event logging framework.

2. Automated trace analysis tool (experimental)

To illustrate the power of the event logging framework, we have built a simple viztrace tool to automatically draw sequence diagrams from a JSON trace file. The tool is written in Julia, and will require a working installation of Julia on your machine to run.

To illustrate the power of the tool, let us simulate a simple 2-node network and make a range measurment from node A to B. On node A:

> range host('B')
999.99976

If you look in the logs folder in the simulator, you’ll find a trace.nam file. We can analyze it using the viztrace tool:

$ julia --project viztrace.jl trace.json
Specify a trace:
1: 1617881734525 [B] AddressAllocReq ⟦ node → arp ⟧ (1 events)
2: 1617881734525 [A] AddressAllocReq ⟦ node → arp ⟧ (1 events)
3: 1617881734531 [A] AddressResolutionReq ⟦ websh → arp ⟧ (1 events)
4: 1617881734595 [A] RangeReq ⟦ websh → ranging ⟧ (23 events)

So the tool tells us that there are 4 event traces in the trace.json file. The first 2 traces are related to address allocations on nodes B and A. The third trace is an address resolution for node B, when we called host('B'). The final trace is the actual ranging event, consisting of 23 individual sub-events. Let’s explore that in more detail:

$ julia --project viztrace.jl -t 4 trace.json > event4.mmd

This generates a mermaid sequence diagram for all the events in trace 4:

sequenceDiagram
  participant websh_A as websh/A
  participant ranging_A as ranging/A
  participant mac_A as mac/A
  participant phy_A as phy/A
  participant phy_B as phy/B
  participant ranging_B as ranging/B
  websh_A->>ranging_A: RangeReq
  ranging_A-->>websh_A: AGREE
  ranging_A->>mac_A: ReservationReq
  mac_A->>ranging_A: ReservationRsp
  mac_A->>ranging_A: ReservationStatusNtf
  ranging_A->>phy_A: ClearReq
  phy_A-->>ranging_A: AGREE
  ranging_A->>phy_A: TxFrameReq
  phy_A-->>ranging_A: AGREE
  phy_A->>ranging_A: TxFrameNtf
  phy_A->>phy_B: HalfDuplexModem$TX
  phy_B->>ranging_B: RxFrameNtf
  ranging_B->>phy_B: ClearReq
  phy_B-->>ranging_B: AGREE
  ranging_B->>phy_B: TxFrameReq
  phy_B-->>ranging_B: AGREE
  phy_B->>ranging_B: TxFrameNtf
  phy_B->>phy_A: HalfDuplexModem$TX
  phy_A->>ranging_A: RxFrameNtf
  ranging_A->>websh_A: RangeNtf
  ranging_A->>mac_A: ReservationCancelReq
  mac_A-->>ranging_A: AGREE
  mac_A->>ranging_A: ReservationStatusNtf

We can easily convert this to a nice sequence diagram using the mermaid command-line interface or the mermaid online live editor:

3. Signal strength and ambient noise level reporting

While most UnetStack-based modems support reporting of ambient noise level and received signal strength indicator (RSSI), the simulated HalfDuplexModem in UnetStack did not previously provide this information. With UnetStack 3.3, it does!

With the simulated 2-node network, for example:

> phy.noise
96.1236

tells us that the ambient noise level is 96.1 dB. If we subscribe to the phy agent on node B and transmit a frame from node A, we see RSSI of 112.4 dB in the notification on node B:

phy >> RxFrameStartNtf:INFORM[type:CONTROL rxTime:973249369]
phy >> RxFrameNtf:INFORM[type:CONTROL from:232 rxTime:973249369 rssi:112.4]

This information may be useful to agents that automatically adapt transmit power or other link parameters based on signal strength or signal-to-noise ratio.

4. Julia agents (experimental)

As we have seen in two previous blog articles (part I, part II), the power of Julia can be harnessed by UnetStack agents via UnetSockets.jl or the Java-Julia bridge. While this is great, wouldn’t it be even better if we could write UnetStack agents fully in Julia?

Well, now you can! We now have experimental support for first-class Julia agents in UnetStack via Fjage.jl. Stay tuned for an upcoming blog article on how to write a custom PHY as a first-class Julia agent!

5. Numerous other improvements

There are many other enhancements, bug fixes and performance improvements in UnetStack 3.3. While we won’t list of of them explicitly, there are a few enhancements that are worth a passing mention:

Added NodeInfo service parameters for roll and pitch, allowing UnetStack on autonomous underwater vehicles (AUVs) to use orientation information in making intelligent decisions.
On modems supporting low power sleep mode, an AboutToSleepNtf message is broadcasted before a modem goes to sleep, enabling agents to do housekeeping before taking a nap.
Add eternity as an alias for forever for sleep scheduling shell commands.
Improved communication performance for UdpLink and acoustic OFDM links.
Added support for 32x upsampling and 16x decimation to support additional frequency bands of operation.

Converting your laptop into a JANUS modem using Unet audio

Sun, 06 Dec 2020 00:00:00 +0000

Imagine you are developing an application for an underwater use case such as messaging or file transfer and you intend to eventually deploy the app on a network of JANUS compliant modems in the field. Or you may be developing a new routing protocol that is intended to work on a network of JANUS compliant modems. Or you might be a university Professor designing an exercise for your students to learn about underwater communications and networking.

Along with developing the app or the protocol, a common step is to simulate its performance using simulators like UnetSim. However, before deploying the app on actual modems and going to the field for testing, you want to make sure it works on actual devices as intended. If you are in a classroom, having a hardware component that can actually transmit and receive the frames would be extremely useful. This is where Unet audio comes in handy.

What is Unet audio?

Unet audio is one of the software-defined open architecture modems (SDOAMs) that is built using UnetStack technologies that let users convert their computers to an acoustic modem. It uses a computer’s sound card (or any sound card attached to a computer) along with its speaker and microphone as the hardware to transmit and receive data or signals as instructed by the user.

Unet audio Block Diagram

Running Unet audio

Make sure your computer meets all the prerequisites as listed in below:
- Operating system: OS X / Linux (x86_64)
- Software: Java 8 runtime environment
- Driver: PortAudio
- Browser: Chrome 61+ / Firefox 60+ / Safari 10.1+
Head to www.unetstack.net and download a copy of the UnetStack community edition.

Untar the zip file, open a terminal in the download’s root folder and type:

> bin/unet audio
Modem web: http://localhost:8080/

This should start up the SDOAM and open a browser with a command shell accessing the modem. If the browser does not automatically open, just enter the modem web URL shown above in your browser. At the command shell, you can try transmitting a message:
```
1
2
> tell 0, 'hello sea!'
AGREE
```

You should hear the transmission from your computer speaker! If you don’t, check your speaker volume and try again.

Great, you have just transmitted a message using the default settings of Unet audio.

NOTE: If you have two computers with speakers and microphones, you can run Unet audio on both, and communicate between the two. If you happen to have only one computer handy, we can get one Unet audio instance to transmit and receive at the same time as detailed in section 15.4. Transmitting & receiving using Unet audio of the Unet handbook.

Transmitting & receiving JANUS frames

The physical layer in Unet audio typically supports 3 logical channels . The first two are used for CONTROL and DATA, and the third, by default, is configured as JANUS. The CONTROL channel uses FH-BFSK (frequency-hopping binary frequency shift keying) by default, which is very close to JANUS, but not exactly the same. Let us take a look at the differences between the two and how to make your transmissions fully JANUS compliant.

If you simply type phy on the web shell, you get a list of physical layer parameters for Unet audio:

> phy
« Physical layer »

Provides software-defined physical layer communication services (including error detection & correction).

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

[org.arl.unet.phy.PhysicalParam]
  maxPowerLevel ⤇ 0.0
  minPowerLevel ⤇ -138.0
  propagationSpeed = 1500.0
  rxEnable = true

[org.arl.yoda.ModemParam]
  adcrate ⤇ 48000.0
  dacrate ⤇ 96000.0
  fullduplex = false
  loopback = false
  model ⤇ Unet audio
  vendor ⤇ UnetStack

NOTE: For brevity, we have omitted the baseband service, scheduler service parameters and some of the non-relevant parameters in the listings given in this article. Even then, there are many parameters that allow you to configure the SDOAM. We cannot cover each parameter in detail here, but we encourage you to explore the help pages for the parameters by simply typing help phy followed by the parameter name.

Unet audio defines three types of frames:

CONTROL frame = 1
DATA frame = 2
JANUS frame = 3

To get the details of each type of frame, you can use indexed parameters. For getting the details of CONTROL channel, type phy[1] (or phy[CONTROL]).

> phy[1]
« PHY »

[org.arl.unet.phy.PhysicalChannelParam]
  dataRate ⤇ 70.588234
  errorDetection ⤇ true
  fec = 1
  fecList ⤇ [ICONV2]
  frameDuration ⤇ 2.04
  frameLength = 18
  janus = false

[org.arl.yoda.FhbfskParam]
  chiplen = 1
  fmin = 9520.0
  fstep = 160.0
  hops = 13
  scrambler = 0
  sync = true
  tukey = true

Similarly, typing phy[3] will list the parameters of JANUS frame.

> phy[3]
« PHY »

[org.arl.unet.phy.PhysicalChannelParam]
  dataRate ⤇ 58.181816
  errorDetection ⤇ true
  fec = 1
  fecList ⤇ [ICONV2]
  frameDuration ⤇ 1.1
  frameLength = 8
  janus = true

[org.arl.yoda.FhbfskParam]
  chiplen = 1
  fmin = 9520.0
  fstep = 160.0
  hops = 13
  scrambler = 0
  sync = true
  tukey = true

The first difference you will notice between the three is the phy.janus parameter which is set to false for the CONTROL channel and true for JANUS channel. The settings phy.janus & modulation = fhbfsk sets up the modulation for JANUS.

The other key parameters to take note of:

fmin = 9520.0, fstep = 160.0 and hops = 13 are the modulation parameters to setup fhbfsk as required by JANUS.
fec = 7 chooses ICONV2 from the fecList, to set up UnetStack to use the Interleaved Convolution Code (2:1) as required by JANUS
threshold = 0.0 indicates that the reception of JANUS frames is disabled by turning off the detector

Notice how they are different between the CONTROL channel and the JANUS channel. As a result, the data rate provided by the CONTROL channel is different from that of the JANUS channel.

To enable JANUS reception, you need to set:

> phy[3].threshold = 0.3

NOTE: To avoid detection for other type of frames, you can disable the other two channels by setting the threshold to zero.

Now comes the most exciting part – communicating between two computers using JANUS with Unet audio. First you need to setup you receiving computer to generate notification after a reception by typing:

subscribe phy

This will show notifications from phy on the shell.

Next, you can make a JANUS transmission by typing:

> phy << new TxJanusFrameReq()
AGREE
phy >> TxFrameNtf:INFORM[type:#3 txTime:127730682]

This will transmit a broadcast JANUS frame.

On the receiving computer, you should see:

phy >> RxFrameStartNtf:INFORM[type:#3 rxTime:127730375 rxDuration:1100000 detector:0.96]
phy >> RxJanusFrameNtf:INFORM[type:#3 classUserID:0 appType:0 appData:0 mobility:false canForward:true txRxFlag:true rxTime:127730374 rssi:-44.2 cfo:0.0]

NOTE: The JANUS frame format doesn’t contain user data by default, and so the MTU is 0 (frameLength of 8 as defined in JANUS specifications). JANUS allows vendors to provide their own “cargo”, and so UnetStack lets you increase the frameLength to make space for user data (MTU).

If you would like to add a payload, you can increase the phy.frameLength parameter (default is 8). Let us transmit 1 byte of data.

> phy[3].frameLength=9
9

Data can be added to the transmission by typing:

> phy << new TxJanusFrameReq(data:[1])
AGREE
phy >> TxFrameNtf:INFORM[type:#3 txTime:1754760016]

On the receiving side:

> phy << new TxJanusFrameReq(data:[1])
AGREE
phy >> RxFrameStartNtf:INFORM[type:#3 rxTime:1754759709 rxDuration:1300000 detector:0.96]
phy >> RxJanusFrameNtf:INFORM[type:#3 classUserID:0 appType:0 appData:0 mobility:false canForward:true txRxFlag:true reservationDuration:0.15031052 rxTime:1754759708 rssi:-44.3 cfo:0.0 (1 byte)]

You can check the content of the received frame by typing:

> ntf.data
[1]

Similarly, if you want to transmit 2 bytes of data, you can set the phy.frameLength parameter to 10 and transmit an array of 2 bytes as:

> phy[3].frameLength=10
10
> phy << new TxJanusFrameReq(data:[1,2])
AGREE
phy >> TxFrameNtf:INFORM[type:#3 txTime:398270432]

It is that simple to set up an SODAM on your laptop/computer and transmit and receive acoustic communication signals using Unet audio.

Conclusion

Unet audio provides an easy method for researchers, teachers and students to convert their computers to a JANUS compliant SDOAM. Even the cheapest of the underwater acoustic modems comes at a cost and may not be the best option to invest in, if the intended purpose is teaching. Unet audio community edition is free for academic and research use.

Even if you happen to own some UnetStack compatible acoustic modems, testing with a modem means setting up a dedicated test setup & equipment, access to a water body and dealing with the logistics. With Unet audio, you can develop and test from the comfort of your seat. Additionally, Unet audio provides an SDOAM that covers the frequency band of operation as defined by the JANUS specifications.

This post only gives you a glimpse of how you can do JANUS transmissions and receptions using Unet audio. There are many more interesting things you can do like transmit and receive the raw baseband signals from a *.wav file and plot a spectrogram to verify the signal is indeed JANUS compliant (as illustrated here), or setup a network of SDOAMs that uses JANUS as their physical layer.

OCEANS’19 JANUS Tutorial - Highlights Video

Harnessing the power of Julia in UnetStack — Part II

Sun, 01 Nov 2020 00:00:00 +0000

In my previous article on developing your own acoustic PHY, I showed you how to develop your own acoustic PHY in Groovy or Java. However, Groovy and Java are not well suited to writing complex mathematical algorithms. Wouldn’t it be nice if we could write the algorithms in Julia instead? In this article, we take the custom PHY we developed previously, and replace the signal processing methods with the Julia equivalents. The technique applies not just to PHY agents, and so this article should get you started on leveraging Julia in any UnetStack agents (or for that matter in any Java or Groovy code).

Java-Julia Bridge

Julia is a wonderful language to implement mathematical and signal processing algorithms. It solves the two-language problem by allowing you to write your algorithm in a nice high-level mathematically intuitive style, while generating performant native code that can be used in real-time systems. In the “Harnessing the power of Julia in UnetStack — Part I” article, we looked at how to access UnetStack functionality from Julia. In this article, we’ll do the reverse – we’ll explore how to use Julia code in UnetStack agents.

In order to access Julia’s mathematical prowess from Groovy or Java agents, we need a way to call Julia functions from the JVM. The Java-Julia Bridge (JaJuB) project provides exactly this functionality, and we’ll leverage it in this article.

Modulation and demodulation

Recall from my previous article on developing your own acoustic PHY that we developed a simple uncoded binary frequency-shift keying (BFSK) implementation in Groovy. While this implementation wasn’t difficult to do, Groovy or Java aren’t ideally suited for mathematical algorithms. So let’s see what the equivalent code would look like in Julia.

The Groovy modulation code we used was encapsulated within a single method bytes2signal():

private float[] bytes2signal(byte[] buf) {
  float[] signal = new float[buf.length * 8 * SAMPLES_PER_SYMBOL * 2]   // 8 bits/byte, 2 floats/sample
  int p = 0
  for (int i = 0; i < buf.length; i++) {
    for (int j = 0; j < 8; j++) {
      int bit = (buf[i] >> j) & 0x01
      float f = bit == 1 ? -NFREQ : NFREQ
      for (int k = 0; k < SAMPLES_PER_SYMBOL; k++) {
        signal[p++] = (float)Math.cos(2 * Math.PI * f * k)
        signal[p++] = (float)Math.sin(2 * Math.PI * f * k)
      }
    }
  }
  return signal
}

The equivalent Julia code is this:

function bytes2signal(buf)
  signal = Array{ComplexF32}(undef, length(buf) * 8 * SAMPLES_PER_SYMBOL)
  p = 1
  for b in buf
    for j in 0:7
      bit = (b >> j) & 0x01
      f = bit == 1 ? -NFREQ : NFREQ
      signal[p:p+SAMPLES_PER_SYMBOL-1] .= cis.(2pi * f * (0:SAMPLES_PER_SYMBOL-1))
      p += SAMPLES_PER_SYMBOL
    end
  end
  return signal
end

Being able to use complex numbers directly in Julia is such a pleasure! While this code isn’t particularly different, as you start implemeting more complex algorithms, you’ll appreciate the different a lot more.

The Groovy demodulation code we used was in the method signal2bytes() and a helper method abs2:

private byte[] signal2bytes(float[] signal, int start) {
  int n = (int)(signal.length / (2 * SAMPLES_PER_SYMBOL * 8))       // number of bytes
  def buf = new byte[n]
  int p = start
  for (int i = 0; i < buf.length; i++) {
    for (int j = 0; j < 8; j++) {
      double s0re = 0                 // real path of matched filter for f0
      double s0im = 0                 // imaginary path of matched filter for f0
      double s1re = 0                 // real path of matched filter for f1
      double s1im = 0                 // imaginary path of matched filter for f0
      for (int k = 0; k < SAMPLES_PER_SYMBOL; k++) {
        float re = signal[p++]
        float im = signal[p++]
        float rclk = (float)Math.cos(2 * Math.PI * NFREQ * k)
        float iclk = (float)Math.sin(2 * Math.PI * NFREQ * k)
        s0re += re*rclk + im*iclk
        s0im += im*rclk - re*iclk
        s1re += re*rclk - im*iclk
        s1im += im*rclk + re*iclk
      }
      if (abs2(s1re, s1im) > abs2(s0re, s0im))
        buf[i] = (byte)(buf[i] | (0x01 << j))
    }
  }
  return buf
}

private double abs2(double re, double im) {
  return re*re + im*im
}

In Julia, we don’t need the helper method, and the complex number calculations become simpler:

function signal2bytes(signal)
  n = length(signal) ÷ (SAMPLES_PER_SYMBOL * 8)
  buf = zeros(Int8, n)
  p = 1
  for i in 1:length(buf)
    for j in 0:7
      s = @view signal[p:p+SAMPLES_PER_SYMBOL-1]
      p += SAMPLES_PER_SYMBOL
      x = cis.(2pi * NFREQ .* (0:SAMPLES_PER_SYMBOL-1))
      s0 = sum(s .* conj.(x))
      s1 = sum(s .* x)
      if abs(s1) > abs(s0)
        buf[i] = buf[i] | (0x01 << j)
      end
    end
  end
  return buf
end

Using JaJuB from our PHY agent

In order to run the Julia code from our PHY agent, we need to pass it to JaJuB as a string. For a complex piece of code, we might store it in a .jl file and load it as a resource from Groovy, but since our code is simple, we’ll just insert it in our Groovy source code directly. This also enables us to directly insert constants in our Groovy code (e.g. SAMPLES_PER_SYMBOL and NFREQ) into the Julia code using Groovy’s string interpolation syntax (${...}), rather than have to pass them as arguments to the function.

The modulation method now looks like this:

private final String julia_bytes2signal = """
  function bytes2signal(buf)
    signal = Array{ComplexF32}(undef, length(buf) * 8 * ${SAMPLES_PER_SYMBOL})
    p = 1
    for b in buf
      for j in 0:7
        bit = (b >> j) & 0x01
        f = bit == 1 ? -${NFREQ} : ${NFREQ}
        signal[p:p+${SAMPLES_PER_SYMBOL-1}] .= cis.(2pi * f * (0:${SAMPLES_PER_SYMBOL-1}))
        p += ${SAMPLES_PER_SYMBOL}
      end
    end
    return signal
  end
"""

private float[] bytes2signal(byte[] buf) {
  def arg = new ByteArray(data: buf, dims: [buf.length] as int[])
  def rv = (FloatArray)julia.call("bytes2signal", arg)
  return rv?.data
}

The original bytes2signal() method in Groovy is replaced by a julia.call() to the Julia implementation of the function bytes2signal() defined in julia_bytes2signal. To pass the byte array to Julia, we need to wrap the byte[] in a ByteArray instance provided by JaJuB. The return value from the function is a complex float array, which we get as a FloatArray instance. The data field of the FloatArray object is simply the float[] that we return from the Groovy method.

Similarly, we convert the demodulation function to also use the Julia code:

private final String julia_signal2bytes = """
  function signal2bytes(signal)
    n = length(signal) ÷ (${SAMPLES_PER_SYMBOL} * 8)
    buf = zeros(Int8, n)
    p = 1
    for i in 1:length(buf)
      for j in 0:7
        s = @view signal[p:p+${SAMPLES_PER_SYMBOL-1}]
        p += ${SAMPLES_PER_SYMBOL}
        x = cis.(2pi * ${NFREQ} .* (0:${SAMPLES_PER_SYMBOL-1}))
        s0 = sum(s .* conj.(x))
        s1 = sum(s .* x)
        if abs(s1) > abs(s0)
          buf[i] = buf[i] | (0x01 << j)
        end
      end
    end
    return buf
  end
"""

private byte[] signal2bytes(float[] signal, int start) {
  def arg = new FloatArray(
    data: signal[start..-1] as float[],
    dims: [(signal.length-start).intdiv(2)] as int[],
    isComplex: true
  )
  def rv = (ByteArray)julia.call('signal2bytes', arg)
  return rv?.data
}

Here we pass in a FloatArray representing the complex baseband signal to the Julia function, and get back a ByteArray with the demodulated data.

Before we can use the julia.call() functionality from JaJuB, we need to initialize Julia. We do this by adding an attribute to our class (after importing org.arl.jajub.*):

private JuliaBridge julia = new JuliaBridge()

and loading the two functions at startup (code inserted in our setup() method):

julia.open()
julia.exec(julia_bytes2signal)
julia.exec(julia_signal2bytes)

We also add a shutdown() method to our agent to cleanly shutdown Julia when the agent terminates:

void shutdown() {
  julia.close()
}

Thats it!

The entire modified agent source code can be found in the unet-contrib repository.

Testing our custom Julia PHY

Now that we’ve the modified Julia-based phy2 agent, it is time to try it out on Unet audio. Copy the MyJuliaPhy.groovy file to the classes folder in Unet audio. Download JaJuB jar and put it in the jars folder.

If you don’t already have Julia installed, download and install it on your computer and ensure it’s in your PATH.

Then on the shell:

> phy.fullduplex = true
true
> container.add 'phy2', new MyJuliaPhy()
phy2
> subscribe phy2

We turn on fullduplex so that we can transmit and receive on the same device. We subscribe to the phy2 agent’s topic so that we see the RxFrameNtf when data is received.

TIP

Writing agents in Groovy in the classes folder of UnetStack is often convenient since Groovy can load the class directly from source, without needing explicit compilation. However, if there are errors in the code, Groovy’s classloader sometimes gives a cryptic “BUG! exception in phase 'semantic analysis' in source unit” error message. If you encounter this, use groovyc to get a clearer error report:

$ groovyc -cp lib/unet-framework-3.2.0.jar:lib/fjage-1.8.0.jar:lib/unet-yoda-3.2.0.jar:jars/jajub-0.1.0.jar classes/MyJuliaPhy.groovy

and remember to delete off the resultant MyJuliaPhy.class file to avoid a stale class file being used later accidentally.

To test the agent, we make a transmission:

> phy2 << new TxFrameReq(data: [1,2,3])
AGREE
phy2 >> TxFrameNtf:INFORM[txTime:19013099]
phy2 >> RxFrameNtf:INFORM[type:CONTROL from:1 rxTime:19039936 rssi:-49.1 (3 bytes)]

You should have been able to hear the transmission on your speaker. After a short delay, you’d see the reception (RxFrameNtf). We check the contents to ensure that we got the correct data back:

> ntf.data
[1, 2, 3]

If the frame had any errors, you’d have gotten a BadFrameNtf. In that case, you may want to try adjusting your computer’s volume setting or transmit power (plvl command), and try again.

Now that we can transmit and receive correctly, we can enable the rest of the network stack to use our new Julia PHY:

> uwlink.phy = 'phy2'
phy2
> mac.phy = 'phy2'
phy2
> ranging.phy = 'phy2'
phy2

We can send a text message via UnetStack’s remote agent:

> tell 0, 'hi'
AGREE
phy2 >> RxFrameNtf:INFORM[type:DATA from:1 protocol:3 rxTime:96861353 rssi:-48.7 (3 bytes)]
[1]: hi

This resulting datagram goes down the layers of the stack, passed through our new PHY to yield an acoustic signal, gets received by the PHY again to be converted to a datagram, which then goes back up the stack all the way to the remote agent who sends it to the shell for display!

TIP

With Unet audio, Julia calls from Java work seamlessly. However, if you’re running on a real modem, chances are that the modem’s JVM sandbox won’t let you install and run non-JVM code directly. If you have a coprocessor on your modem, you can install Julia on the coprocessor and run the phy2 agent in a fjåge slave container. Alternatively you can run the phy2 agent even on your laptop, as long as the laptop is connected over Ethernet to thr modem. To start a slave container, just install Unet audio on the coprocessor/laptop, and start Unet with bin/unet sh <ipaddr> 1100 where <ipaddr> is replaced by the IP address of your modem, and port 1100 is the API port set on the modem.

Conclusion

Developing complex algorithms in Julia is much easier than in Java or Groovy. By leveraging Julia from UnetStack agents, we bring the power of Julia to UnetStack. The custom Julia-based PHY implementation developed in this article demonstrates how easy it is to combine Groovy and Julia code seamlessly.

I am excited about developing cool new agents in UnetStack using Julia, and I hope you are too!

Developing your own acoustic PHY with UnetStack

Sat, 31 Oct 2020 00:00:00 +0000

UnetStack enables software-defined open architecture modems (SDOAMs). While such modems come with one or more implementations of physical layers (PHY) for your use, there are times when you may wish to develop your own PHY. Perhaps it is because you have a special environment that demands a unique PHY, or because you want to interoperate with another modem. Or maybe you just want to try your hands at implementing communication techniques. Whatever the reason, I have often been asked for advice on how to go about writing a custom PHY. In this article, I will walk you through the process of implementing a simple PHY from scratch.

Background

In an acoustic communication system, the PHY is responsible for converting data bits into an acoustic signal to be transmitted through the channel, and the received signal back into data bits. In UnetStack based modems, this functionality is usually provided by the phy agent. The phy agent implements the PHYSICAL service, and other agents such as uwlink, mac and ranging use this service to provide communication and navigation services to the user (and to others agents in the network stack).

At this point, it may be useful to fire up a Unet audio instance, or connect to a UnetStack powered modem if you’ve one handy.

$ bin/unet -c audio
Modem web: http://localhost:8080/
> ps
node: org.arl.unet.nodeinfo.NodeInfo - IDLE
phy: org.arl.yoda.Physical - IDLE
ranging: org.arl.unet.localization.Ranging - IDLE
uwlink: org.arl.unet.link.ReliableLink - IDLE
  ⋮

We see the phy agent among all the agents running on the modem. The Unet audio community edition, as well as most UnetStack based underwater modems (e.g. Subnero M25M series modems), use Yoda PHY (org.arl.yoda.Physical) as the default PHY. The Yoda PHY not only provides the PHYSICAL service, but also the BASEBAND service and a signal detection capability that we’ll be using shortly.

Just typing phy on the shell tells us more about the active PHY:

> phy
« Physical layer »

Provides software-defined physical layer communication services (including error detection & correction).

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

[org.arl.unet.bb.BasebandParam]
  basebandRate ⤇ 12000.0
  carrierFrequency = 12000.0
  maxPreambleID ⤇ 4
  maxSignalLength ⤇ 2147483647
  signalPowerLevel = -42.0

[org.arl.unet.phy.PhysicalParam]
  busy ⤇ false
  maxPowerLevel ⤇ 0.0
  minPowerLevel ⤇ -138.0
  propagationSpeed = 1500.0
  refPowerLevel ⤇ 0.0
  rxEnable = true
  rxSensitivity ⤇ 0.0
  time = 20157105
  timestampedTxDelay = 1.0

[org.arl.yoda.ModemParam]
  adcrate ⤇ 48000.0
  dacrate ⤇ 96000.0
  downconvRatio = 4.0
  fullduplex = false
  upconvRatio ⤇ 8.0
    ⋮

There are a lot more parameters, but I’ve only reproduced the ones that might interest us here.

If we check the uwlink, mac and ranging agents, we’ll see that they are using this phy agent as their PHY:

> uwlink.phy
phy
> mac.phy
phy
> ranging.phy
phy
>

Our aim is to write our own custom PHY agent (we’ll call it phy2), load it on the modem, and then ask uwlink, mac and ranging to use it instead!

Our phy2 will use the BASEBAND service provided by Yoda PHY (phy) to transmit and record acoustic signals. We will also use phy to sense the acoustic channel, accurately timestamp transmissions and receptions, and continuously monitor the acoustic channel for incoming signals. However, we will implement our own frame format and modulation scheme in phy2.

We’ll be writing our phy2 agent here in Groovy, but you could choose to write yours in Java if you wish. While our example here will be 100% pure Groovy for illustration, you may prefer to develop complex signal processing components in Julia or C (invoked via JNI) if you need higher performance or access to GPUs.

Modulation and demodulation

The core component of a PHY implementation is the modulator and demodulator. The modulator converts a sequence of bits into an acoustic signal for transmission through the channel. The demodulator converts a received acoustic signal (noisy distorted version of the transmitted signal) back into the sequence of bits. In UnetStack, the acoustic signals are represented as sampled complex baseband signals. The basebandRate and carrierFrequency of the signal were shown when you looked up the parameters of phy earlier. For Unet audio, these are 12 kSa/s and 12 kHz respectively (but they may be different on other modems).

The focus of this article is to understand how the PHY agent is developed, and so we won’t spend much time on the signal processing. For the purposes of illustration, we will develop a simple low-rate uncoded binary frequency-shift keying (BFSK) scheme. In reality, you’d probably want to use a more performant communication technique, and also include forward error correction coding (FEC).

For the simple BFSK scheme, we’ll use 150 baseband samples for each bit (symbol). We’ll use frequency f0 to represent a bit 0, and f1 to represent a bit 1:

f0 = carrierFrequency + 1/15 × basebandRate
f1 = carrierFrequency - 1/15 × basebandRate

For Unet audio, this will translate to f0 and f1 being 12.8 kHz and 11.2 kHz respectively, and a signaling rate of 80 bps.

The modulator function bytes2signal() takes in a byte array and converts it into a float array representing the baseband acoustic signal. Alternate entries in the float array are real and imaginary parts of each sample. The implementation is fairly straightforward:

private final int SAMPLES_PER_SYMBOL = 150
private final float NFREQ = 1/15

private float[] bytes2signal(byte[] buf) {
  float[] signal = new float[buf.length * 8 * SAMPLES_PER_SYMBOL * 2]   // 8 bits/byte, 2 floats/sample
  int p = 0
  for (int i = 0; i < buf.length; i++) {
    for (int j = 0; j < 8; j++) {
      int bit = (buf[i] >> j) & 0x01
      float f = bit == 1 ? -NFREQ : NFREQ
      for (int k = 0; k < SAMPLES_PER_SYMBOL; k++) {
        signal[p++] = (float)Math.cos(2 * Math.PI * f * k)
        signal[p++] = (float)Math.sin(2 * Math.PI * f * k)
      }
    }
  }
  return signal
}

The demodulator function signal2bytes() takes in a float array with the received baseband acoustic signal and returns a byte array containing the decoded bits. Bit decisions are taken by running two matched filters for f0 and f1 frequencies, and comparing the output:

private byte[] signal2bytes(float[] signal, int start) {
  int n = (int)(signal.length / (2 * SAMPLES_PER_SYMBOL * 8))       // number of bytes
  def buf = new byte[n]
  int p = start
  for (int i = 0; i < buf.length; i++) {
    for (int j = 0; j < 8; j++) {
      double s0re = 0                 // real path of matched filter for f0
      double s0im = 0                 // imaginary path of matched filter for f0
      double s1re = 0                 // real path of matched filter for f1
      double s1im = 0                 // imaginary path of matched filter for f1
      for (int k = 0; k < SAMPLES_PER_SYMBOL; k++) {
        float re = signal[p++]
        float im = signal[p++]
        float rclk = (float)Math.cos(2 * Math.PI * NFREQ * k)
        float iclk = (float)Math.sin(2 * Math.PI * NFREQ * k)
        s0re += re*rclk + im*iclk
        s0im += im*rclk - re*iclk
        s1re += re*rclk - im*iclk
        s1im += im*rclk + re*iclk
      }
      if (abs2(s1re, s1im) > abs2(s0re, s0im))
        buf[i] = (byte)(buf[i] | (0x01 << j))
    }
  }
  return buf
}

private double abs2(double re, double im) {
  return re*re + im*im
}

The second argument start tells the function where in the signal array to start demodulating. This is required because the recorded signal that we will receive from phy contains an additional detection preamble that we’ll need to skip over.

Writing the agent

Now that we have our modulator and demodulator functions, we are ready to put together our phy2 agent (we call the agent class MyPhy). If you’re not familar with developing agents, now would be a good time to familiarize yourself with the key concepts.

Any PHY agent needs to implement the PHYSICAL service and the DATAGRAM service. We’ll limit ourselves to the basic functionality and honor the TxFrameReq (subclass of DatagramReq), TxRawFrameReq and ClearReq requests. We’ll generate RxFrameNtf (subcalss of DatagramNtf) and BadFrameNtf notifications. The other TxFrameStartNtf, RxFrameStartNtf and CollisionNtf are generated by the Yoda PHY automatically, and we do not need to generate those. We will also need to implement all the parameters in both services.

Let’s start by registering the services we provide, as well as the parameters we support:

void setup() {
  register Services.DATAGRAM
  register Services.PHYSICAL
}

protected List<Parameter> getParameterList() {
  return allOf(DatagramParam, PhysicalParam)
}

protected List<Parameter> getParameterList(int ndx) {
  if (ndx == Physical.CONTROL || ndx == Physical.DATA)
    return allOf(DatagramParam, PhysicalChannelParam)
  return null
}

When we transmit data, we need to add a header to indicate the source node address, destination node address, data length and protocol number. Additionally, we also include a parity byte for error detection (in practice you may want to use a CRC, but we stick to parity byte for simplicity). We define the header:

private final int HDRSIZE = 5           // bytes

private PDU header = new PDU() {
  void format() {
    length(HDRSIZE)
    uint8('parity')
    uint8('protocol')
    uint8('from')
    uint8('to')
    uint8('len')
  }
}

We fix the number of user data bytes in a frame (MTU and RTU). These are DATAGRAM service parameters, and we mark them as read-only through the use the final modifier:

final int MTU = 8
final int RTU = MTU

We’ll be needing the Yoda PHY (phy) agent often, so we save a reference to it in an attribute bbsp (baseband service provider). We subscribe to notifications from Yoda PHY, and also configure it to provide us acoustic signals when it detects a frame:

private final AgentID bbsp = agent('phy')       // Yoda PHY

void startup() {
  subscribe bbsp
  int nsamples = (MTU + HDRSIZE) * 8 * SAMPLES_PER_SYMBOL
  set(bbsp, Physical.CONTROL, ModemChannelParam.modulation, 'none')
  set(bbsp, Physical.CONTROL, ModemChannelParam.basebandExtra, nsamples)
  set(bbsp, Physical.CONTROL, ModemChannelParam.basebandRx, true)
  set(bbsp, Physical.DATA, ModemChannelParam.modulation, 'none')
  set(bbsp, Physical.DATA, ModemChannelParam.basebandExtra, nsamples)
  set(bbsp, Physical.DATA, ModemChannelParam.basebandRx, true)
}

By setting the modulation parameters for both CONTROL and DATA channels to 'none', we have instructed Yoda not to process the received frames. By setting basebandRx parameter to true, we have asked Yoda PHY to send us the baseband signal each time a CONTROL or DATA frame is detected. The basebandExtra parameter is set to the number of samples in our frame, so that Yoda PHY knows how long a signal to record for us.

Yoda PHY detects acoustic signals in the channel by detecting unique preamble signals transmitted just before CONTROL and DATA frames. These signals are included in the recordings and therefore our modulated signal starts a few samples into the signal buffer. To find out exactly how long the preamble signals are (can be configured using Yoda PHY parameters), we ask Yoda PHY for a copy of the preamble and extract the length:

private int getPreambleLength(int ndx) {      // ndx is Physical.CONTROL or Physical.DATA
  int prelen = 0
  def pre = request(new GetPreambleSignalReq(recipient: bbsp, preamble: ndx), 1000)
  if (pre instanceof BasebandSignal) prelen = ((BasebandSignal)pre).signalLength
  return prelen
}

Next, we implement all the PHYSICAL service parameters by delegating them to Yoda PHY:

// Physical service parameters (read-only) delegated to Yoda PHY
Float getRefPowerLevel()    { return (Float)get(bbsp, PhysicalParam.refPowerLevel) }
Float getMaxPowerLevel()    { return (Float)get(bbsp, PhysicalParam.maxPowerLevel) }
Float getMinPowerLevel()    { return (Float)get(bbsp, PhysicalParam.minPowerLevel) }
Float getRxSensitivity()    { return (Float)get(bbsp, PhysicalParam.rxSensitivity) }
Float getPropagationSpeed() { return (Float)get(bbsp, PhysicalParam.propagationSpeed) }
Long getTime()              { return (Long)get(bbsp, PhysicalParam.time) }
Boolean getBusy()           { return (Boolean)get(bbsp, PhysicalParam.busy) }
Boolean getRxEnable()       { return (Boolean)get(bbsp, PhysicalParam.rxEnable) }

We also implement the PHYSICAL service indexed parameters:

// Physical service indexed parameter (read-only)
int getMTU(int ndx)               { return MTU }
int getRTU(int ndx)               { return RTU }
int getFrameLength(int ndx)       { return MTU + HDRSIZE }
int getMaxFrameLength(int ndx)    { return MTU + HDRSIZE }
int getFec(int ndx)               { return 0 }        // no FEC
List<String> getFecList(int ndx)  { return [] }       // FEC not supported
int getErrorDetection(int ndx)    { return 8 }        // 8 bits
boolean getLlr(int ndx)           { return false }    // LLR not supported

// Physical service indexed dynamic parameters

void setPowerLevel(int ndx, float lvl) {
  if (ndx != Physical.CONTROL && ndx != Physical.DATA) return
  set(bbsp, BasebandParam.signalPowerLevel, lvl)
}

Float getPowerLevel(int ndx) {
  if (ndx != Physical.CONTROL && ndx != Physical.DATA) return null
  return (Float)get(bbsp, BasebandParam.signalPowerLevel)
}

Float getFrameDuration(int ndx) {
  if (ndx != Physical.CONTROL && ndx != Physical.DATA) return null
  def bbrate = (Float)get(bbsp, BasebandParam.basebandRate)
  if (bbrate == null) return 0f
  int prelen = getPreambleLength(ndx)
  return (float)((prelen + (MTU + HDRSIZE) * 8 * SAMPLES_PER_SYMBOL) / bbrate)
}

Float getDataRate(int ndx) {
  if (ndx != Physical.CONTROL && ndx != Physical.DATA) return null
  return (float)(8 * getFrameLength(ndx) / getFrameDuration(ndx))
}

The powerLevel parameter is delegated to Yoda PHY signalPowerLevel since we will ask Yoda PHY to transmit signals for us.

We often require our node address. Rather than ask the node agent each time, we use the UnetStack utility to request and cache the node address:

private NodeAddressCache addrCache = new NodeAddressCache(this, true)

We also need to keep a temporarily store pending transmission requests, so that when Yoda PHY informs us that the transmission is complete, we can inform our client (agent who sent us the transmission request) that the transmission was completed:

private Map<String,Message> pending = [:]

To process various requests, we override the processRequest() method:

Message processRequest(Message req) {
  if (req instanceof DatagramReq) return processDatagramReq(req)
  if (req instanceof TxRawFrameReq) return processTxRawFrameReq(req)
  if (req instanceof ClearReq) {
    send new ClearReq(recipient: bbsp)
    pending.clear()
    return new Message(req, Performative.AGREE)
  }
}

We don’t need an if condition for TxFrameReq, as it is a subclass of DatagramReq and therefore processDatagramReq() will be called when a TxFrameReq is received.

The processTxRawFrameReq() simply delegates the transmission to transmit():

private Message processTxRawFrameReq(TxRawFrameReq req) {
  if (transmit(req.type, req.data, req)) return new Message(req, Performative.AGREE)
  return new Message(req, Performative.FAILURE)
}

The processDatagramReq() also delegates transmission to transmit() after composing a data frame (PDU) with the required header prepended:

private Message processDatagramReq(DatagramReq req) {
  def from = addrCache.address
  byte[] buf = composePDU(from, req.to, req.protocol, req.data)
  int ch = req instanceof TxFrameReq ? req.type : Physical.DATA     // default to DATA if DatagramReq
  if (transmit(ch, buf, req)) return new Message(req, Performative.AGREE)
  return new Message(req, Performative.FAILURE)
}

private byte[] composePDU(int from, int to, int protocol, byte[] data) {
  if (data == null) data = new byte[0]
  def hdr = header.encode([
    parity: 0, from: from, to: to, protocol: protocol, len: data.length
  ] as Map<String,Object>)
  def buf = new byte[HDRSIZE + MTU]
  System.arraycopy(hdr, 0, buf, 0, HDRSIZE)
  System.arraycopy(data, 0, buf, HDRSIZE, data.length)
  int parity = 0
  for (int i = 1; i < buf.length; i++)
    parity ^= buf[i]    // compute parity bits
  buf[0] = (byte)parity
  return buf
}

The transmit() method simply converts the buffer into a signal and makes a TxBasebandSignalReq request to Yoda PHY to do the transmission. It adds the transmission request to the temporary store so that a notification can be sent to the requester when the transmission is completed.

private boolean transmit(int ch, byte[] buf, Message req) {
  def signal = bytes2signal(buf)
  def bbreq = new TxBasebandSignalReq(recipient: bbsp, preamble: ch, signal: signal)
  def rsp = request(bbreq, 1000)
  if (rsp?.performative != Performative.AGREE) return false
  pending.put(bbreq.messageID, req)
  return true
}

Incoming transmit notifications and signal receptions are processed by overriding the processMessage() method:

void processMessage(Message msg) {
  addrCache.update(msg)
  if (msg instanceof TxFrameNtf) handleTxFrameNtf(msg)
  else if (msg instanceof RxBasebandSignalNtf) handleRxBasebandSignalNtf(msg)
}

The addrCache.update() call ensures that any node address changes are update to the address cache.

When a transmission is completed by Yoda PHY, it sends us a TxFrameNtf. We in turn send a TxFrameNtf to our client:

private void handleTxFrameNtf(TxFrameNtf msg) {
  def req = pending.remove(msg.inReplyTo)
  if (req == null) return
  def ntf = new TxFrameNtf(req)
  ntf.type = msg.type
  ntf.txTime = msg.txTime
  ntf.location = msg.location
  send ntf
}

When a baseband signal is received from Yoda PHY, we process it and convert it to bits. If the parity bits suggest that the frame is error-free, we send a RxFrameNtf for the received frame. In case of errors, we send a BadFrameNtf instead. The RxFrameNtf is published on the agent’s default topic if the frame is a BROADCAST or intended for our node address. Otherwise it is published on the agent’s SNOOP topic.

private void handleRxBasebandSignalNtf(RxBasebandSignalNtf msg) {
  def buf = signal2bytes(msg.signal, 2 * getPreambleLength(msg.preamble))
  int parity = 0
  for (int i = 1; i < buf.length; i++)
    parity ^= buf[i]        // compute parity bits
  if (buf.length >= HDRSIZE && buf[0] == parity) {
    def hdr = header.decode(buf[0..HDRSIZE-1] as byte[])
    int len = (int)hdr.len
    def rcpt = topic()
    if (hdr.to != Address.BROADCAST && hdr.to != addrCache.address)
      rcpt = topic(agentID, Physical.SNOOP)
    byte[] data = null
    if (len > 0) {
      data = new byte[len]
      System.arraycopy(buf, HDRSIZE, data, 0, len)
    }
    send new RxFrameNtf(
      recipient: rcpt, type: msg.preamble, rxTime: msg.rxTime, location: msg.location,
      rssi: msg.rssi, from: (int)hdr.from, to: (int)hdr.to, protocol: (int)hdr.protocol, data: data
    )
  } else {
    send new BadFrameNtf(
      recipient: topic(), type: msg.preamble, rxTime: msg.rxTime, location: msg.location,
      rssi: msg.rssi, data: buf
    )
  }
}

That’s it!

The complete implementation (with a few additional error checks) is available from the unet-contrib repository.

Testing our custom PHY

Now that we’ve implemented phy2 agent, it is time to try it out on Unet audio or your modem. Copy the MyPhy.groovy file to the classes folder in Unet audio or the modem. Then on the shell:

> phy.fullduplex = true
true
> container.add 'phy2', new MyPhy()
phy2
> subscribe phy2

We turn on fullduplex so that we can transmit and receive on the same device. We subscribe to the phy2 agent’s topic so that we see the RxFrameNtf when data is received.

TIP

Writing agents in Groovy in the classes folder of UnetStack is often convenient since Groovy can load the class directly from source, without needing explicit compilation. However, if there are errors in the code, Groovy’s classloader sometimes gives a cryptic “BUG! exception in phase 'semantic analysis' in source unit” error message. If you encounter this, use groovyc to get a clearer error report:

$ groovyc -cp lib/unet-framework-3.2.0.jar:lib/fjage-1.8.0.jar:lib/unet-yoda-3.2.0.jar classes/MyPhy.groovy

and remember to delete off the resultant MyPhy.class file to avoid a stale class file being used later accidentally.

To test the agent, we make a transmission:

> phy2 << new TxFrameReq(data: [1,2,3])
AGREE
phy2 >> TxFrameNtf:INFORM[txTime:19013099]
phy2 >> RxFrameNtf:INFORM[type:CONTROL from:1 rxTime:19039936 rssi:-49.1 (3 bytes)]

If you are using Unet audio, you should have been able to hear the transmission on your speaker. After a short delay, you’d see the reception (RxFrameNtf). We can check the contents to ensure that we got the correct data back:

> ntf.data
[1, 2, 3]

If the frame had any errors, you’d have gotten a BadFrameNtf. In that case, you may want to try adjusting your computer’s volume setting (for Unet audio) or transmit power (plvl command on Unet audio or modem), and try again.

Now that we can transmit and receive correctly, we can enable the rest of the network stack to use our new PHY:

> uwlink.phy = 'phy2'
phy2
> mac.phy = 'phy2'
phy2
> ranging.phy = 'phy2'
phy2

We can send a text message via UnetStack’s remote agent:

> tell 0, 'hi'
AGREE
phy2 >> RxFrameNtf:INFORM[type:DATA from:1 protocol:3 rxTime:96861353 rssi:-48.7 (3 bytes)]
[1]: hi

Conclusion

In this article, we have seen how to write a simple custom PHY agent. We intentionally kept the implementation simple by using an uncoded BFSK communication scheme, as the focus of this article was to illustrate how to implement a custom PHY.

In a practical system, you may wish to replace the communication scheme (bytes2signal() and signal2bytes() methods) with something more sophisticated, including FEC coding. You may also want to use a stronger error detection scheme (CRC rather than parity bits). You’d perhaps also want to consider supporting variable MTU and some of the optional features of the PHYSICAL service (e.g. timed transmission, timestamping, etc).

If you find that Java or Groovy doesn’t meet your signal processing needs, you may consider writing the bytes2signal() and signal2bytes() methods in C (using JNI) or in Julia (my preferred choice!).

TIP

With Unet audio, C or Julia calls from Java work seamlessly. However, if you’re running on a real modem, chances are that the modem’s JVM sandbox won’t let you run non-JVM code directly. If you have a coprocessor on your modem, you can run the phy2 agent on the coprocessor in a fjåge slave container, and you will have no JVM sandbox restrictions. Alternatively you can run the phy2 agent even on your laptop, as long as the laptop is connected over Ethernet to thr modem. To start a slave container, just install Unet audio on the coprocessor/laptop, and start Unet with bin/unet sh <ipaddr> 1100 where <ipaddr> is replaced by the IP address of your modem, and port 1100 is the API port set on the modem.

Unet

Turning a Multi-Receiver Modem into a USBL Transceiver

USBL Basics

Installing the Dependencies

Setting Up the Multi-Receiver Modem

Launching the USBL Script

USBL UI

How Does This Work?

Estimating the Range

Estimating the Bearing

Estimating the Arrival Times

Appendix: Setting Up a VirtualAcousticOcean Test Environment

Acoustic Communication and Navigation for Subsea Robotics — Part 2

Level 4: Adaptive communication links

Level 5: Adaptive command and control

Putting it all together

Acoustic Communication and Navigation for Subsea Robotics — Part 1

The Basics

Why Acoustics?

Acoustic communication

Acoustic navigation

Why doesn’t it “just work”?

The five levels of confidence

Level 1: Technology choices

Level 2: Integration hygiene

Level 3: Deployment planning

Running Hardware-in-the-Loop Simulations Using UnetStack Modems

Why Hardware-in-the-Loop (HIL)?

The Foundation: UnetStack v5 + Virtual Acoustic Ocean

Typical Use Cases

Step-by-Step Guide to HIL Simulation

1. Install VAO and Packages

2. Add Example Scenario

3. Configure Subnero Modems

4. Set Transmit Power

5. Test the Link

UnetCube (UnetStack OEM Edition) + VAO

Additional Resources

Running Unet audio on Apple silicon

Setup Unet audio on Macs with Apple Silicon

Pre-requisites

Running Unet audio

Accepting Security Permissions on macOS for running Unet audio

A Step-by-Step Guide to Deploying and Operating an Acoustic Modem running UnetStack to Achieve the Best Performance

The ping & tell commands

File transfer using fput

Speedtest

Tuning the link

Link Tuner

Communication Profiles

Basic Troubleshooting

1. The landing dashboard is not loading

2. ping is not working

3. tell is not working (ping is working)

Low-cost DIY underwater modem using COTS components and Unet audio

Introduction

Motivation and Approach

Overview of the DIY modem

Transmit chain

Receive chain

Hardware Selection

Digital Hardware

Transmit Chain

Receive Chain

Waterproofing

Bill of materials

Software installation

Requirements

Setup

OS

Audio

Dependencies

Run UnetStack

Taking it for a spin

Synchronizing physical clocks among different UnetStack-based modems

Compensating for clock offset

Compensating for clock drift

An example of calibrating clock

Calibrating clock without relying on RTC

Scheduling transmissions intelligently in UnetStack enabled modems

The `ping` & `tell` commands

File transfer using `fput`

2. `ping` is not working

3. `tell` is not working (`ping` is working)