Hardware Diagnostics Tool — Usage Guide¶

This guide describes how to use the ResIOT Hardware Diagnostics Tool. It explains available options, expected output, and practical use cases.

The resiotinfo utility requires Merlin v268 or higher to report modem metrics!

What It Does¶

resiotinfo collects and prints hardware and system status in JSON format from ResIOT-based gateways. It reports:

Temperature and humidity
Solar MPPT metrics (VBat, IBat, VIn, IIn, battery %) for Solar gateways
Supercapacitor voltage levels for X7 gateways
Modem status (ICCID, operator, RSSI, band, connection status)
System information (CPU, RAM, storage, uptime)
Running ResIOT services
Basic Gateway information

How to Use¶

/opt/resiot/resiotinfo [options]

Available Options¶

Option	Type	Description
`-basic`	bool	Include temperature and humidity readings
`-mppt`	bool	Include mppt solar battery charging stats
`-caps`	bool	Include supercapacitor readings
`-modem`	bool	Include modem and SIM information
`-services`	bool	Include ResIOT service status
`-system`	bool	Include system info (CPU, RAM, disk, uptime)
`-print`	bool	Print JSON output to stdout (default: true)
`-enablelogging`	bool	Save output to a file
`-logpath`	string	File path for log (default: `/var/log/readings`)

Example¶

/opt/resiot/resiotinfo -basic -mppt -modem -system -print

Output Format¶

The tool returns a single JSON object with fields based on selected flags.

Root-Level Fields¶

Field	Type	Description
`version`	string	Software version
`model`	string	Gateway model identifier
`macAddress`	string	ETH MAC address
`hasModem`	bool	Whether device supports modem
`hasSupercaps`	bool	Whether device uses supercapacitors
`hasMppt`	bool	Whether device uses solar MPPT
`basic`	object	See Basic Readings
`mppt`	object	See MPPT Readings
`caps`	object	See Capacitor Readings
`modem`	object	See Modem Readings
`services`	object	See Service Readings
`system`	object	See System Readings

Each sub-object follows this structure:

{
  "result": "success", // or "error"
  "details": "error message if any",
  "missing": true, // if requested hardware is missing
  "readings": { ... } // object described below
}

Subtype Response Structures¶

Basic Readings¶

Collected from temperature/humidity sensor.

/opt/resiot/resiotinfo -basic

{
  "temperature": 24.5,   // °C
  "humidity": 41.2       // %
}

MPPT Readings¶

Data from the solar charge controller.

/opt/resiot/resiotinfo -mppt

Due to ultra low power configuration, enabling telemetry might take up to a minute to retrieve mppt readings

{
  "vbat": 10.2,          // Battery voltage in V
  "ibat": 0.34,          // Battery charging current in A, negative possible
  "vin": 18.7,           // Input voltage from solar panel in V
  "iin": 1.2,            // Input current from solar panel in A, negative possible
  "batteryPerc": 75.8,   // Estimated battery charge %
  "chstate": 2,          // Charger state, see more below
  "chrstatus": 1         // Charge status, see more below
}

-mppt can only be called on Solar gateway models

{
  "missing": true       // If not MPPT onboard
}

Charger State Value List¶

Bit Flag Name	Value
bat_detect_failed_fault	4096
battery_detection	2048
absorb_charge	512
charger_suspended	256
cc_cv_charge	64
ntc_pause	32
timer_term	16
c_over_x_term	8
max_charge_time_fault	4
bat_missing_fault	2
bat_short_fault	1

Charge Status Value List¶

Bit Flag Name	Value
ilim_reg_active	32
thermal_reg_active	16
vin_uvcl_active	8
iin_limit_active	4
constant_current	2
constant_voltage	1
charger_off	0

Capacitor Readings¶

Supercapacitor voltage data.

/opt/resiot/resiotinfo -caps

{
  "vbat": 7,             // Input voltage in V
  "vcap": 990,           // Main capacitor voltage in mV
  "v1cap": 1023,         // Cell 1 voltage in mV
  "v2cap": 1010,         // Cell 2 voltage in mV
  "v3cap": 995,          // Cell 3 voltage in mV
  "v4cap": 998,          // Cell 4 voltage in mV
  "shunting": false      // Shunting active or not
}

-caps can only be called on X7 gateway models

{
  "missing": true       // If no supercaps onboard
}

Modem Readings¶

Modem and SIM readings.

/opt/resiot/resiotinfo -modem

