1. Overview

1.1 What is USI

USI (Unified Status Interface) is a unified status query interface provided by the RobustOS Pro system, used to view device running status, network connection information, traffic statistics, and various other system information in real-time.

1.2 Basic Query Commands

# Query single status
usi get <status_path>

# Examples
usi get system.firmware_version    # Query firmware version
usi get active_link.ip              # Query current IP address
usi get gps.latitude                # Query GPS latitude

Permission Note: To keep examples concise, most commands in this document don't explicitly add sudo; in non-root environments, please add sudo before commands or run as root user. Example:

sudo usi get system.firmware_version

1.3 Usage Instructions

• Query commands require root privileges or sudo execution

• Status data is real-time information reflecting current device running status

• List item indexes start from 1, e.g., wan_links.link_status[1]

Sync First, Then Query:

• For values that change dynamically, execute usi sync

  html 错误：Message timeout after 5 minutes

   before usi get to synchronize the corresponding module's USI status, obtaining the latest data and avoiding reading stale values.

• Common modules requiring synchronization: cellular, lan_links, modem, wan_links, system, gps, wireless, openvpn, wireguard, route, ipsec, dmvpn, captive_portal, gre, emmc

Example:

# Sync cellular status before querying signal quality
usi sync cellular
usi get cellular.status[1].rsrp

2. System Information Queries

2.1 Basic System Information

Query Example:

# Query basic device information
echo "Device Model: $(usi get system.device_model)"
echo "Serial Number: $(usi get system.serial_number)"
echo "Firmware Version: $(usi get system.firmware_version)"
echo "Hardware Version: $(usi get system.hardware_version)"

2.2 Ethernet Port Information

3. Network Status Queries

3.1 Current Active Connection

Query currently active network connection information

Query Example:

# Sync WAN link status before querying
usi sync wan_links

# View current network connection status
echo "Current Interface: $(usi get active_link.desc)"
echo "IP Address: $(usi get active_link.ip)"
echo "Gateway: $(usi get active_link.gateway)"
echo "DNS: $(usi get active_link.dns)"

3.2 WAN Link Status

Query WAN interface connection status (supports multiple WAN links)

3.2.1 Link Basic Status

Query Example:

# Sync WAN link status before querying
usi sync wan_links

# Query first WAN link
echo "Interface: $(usi get wan_links.link_status[1].interface)"
echo "Status: $(usi get wan_links.link_status[1].status)"
echo "IP: $(usi get wan_links.link_status[1].ip4_addr)"

# Query second WAN link
echo "Interface: $(usi get wan_links.link_status[2].interface)"
echo "Status: $(usi get wan_links.link_status[2].status)"

# Batch query all WAN link statuses
for i in 1 2 3; do
    status=$(usi get wan_links.link_status[$i].status 2>/dev/null)
    if [ -n "$status" ]; then
        interface=$(usi get wan_links.link_status[$i].interface)
        ip=$(usi get wan_links.link_status[$i].ip4_addr)
        echo "WAN$i: $interface - $status - $ip"
    fi
done

3.2.2 WAN Link Traffic Statistics

Query Example:

# Sync WAN link status before querying
usi sync wan_links

# Query first WAN link traffic
echo "Interface: $(usi get wan_links.link_traffic[1].interface)"
echo "Sent: $(usi get wan_links.link_traffic[1].tx)"
echo "Received: $(usi get wan_links.link_traffic[1].rx)"
echo "Total: $(usi get wan_links.link_traffic[1].all)"

3.3 LAN Interface Status

Query LAN interface information

Query Example:

# Sync LAN link status before querying
usi sync lan_links

# Query LAN interface information
echo "LAN IP: $(usi get lan_links.link_status[1].ip4_addr)"
echo "LAN MAC: $(usi get lan_links.link_status[1].mac)"

3.4 LAN Connected Devices

Query list of devices connected to LAN

Query Example:

# Sync LAN link status before querying
usi sync lan_links

