28  Device information

org.arl.unet.Services.DEVICE_INFO

28.1 Overview

The DEVICE_INFO service provides access to information and parameters about the physical device that hosts UnetStack. This includes static identification (vendor, model, serial number) and dynamic health information, such as a self-test status. Monitoring these is useful for diagnosing problems with deployed nodes that cannot be physically inspected.

The service also provides device-level power management. On supported hardware, a PMMSleepReq puts the device into a low-power sleep mode, optionally configuring it to wake on acoustic or GPIO activity — important for long-endurance battery-powered deployments. Higher-level, time-based sleep/wake scheduling is provided by the SCHEDULER service (Chapter 29). The default device agent is accessed as device.

28.2 Messages

On supported hardware, agents providing this service honor the following request:

• PMMSleepReq – put the device into low-power sleep

  Field	Type	Default	Remarks
  wakeOnAcoustic	boolean	false	wake on acoustic activity
  wakeOnGPIO	boolean	false	wake on GPIO activity

The request is answered with an AGREE before the device sleeps; a REFUSE is generated if power-mode management is not supported on the platform, and a FAILURE if the request fails.

Other than this, all interaction with the service is through the standard parameter messages (ParameterReq/ParameterRsp, Chapter 3).

28.3 Parameters

• vendor :: String – device vendor/make

• model :: String – device model number

• serial :: String – device serial number

• health :: String – self-test error code (‘OK’ = no errors)

  Device health status. A string value of ‘OK’ indicates that the device is working correctly. Any other status indicates a problem, and the status string provides an error code or a human-readable description of the problem.

• time :: long – device time in milliseconds since epoch

• allIPs :: String[] – list of all IP addresses assigned to the device

• storage :: long[] – list of two numbers: [free storage in bytes, total storage in bytes]

Parameters that the hardware does not support read as empty or null. The time parameter is the device’s real-time clock in milliseconds, and is writable on platforms that allow the clock to be set.

28.4 Commands

• free – show free disk space

28.5 Examples

If you start a simulation, connect to a node’s shell and type device, you’ll see the DEVICE_INFO parameters reported by the generic SimpleDevice provider:

> device
« Device management for generic platforms »

Provides hardware access for simulated devices

[org.arl.unet.device.DeviceParam]
  allIPs ⤇ [192.168.1.31]
  health = OK
  model ⤇ A
  serial = 0123-4567-89ab-cdef
  storage ⤇ [2987621859328, 3996329328640]
  time = 1.783523828846E12
  vendor ⤇ UnetStack

You can also query individual parameters, for example to check device health and available storage:

> device.health
OK
> device.storage
[2987621703680, 3996329328640]

28.6 Implementation

Real modems provide their own hardware-specific DEVICE_INFO implementation, exposing the vendor, model and serial number of the device, along with additional hardware-specific parameters such as thermal, voltage and power metrics (on commercial modems, this is part of the firmware’s hardware abstraction layer, which also implements PMMSleepReq-based power management). On simulated (and other non-specialized) platforms, the generic device agent provides the service instead.

Real modems may provide many more parameters than the ones listed above. For more information on them, type help device on the modem.

28.6.1 SimpleDevice (device)

Class	Services	Capabilities	Availability
SimpleDevice	DEVICE_INFO	—	default stack (simulated/generic platforms)

28.6.1.1 How it works

The agent answers device queries using standard Java runtime APIs — system time (settable, emulated with an offset clock), free and total storage, and the non-loopback IPv4 network interfaces (allIPs). Identification parameters (serial, health) are simple writable values, so a simulation can inject test values; model reports the container name. Hardware-specific metrics are not available on a generic platform, and PMMSleepReq is not honored.