{
  "connected": true,
  "simFound": true,
  "simICCID": "8931001234567890123",
  "simResIOT": true,
  "connectionRssi": -87,                // Signal strength in dBm
  "connectionOperator": "Vodafone",
  "connectionBand": "4G",
  "modemImei": "352580110123456"
}

-modem can only be called on LTE gateway models

{
  "missing": true       // If no modem onboard
}

Service Readings¶

Presence of background ResIOT processes.

{
  "ResIOTMerlin": true,
  "ResIOTPacketForwarder": true,
  "ResIOTPacketForwarder2": false,
  "Basicstation": true,
  "ResIOTbsserver": true,
  "ResIOTplatform": true,
  "ResIOTwd": true
}

System Readings¶

CPU, RAM, disk, uptime and other system metrics.

{
  "uptime": 1234567,                // seconds
  "memoryTotal": 512,               // MB
  "memoryUsed": 233,                // MB
  "memoryUsedPerc": 45.5,           // %
  "cpuCores": 2,
  "cpuUsagePerc": [4.5, 5.6],       // %
  "systemTime": 1720692123,         // System Unix timestamp
  "storage": [
    {
      "name": "/dev/root",          // Partition name
      "mounted": "/",               // System path
      "size": 3500,                 // MB
      "used": 668,                  // MB
      "usedPercent": 20.5           // %
    }
  ]
}

If a section is not applicable (e.g., caps on a non-supercap model), the missing field is set to true and other fields are omitted.

Common Use Cases¶

Goal	Command
View temperature + humidity	`/opt/resiot/resiotinfo -basic`
Check solar charging status	`/opt/resiot/resiotinfo -mppt`
Show modem + SIM info	`/opt/resiot/resiotinfo -modem`
Full diagnostics on Solar	`/opt/resiot/resiotinfo -basic -mppt -modem -services -system`
Full diagnostics on X7LTE	`/opt/resiot/resiotinfo -basic -caps -modem -services -system`
Save output to file	`/opt/resiot/resiotinfo -basic -system -enablelogging -logpath /tmp/output.json`

Notes¶

The output is suitable for integration with monitoring systems or remote diagnostics tools.
Sections with "missing": true indicate hardware is absent. Disabled features return an error instead.

Logging ResIOT Readings to File¶

This guide explains how to periodically dump system and monitoring data from resiotinfo into a log file.
By setting this up, you can keep historical records for debugging, auditing, or external monitoring.

1. Create the dump script¶

First, create a script that will collect data at regular intervals.

nano /opt/resiot/resiotinfodump.sh

Paste the following content:

#!/bin/bash

#initial sleep of 5 minutes
sleep 300
while true; do
  #edit your resiotinfo parameters with what you wish to be dumped
  /opt/resiot/resiotinfo -basic -system -mppt -services -caps -print=false -enablelogging -logpath /var/log/resiotinfo.output

  #sleep 5 additional minutes before refreshing data
  sleep 300
done

Make it executable:

chmod +x /opt/resiot/resiotinfodump.sh

This configures resiotinfo to dump its output in the /var/log/resiotinfo.output file!

2. Register the script as a service¶

To run the script automatically at boot, register it as a service.

Create the service file:

nano /etc/init.d/resiotinfologger

Paste this:

#!/bin/bash

NAME="resiotinfologger"
pidfile=/opt/resiot/resiotinfologger.pid

do_start() {
    echo -n "Starting $NAME: "
    start-stop-daemon --start --background --make-pidfile --pidfile $pidfile --exec /opt/resiot/resiotinfodump.sh
    echo "OK"
}

do_stop() {
    echo -n "Stopping $NAME: "
    start-stop-daemon --stop --quiet --oknodo --pidfile $pidfile --retry 5
    rm -f $pidfile
    echo "OK"
}

case "$1" in
    start)
        do_start
        ;;
    stop)
        do_stop
        ;;
    restart)
        do_stop
        do_start
        ;;
    *)
        echo "Usage: $0 {start|stop|restart}"
        exit 1
        ;;
esac

Save and make it executable:

chmod +x /etc/init.d/resiotinfologger

Register the service so it runs on startup and start the service immediately:

update-rc.d resiotinfologger defaults
/etc/init.d/resiotinfologger start

3. Removing the service¶

To unregister the service so it no longer runs at boot:

update-rc.d -f resiotinfologger remove

You can still run the script manually if needed:

/opt/resiot/resiotinfodump.sh

Summary¶

/opt/resiot/resiotinfodump.sh handles what gets logged, how often, and where.
/etc/init.d/resiotinfologger makes the script automatically run at boot.
Logs are written to /var/log/resiotinfo.output (or your custom path).
Remove the service if you want to stop automatic logging.