# Query all connected devices
echo "=== LAN Connected Devices ==="
for i in {1..50}; do
    ip=$(usi get lan_links.connected_device[$i].ip 2>/dev/null)
    if [ -n "$ip" ]; then
        mac=$(usi get lan_links.connected_device[$i].mac)
        interface=$(usi get lan_links.connected_device[$i].interface)
        inactive=$(usi get lan_links.connected_device[$i].inactive_time)
        echo "Device $i: $ip ($mac) - $interface - Inactive time: $inactive"
    fi
done

3.5 Route Status

Field Description:

• destination/netmask: 0.0.0.0/0 represents default route.

• gateway: Next hop address.

• interface: Outgoing network interface, e.g., wlan0, eth0.

• metric: Route priority metric value, smaller values have higher priority.

Query Example:

# Sync route status before querying
usi sync route

# Query route table entry 1 (example output below)
echo "=== Route Table Entry 1 ==="
echo "Destination: $(usi get route.route_table[1].destination)"
echo "Mask: $(usi get route.route_table[1].netmask)"
echo "Gateway: $(usi get route.route_table[1].gateway)"
echo "Interface: $(usi get route.route_table[1].interface)"
echo "Metric: $(usi get route.route_table[1].metric)"

# Iterate through first several routes and print valid entries
for i in {1..50}; do
    dest=$(usi get route.route_table[$i].destination 2>/dev/null)
    if [ -n "$dest" ]; then
        mask=$(usi get route.route_table[$i].netmask)
        gw=$(usi get route.route_table[$i].gateway)
        ifname=$(usi get route.route_table[$i].interface)
        metric=$(usi get route.route_table[$i].metric)
        echo "[$i] $dest/$mask via $gw dev $ifname metric $metric"
    fi
done

4. Cellular Network Status Queries

4.1 Modem Basic Status

4.2 SIM Card Traffic Statistics

Query Example:

# Query SIM card traffic
echo "=== SIM1 Traffic Statistics ==="
echo "Monthly RX: $(usi get modem.monthly_rx_bytes_sim1)"
echo "Monthly TX: $(usi get modem.monthly_tx_bytes_sim1)"
echo "Daily RX: $(usi get modem.daily_rx_bytes_sim1)"
echo "Daily TX: $(usi get modem.daily_tx_bytes_sim1)"

4.3 Detailed Cellular Network Status

Query signal strength, band, cell information, etc.

Query Example:

# Sync cellular status before querying
usi sync cellular

# Query cellular network signal quality
echo "=== Signal Status ==="
echo "Band: $(usi get cellular.status[1].band)"
echo "RSRP: $(usi get cellular.status[1].rsrp)"
echo "RSRQ: $(usi get cellular.status[1].rsrq)"
echo "SINR: $(usi get cellular.status[1].sinr)"
echo "Cell ID: $(usi get cellular.status[1].cell_id)"

4.4 Smart Roaming Status

Query Example:

# Query smart roaming status
echo "Roaming Status: $(usi get smart_roaming.state)"
echo "Selection Mode: $(usi get smart_roaming.oper_selection_mode)"

5. GPS Positioning Queries

5.1 GPS Status

Query Example:

# Sync GPS status before querying
usi sync gps

# Query GPS positioning information
echo "=== GPS Positioning Information ==="
echo "Status: $(usi get gps.status)"
echo "Time: $(usi get gps.time)"
echo "Latitude: $(usi get gps.latitude)"
echo "Longitude: $(usi get gps.longitude)"
echo "Altitude: $(usi get gps.altitude)"
echo "Speed: $(usi get gps.speed)"
echo "Satellites in Use: $(usi get gps.satellite_in_use)"
echo "Satellites in View: $(usi get gps.satellite_in_view)"

6. Serial Port and I/O Status Queries

6.1 Serial Port Status

Status Description:

• link_status:

  • up: Connection established (e.g., TCP client connected, or TCP server has client connected)

  • down: Connection disconnected

  • establish: Port initialized (e.g., in UDP mode)

