32  Utility agents

Not every agent in UnetStack provides a UnetStack service. Some are simply tools and helpers — utilities for switching physical-layer profiles, measuring throughput, capturing baseband signals, logging diagnostic traffic, or squeezing better reception out of several receivers. A few of these (profiles, speedtest, bbmon) are loaded as part of the default stack (Chapter 13); others are loaded only when you need them. This chapter collects those utility agents in one place.

32.1 PHY profile manager — profiles

Services: none (utility agent)

profiles is a convenience utility for switching the physical layer between pre-defined modulation/coding profiles without having to set the individual physical-channel parameters by hand.

32.1.1 How it works

On startup the agent waits for the BASEBAND service and reads the modem’s carrier frequency. It then loads a set of default profiles keyed by that carrier frequency (so the appropriate schemes are offered for the band the modem operates in), and merges in any user-defined profiles from a TOML configuration file. Selecting a profile by index sends a ParameterReq to the physical agent that sets the scheme code of the DATA channel, so the modulation and coding scheme can be changed in a single step rather than by editing several physical-channel parameters.

32.1.2 Parameters

• profile – current profile
• profiles – list of all profiles

32.1.3 Commands

• addprofile – add a profile temporarily

  Examples:

  addprofile                         // add profile with current DATA scheme
  addprofile 'hantu'                 // add named profile
  addprofile 'sji', 'lkm09x8se0THo'  // add named profile with scheme code
  

• saveprofile – add a profile persistently to profiles.toml

  Examples:

  saveprofile              // save profile with current DATA scheme
  saveprofile 'hantu'      // save named profile with current DATA scheme

32.1.4 Usage notes

• Use profiles to switch quickly between, say, a robust low-rate scheme and a fast high-rate scheme as channel conditions change.
• The available profiles depend on the modem’s carrier frequency and on the profile configuration file.

32.2 Throughput measurement — speedtest

Services: none (utility agent)

speedtest measures link throughput between two modems.

32.2.1 How it works

The transmitting node sends tx test frames, each tagged with a sequence number and test metadata, spacing them out according to dutyCycle (the fraction of time spent transmitting) so the test can run alongside other traffic. The receiving node filters for the test frames, counts how many of the expected frames arrive (rx), and computes an estimated throughput from the packet success rate, the configured data rate and the duty cycle. It also maintains nowput, the same estimate over a recent moving window whose length is set by nowDuration, which is useful for watching how throughput varies over time rather than just its average. Both throughput and nowput are estimates derived from the packet success rate; the actual measured data rate is logged only when the agent’s logLevel is set to FINE.

A test is started by sending a SpeedTestReq to the agent — this is what the speedtest command does under the hood:

• SpeedTestReq – start a throughput test

  Field	Type	Default	Remarks
  count	int	0	number of test packets to send
  to	int	-1	destination node address

32.2.2 Parameters

• tx – number of frames to transmit
• rx – number of frames received
• throughput – estimated throughput (bps)
• dutyCycle – duty cycle of the test (0-1, default: 0.5)
• nowput – measured throughput for the moving window (bps)
• nowDuration – duration of the moving window (seconds, default: 10)

32.2.3 Usage notes

• Set tx on the transmitter to the number of frames to send, and read rx, throughput and nowput on the receiver.
• Lower the dutyCycle to leave the channel idle between frames when testing alongside other traffic.

32.3 Baseband signal monitor — bbmon

Services: none (utility agent)

bbmon records the baseband signals received by the node to a log file, for offline analysis.

32.3.1 How it works

The agent subscribes to the baseband signal streams of the BASEBAND providers. When enable is set, each received baseband signal (RxBasebandSignalNtf) is appended to the log file named by file, with the samples base64-encoded and tagged with a timestamp and metadata. The recorded files can be loaded for analysis with the arlpy.unet Python package or the UnetUtils.jl Julia module.

32.3.2 Parameters

• enable – enable logging of baseband signals
• file – baseband signal log filename

32.3.3 Usage notes

• Enable bbmon only when you need signal captures — the log files grow quickly.
• Pair captured signals with the corresponding RxFrameNtf/BadFrameNtf events when diagnosing reception problems.

32.4 UDP logger — UdpLogger

Services: none (logging utility)

A simple diagnostic utility that listens on a UDP port and logs everything sent to it, with timestamps — handy when working with LAN devices.

32.4.1 How it works

On startup the agent opens a UDP socket on the configured port and runs a background thread that receives packets, converts each to a string, stores it in the last parameter and logs it at INFO level.

32.4.2 Parameters

• port – UDP port number to listen on
• last – last message received

32.5 Spatial diversity combiner — Unity

NotePremium feature

The Unity agent is a premium feature (see Section 13.3).

Services: none (signal-processing utility)

Unity improves reception by combining copies of a transmission received at several physically separated receivers — exploiting spatial diversity to decode frames that no single receiver could decode on its own.

32.5.1 How it works

The agent subscribes to a primary physical agent (phy) and a list of assisting receivers’ physical agents (assisters). When a frame is received (or fails to decode) at the primary and at the assisters, it pairs the copies using time-synchronized metadata and feeds the additional copies into a forward-error-correction decoder to recover the frame. It periodically synchronizes the receivers’ clocks so that copies can be matched, and combines copies that fall within a time window derived from maxAssisterRange.

32.5.2 Parameters

• phy – physical agent to provide diversity combining for
• enable – enable distributed spatial diversity combining
• maxAssisterRange – farthest distance to the assisting receiver node
• assisters – list of physical agent names on assisting receivers

32.6 See also

A few other agents are tools or bridges rather than service providers, but are documented elsewhere because they belong with the topics they support:

• Portal and UdpPortal — bridge TCP/serial or UDP byte streams across a Unet; see Chapter 10.
• Wormhole — carries fjåge messages between containers over a Unet link; see Chapter 11.