14  Node information

org.arl.unet.Services.NODE_INFO

14.1 Overview

The NODE_INFO service provides a single place to collate node-related information that is commonly needed by many agents — the node’s name and address, its location and motion, its clock, and the properties of the water around it. It is a special service, in the sense that each node must be configured to have one and only one agent providing this service.

Agents and applications consume this service by reading (and occasionally setting) its parameters: a link agent needs the node address to fill in datagram headers, ranging (Chapter 25) needs location and soundSpeed, and so on. An agent that needs to react to a change — a new address, an updated position — subscribes to the provider’s topic and watches for ParamChangeNtf messages, rather than polling.

14.2 Messages

The NODE_INFO service defines no messages of its own. All interaction is through the standard parameter messages that every agent supports (Chapter 13): parameters are read and set with a ParameterReq, answered by a ParameterRsp.

An agent providing this service is expected to publish a ParamChangeNtf on its own topic whenever one of its parameters changes, so that other agents can monitor important node attributes simply by subscribing to the provider’s topic. Most agents publish parameter changes on the global PARAMCHANGE topic; the NODE_INFO provider deliberately redirects them to its own topic instead, since changes to attributes such as address or location are of interest to many agents.

14.3 Parameters

An agent providing the NODE_INFO service exposes the following parameters:

• address :: int (nullable) – Node address

  Nodes are identified by a unique address that is typically 8-bit long (1 - 255). They can also configure use a 16-bit address depending on the node.addressSize setting.

  Examples:

  node.address              // check node address
  node.address = 5          // change node address
  

• addressSize :: int – address size in bits (valid values are 8 or 16)

• nodeName :: String (nullable) – Node name

• origin :: double[] – origin [lat,long]

• location :: double[] – Location of the node in [x,y,z] meters or [lat,long,z]

• locationAccuracy :: float[] (nullable) – location accuracy [x,y,z] m

• speed :: double (nullable) – speed (meter/second)

• yaw :: double (nullable) – yaw (deg, 0 is East, anticlockwise)

• yawRate :: double (nullable) – yaw rate (deg/s, anticlockwise)

• diveRate :: double (nullable) – dive rate (meter/second)

• roll :: double (nullable) – roll angle (deg, positive rolling starboard)

• pitch :: double (nullable) – pitch angle (deg, positive nose down)

• salinity :: double – water salinity (ppt)

• waterTemperature :: double – water temperature (deg C)

• depth :: double – depth (meters)

• soundSpeed :: double – sound speed in water (m/s), 0 for auto-compute

• mobility :: boolean – true if the node is mobile, false if it is fixed

• time :: Date – node time (real-time clock)

• isSynchronized :: boolean – true if synchronized with network

• networkTime :: long (optional) – network time (ms)

• networkTimeAccuracy :: long (optional) – network time accuracy (ms)

• timeStability :: float (nullable) – node time stability (ppm)

• canForward :: boolean – true if node has forwarding capability, false otherwise

• ready :: boolean – true if the node is fully booted up, false otherwise

Most of these are self-explanatory, but a few groups deserve elaboration:

• Identity. Nodes are identified by an address drawn from an address space whose size is set by addressSize (8 or 16 bits). Names and addresses are coupled: a purely numeric nodeName that fits the address space sets the address directly, and a node without a name takes its address as its name. Address allocation at startup is delegated to the ADDRESS_RESOLUTION service (Chapter 15).
• Position. origin, location and depth work together, and are described in the next section.
• Motion & attitude. When mobility is true, the node is treated as mobile, and the provider estimates location between explicit updates by dead reckoning from speed, yaw, yawRate and diveRate; when mobility is false, these motion parameters read as null. The attitude conventions are: yaw in degrees with 0 pointing East, increasing anticlockwise; pitch positive nose-down; roll positive rolling starboard.
• Environment. Leaving soundSpeed at 0 (its automatic setting) causes it to be computed from waterTemperature, salinity and depth, so that ranging and other agents have a sound speed estimate even when none is measured.
• Clocks. time is the node’s real-time clock. On hardware that supports network time synchronization, networkTime, networkTimeAccuracy and isSynchronized report the synchronized network clock, and timeStability the clock stability in ppm.

Note

If node mobility is enabled, the provider automatically updates location based on the motion parameters (speed, yaw, yawRate, diveRate). Location updates are not published as ParamChangeNtf for such implicit changes — only explicitly set parameters generate notifications.

14.4 Node locations & coordinate systems

A node’s position is described by two parameters that work together: origin, a geographic reference point [latitude, longitude] in degrees, and location, the node’s position as a 3-tuple. Depending on the application, you may wish to work in different coordinate systems. There are four options to choose from, selected purely by the values given to these two parameters:

• No coordinates. We do not know or care about node locations. Both parameters are left empty: origin = [] and location = [].
• Local coordinates. Only the relative positions of nodes matter. Setting origin = [NaN, NaN] declares a local coordinate frame without anchoring it geographically. location = [x, y, z] is then a 3-tuple in meters; the x and y axes are arbitrarily chosen, and the z axis points upwards — the sea surface is 0 m, so an underwater node has a negative z.
• Georeferenced local coordinates. As above, but the local frame is anchored geographically: origin = [latitude, longitude] gives the geographic location of the frame’s origin, commonly agreed across the network. location = [x, y, z] is again in meters, but the axes are no longer arbitrary — x points east, y points north, and z up. This is a local east-north-up (ENU) frame centered at origin.
• GPS coordinates. Each node’s geographic position is given directly, without defining a local frame. origin is left empty ([]), and location = [latitude, longitude, z], with z still in meters, pointing up.