Query Example:

# Query serial port 1 status and traffic
echo "Serial Port 1 Type: $(usi get serial_port.port[1].type)"
echo "Serial Port 1 Connection Status: $(usi get serial_port.port[1].link_status)"
echo "Serial Port 1 RX: $(usi get serial_port.port[1].rx_bytes)"
echo "Serial Port 1 TX: $(usi get serial_port.port[1].tx_bytes)"

6.2 Digital Input/Output (DIDO)

6.2.1 Digital Input (DI)

Status Value Description:

• level:

  • High: High level

  • Low: Low level

• status:

  • Alarm on: Alarm triggered

  • Alarm off: Alarm off

Query Example:

# Query DI1 status
echo "DI1 Level: $(usi get dido.di[1].level)"
echo "DI1 Status: $(usi get dido.di[1].status)"
echo "DI1 Count: $(usi get dido.di[1].count)"

6.2.2 Digital Output (DO)

Status Value Description:

• level:

  • Open / OFF(High): DO open or at high level (specific value depends on device model)

  • Closed / ON(Low): DO closed or at low level (specific value depends on device model)

  • Pulse: Pulse mode (instantaneous state)

Query Example:

# Query DO1 status
echo "DO1 Status: $(usi get dido.do[1].level)"

7. Traffic Statistics Queries

7.1 Total Traffic Statistics

7.2 WAN Traffic Statistics (Ethernet)

Query Example:

# Query WAN traffic
echo "=== WAN Traffic Statistics ==="
echo "Uptime: $(usi get wan.link_uptime)"
echo "Monthly RX: $(usi get wan.monthly_rx_bytes)"
echo "Monthly TX: $(usi get wan.monthly_tx_bytes)"
echo "Daily RX: $(usi get wan.daily_rx_bytes)"
echo "Daily TX: $(usi get wan.daily_tx_bytes)"

7.3 WLAN Traffic Statistics (WiFi)

8. Other Status Queries

8.1 NTP Time Synchronization

8.2 UCI Capability Information

9. Practical Query Script Examples

Note: Scripts in this section are executed by default in root environment; if running as regular user, please add sudo before usi commands in scripts.

9.1 Complete System Status Query

#!/bin/bash

# Sync common modules to ensure data is up-to-date
usi sync system
usi sync wan_links
usi sync gps
usi sync cellular

echo "========================================="
echo "  Robustel Device Status Report"
echo "========================================="
echo ""

# System information
echo "=== System Information ==="
echo "Device Model: $(usi get system.device_model)"
echo "Serial Number: $(usi get system.serial_number)"
echo "Firmware Version: $(usi get system.firmware_version)"
echo "Hardware Version: $(usi get system.hardware_version)"
echo ""

# Network status
echo "=== Network Status ==="
echo "Active Interface: $(usi get active_link.desc)"
echo "IP Address: $(usi get active_link.ip)"
echo "Gateway: $(usi get active_link.gateway)"
echo "DNS: $(usi get active_link.dns)"
echo ""

# WAN link status
echo "=== WAN Link Status ==="
for i in 1 2 3; do
    status=$(usi get wan_links.link_status[$i].status 2>/dev/null)
    if [ -n "$status" ]; then
        interface=$(usi get wan_links.link_status[$i].interface)
        ip=$(usi get wan_links.link_status[$i].ip4_addr)
        echo "WAN$i ($interface): $status - $ip"
    fi
done
echo ""

# GPS status
echo "=== GPS Status ==="
echo "Status: $(usi get gps.status)"
echo "Latitude: $(usi get gps.latitude)"
echo "Longitude: $(usi get gps.longitude)"
echo "Satellites: $(usi get gps.satellite_in_use)"
echo ""