Note carefully what “set” means here: an empty origin ([]) means there is no local frame, so a non-empty location is interpreted as geographic coordinates. An origin of [NaN, NaN] is not the same as an empty one — it does establish a local frame, merely one whose geographic anchor is unspecified, so location is interpreted as local coordinates in meters.

Local frames are preferred wherever one can be agreed on for the whole network: geometry, ranging (Chapter 25) and localization are naturally computed in meters. Georeferencing the frame additionally lets positions be related back to latitude/longitude for deployment planning and plotting. GPS coordinates are used when node location matters but a local frame cannot easily be agreed on (e.g., an ad hoc network with no prior knowledge of the area of operation). The stack does not convert between frames — location is stored and reported exactly as you set it, and origin simply declares which frame it is in and where that frame is anchored. When conversion is needed, the org.arl.unet.utils.GpsLocalFrame utility class translates between local ENU meters and geographic coordinates.

The separate depth parameter is the depth below the water surface in meters (positive downwards), and is kept consistent with the z coordinate of location: location[2] == -depth always holds when both are set.

Note

The simulator requires a local frame, so simulated nodes use local or georeferenced local coordinates: node locations in simulation scripts (Chapter 34) are given in meters, and origin defaults to [NaN, NaN].

14.5 Examples

If you start a simulation, connect to a node’s shell and type node, you’ll see the NODE_INFO parameters for that node:

> node
« Node information »

Manages and maintains node information and attributes.

[org.arl.unet.nodeinfo.NodeInfoParam]
  address = 232
  addressSize = 8
  canForward ⤇ true
  depth = 15
  diveRate = null
  isSynchronized ⤇ false
  location = [0.0, 0.0, -15.0]
  locationAccuracy = null
  mobility = false
  nodeName = A
  origin = [NaN, NaN]
  pitch = 0
  ready ⤇ true
  roll = 0
  salinity = 35
  soundSpeed = 1539.168121822446
  speed = null
  time ⤇ Wed Jul 08 22:57:39 SGT 2026
  timeStability = null
  waterTemperature = 27
  yaw = 0
  yawRate = null

Set a geographic reference point, then work in georeferenced local coordinates. Note how the depth parameter tracks the z coordinate of the location, and how GpsLocalFrame converts between local ENU meters and geographic coordinates:

> node.origin = [1.3, 103.8];        // geographic reference point [lat, long]
> node.location = [100, 200, -10];   // ENU meters relative to origin
> node.location
[100.0, 200.0, -10.0]
> node.depth
10
> gps = new org.arl.unet.utils.GpsLocalFrame(node.origin);
> gps.toGps(node.location[0..1])     // local ENU meters to [lat, long]
[1.3018087296571046, 103.80089854527836]
> gps.toLocal(1.301809, 103.800899)  // [lat, long] to local ENU meters
[100.050606424862, 200.02989312354663]

Tip

GpsLocalFrame also accepts GPS coordinates in degrees and decimal minutes, or degrees, minutes and decimal seconds — both the constructors and the toGps()/toLocal() methods have overloads for these formats, matching how coordinates are usually read off a GPS receiver or a chart.

14.6 Implementation

14.6.1 NodeInfo (node)

Class	Services	Capabilities	Availability
NodeInfo	NODE_INFO	—	default stack

The default — and, since a node must have exactly one NODE_INFO provider, the only — implementation is the node agent, created first when a node boots (Chapter 13).

14.6.1.1 How it works

At startup the agent acquires an address for the node. An explicitly configured address is used as-is; otherwise, if the node has a name, the agent asks the ADDRESS_RESOLUTION service (Chapter 15) to derive an address from it (a purely numeric name that fits the address space is used directly as the address). If the node has no name, the name defaults to the address.

As the service requires, the agent publishes every parameter change as a ParamChangeNtf on its own topic, so that an interested agent can simply subscribe to the NODE_INFO provider rather than poll. Coupled parameters are kept consistent — setting a 3-element location updates depth (and vice versa), and renaming a node to a numeric name updates its address.

For a mobile node (mobility = true), the agent dead-reckons the position between explicit updates: it advances location at speed along the current yaw (following an arc when yawRate is non-zero), and deepens it at diveRate. The estimate is computed whenever location is read, and these implicit updates are deliberately not published.

When soundSpeed is left at its automatic setting (0), the agent computes it from waterTemperature, salinity and depth using an empirical formula. time reports the system clock; the generic implementation does not provide network time synchronization (isSynchronized is always false), though modem implementations with synchronized clocks may.

14.6.1.2 Usage notes

• Set nodeName early; the default ADDRESS_RESOLUTION provider derives the node address from it (Chapter 15).
• For static nodes, leave mobility = false so other agents do not track position needlessly.
• Leave soundSpeed at its automatic setting to have it computed from the water properties, unless you have a measured value.