# Signal quality
echo "=== Cellular Signal ==="
echo "Band: $(usi get cellular.status[1].band)"
echo "RSRP: $(usi get cellular.status[1].rsrp)"
echo "RSRQ: $(usi get cellular.status[1].rsrq)"
echo "SINR: $(usi get cellular.status[1].sinr)"
echo ""

# Traffic statistics
echo "=== Traffic Statistics ==="
echo "Total Traffic: $(usi get internet_traffic.total_traffic)"
echo "WAN Monthly RX: $(usi get wan.monthly_rx_bytes)"
echo "WAN Monthly TX: $(usi get wan.monthly_tx_bytes)"
echo ""

echo "========================================="
echo "  Report Generated: $(date)"
echo "========================================="

9.2 Network Connection Monitoring

#!/bin/bash

# Continuously monitor network connection status
while true; do
    clear
    echo "=== Network Connection Monitor - $(date) ==="
    echo ""

    # Sync WAN link status before each query
    usi sync wan_links

    # Active connection
    echo "Current Active Connection:"
    echo "  Interface: $(usi get active_link.desc)"
    echo "  IP: $(usi get active_link.ip)"
    echo ""

    # WAN links
    echo "WAN Link Status:"
    for i in 1 2 3; do
        status=$(usi get wan_links.link_status[$i].status 2>/dev/null)
        if [ -n "$status" ]; then
            interface=$(usi get wan_links.link_status[$i].interface)
            ip=$(usi get wan_links.link_status[$i].ip4_addr)
            printf "  WAN%d %-8s: %-15s %s\n" $i "($interface)" "$status" "$ip"
        fi
    done

    sleep 5
done

9.3 Signal Quality Monitoring

#!/bin/bash

# Monitor cellular signal quality
while true; do
    clear
    echo "=== Signal Quality Monitor - $(date) ==="
    echo ""

    # Sync cellular status before each query
    usi sync cellular

    band=$(usi get cellular.status[1].band)
    rsrp=$(usi get cellular.status[1].rsrp)
    rsrq=$(usi get cellular.status[1].rsrq)
    sinr=$(usi get cellular.status[1].sinr)

    echo "Band: $band"
    echo "RSRP: $rsrp"
    echo "RSRQ: $rsrq"
    echo "SINR: $sinr"
    echo ""

    # Simple signal quality assessment
    rsrp_val=$(echo $rsrp | grep -oP '[-]?\d+' | head -1)
    if [ -n "$rsrp_val" ]; then
        if [ $rsrp_val -ge -80 ]; then
            echo "Signal Quality: Excellent"
        elif [ $rsrp_val -ge -90 ]; then
            echo "Signal Quality: Good"
        elif [ $rsrp_val -ge -100 ]; then
            echo "Signal Quality: Fair"
        else
            echo "Signal Quality: Poor"
        fi
    fi

    sleep 3
done

9.4 GPS Position Tracking

#!/bin/bash

# GPS position tracking log
LOG_FILE="/tmp/gps_track.log"

echo "Starting GPS tracking, log saved to: $LOG_FILE"
echo "Press Ctrl+C to stop tracking"
echo ""

while true; do
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    # Sync GPS status before each query
    usi sync gps
    status=$(usi get gps.status)

    if [ "$status" = "Fixed" ]; then
        lat=$(usi get gps.latitude)
        lon=$(usi get gps.longitude)
        alt=$(usi get gps.altitude)
        speed=$(usi get gps.speed)
        sats=$(usi get gps.satellite_in_use)

        log_entry="$timestamp | $status | Lat: $lat | Lon: $lon | Alt: $alt | Speed: $speed | Sats: $sats"
        echo "$log_entry"
        echo "$log_entry" >> "$LOG_FILE"
    else
        log_entry="$timestamp | $status | Waiting for fix..."
        echo "$log_entry"
        echo "$log_entry" >> "$LOG_FILE"
    fi

    sleep 5
done

9.5 Traffic Usage Report

#!/bin/bash

# Sync related modules before generating report
usi sync wan_links
usi sync cellular
usi sync wireless

# Generate traffic usage report
echo "========================================="
echo "  Traffic Usage Report"
echo "========================================="
echo "  Generated: $(date)"
echo "========================================="
echo ""

# Total traffic
echo "=== Total Traffic ==="
echo "Total: $(usi get internet_traffic.total_traffic)"
echo ""

# WAN traffic
echo "=== WAN Traffic ==="
echo "Monthly RX: $(usi get wan.monthly_rx_bytes)"
echo "Monthly TX: $(usi get wan.monthly_tx_bytes)"
echo "Daily RX: $(usi get wan.daily_rx_bytes)"
echo "Daily TX: $(usi get wan.daily_tx_bytes)"
echo ""

# WLAN traffic
echo "=== WLAN Traffic ==="
echo "Monthly RX: $(usi get wlan.monthly_rx_bytes)"
echo "Monthly TX: $(usi get wlan.monthly_tx_bytes)"
echo "Daily RX: $(usi get wlan.daily_rx_bytes)"
echo "Daily TX: $(usi get wlan.daily_tx_bytes)"
echo ""

# SIM card traffic
echo "=== SIM1 Traffic ==="
echo "Monthly RX: $(usi get modem.monthly_rx_bytes_sim1)"
echo "Monthly TX: $(usi get modem.monthly_tx_bytes_sim1)"
echo "Daily RX: $(usi get modem.daily_rx_bytes_sim1)"
echo "Daily TX: $(usi get modem.daily_tx_bytes_sim1)"
echo ""

sim2_rx=$(usi get modem.monthly_rx_bytes_sim2 2>/dev/null)
if [ -n "$sim2_rx" ]; then
    echo "=== SIM2 Traffic ==="
    echo "Monthly RX: $(usi get modem.monthly_rx_bytes_sim2)"
    echo "Monthly TX: $(usi get modem.monthly_tx_bytes_sim2)"
    echo "Daily RX: $(usi get modem.daily_rx_bytes_sim2)"
    echo "Daily TX: $(usi get modem.daily_tx_bytes_sim2)"
    echo ""
fi

# Traffic for each WAN link
echo "=== Link Traffic ==="
for i in 1 2 3; do
    interface=$(usi get wan_links.link_traffic[$i].interface 2>/dev/null)
    if [ -n "$interface" ]; then
        tx=$(usi get wan_links.link_traffic[$i].tx)
        rx=$(usi get wan_links.link_traffic[$i].rx)
        all=$(usi get wan_links.link_traffic[$i].all)
        echo "Link $i ($interface):"
        echo "  TX: $tx"
        echo "  RX: $rx"
        echo "  Total: $all"
        echo ""
    fi
done

echo "========================================="

10. FAQ

10.1 Query Returns Empty Value

Problem: Some query commands return empty value or "status not found"

Possible Causes:

1. Corresponding function not enabled (e.g., cannot query GPS status when GPS is disabled)

2. Parameter name spelling error

3. List index out of range

Solution:

# First sync corresponding module (using GPS as example)
usi sync gps
# Use 2>/dev/null to ignore error messages
value=$(usi get gps.status 2>/dev/null)
if [ -z "$value" ]; then
    echo "GPS function not enabled or status unavailable"
fi

10.2 How to Determine if Network is Online

#!/bin/bash

# First sync WAN link status
usi sync wan_links

# Check network connection status
status=$(usi get wan_links.link_status[1].status)

if [ "$status" = "Connected" ]; then
    ip=$(usi get wan_links.link_status[1].ip4_addr)
    echo "Network connected - IP: $ip"
else
    echo "Network not connected - Status: $status"
fi

10.3 How to Get All WAN Links

#!/bin/bash

# Iterate through all possible WAN links
for i in {1..10}; do
    interface=$(usi get wan_links.link_status[$i].interface 2>/dev/null)
    if [ -n "$interface" ]; then
        status=$(usi get wan_links.link_status[$i].status)
        echo "WAN$i: $interface - $status"
    fi
done