Software interface

There are several software interfaces available to monitor the status of the u.RECS system. These are the Management WebGUI and a REST API providing XML based monitoring and management functionality.

The Management WebGUI is established on every u.RECS unit. Accessible by any known browser on the assigned IP address and the default port 443. The following views are dependent on the device and assembly.

In general these symbols have the following meaning on every page:

	Everything is OK. Also indicated by a green line in a graph.
	Warnung. Something is wrong, but the system is still fully functional. The system has to be checked so the problem doesn't get worse. Indicated by a yellow line in a graph.
	Critical Error. The system must be checked immediately and maybe has to be shut down to prevent hardware damage. indicated by a red line in a graph.

Fig. 1

Fig. 1

The u.RECS Management API is accessible via the IP-Address or the hostname of the u.RECS. The basic URL of the API has the format https://[ip-address]/REST/[system/baseboard/node] with http or https, depending on your configuration. Therefore, please check the following URL as an example:

https://192.168.0.50/REST/system

Accessing the REST API requires HTTP Basic authentication. The password of the admin account can be changed in the Settings page.

The u.RECS Management API makes all hardware components available as XML trees. The following components are supported by the API:

Many resources also return lists of components. These are named according to the scheme <component name>List (e.g. nodeList) and contain the elements of the list.

Example XML:

<nodeList>
  <node maxPowerUsage="26" baseboardPosition="0" architecture="unknown (SMARC)" baseboardId="RCU_0_BB_1" voltage="5.64" 
    actualNodePowerUsage="2.8" actualPowerUsage="2.8" state="0" lastPowerState="0" defaultPowerState="0" 
    rcuId="RCU_0" health="OK" lastSensorUpdate="1369" id="RCU_0_BB_1_0" present="true" bootDevice="0"/>
  <node maxPowerUsage="27" baseboardPosition="1" architecture="ARM + iGPU" baseboardId="RCU_0_BB_1" voltage="5.64" 
    actualNodePowerUsage="2.8" actualPowerUsage="2.8" state="0" lastPowerState="0" defaultPowerState="0" 
    rcuId="RCU_0" health="OK" lastSensorUpdate="1369" id="RCU_0_BB_1_1" present="false" mpciePresent="false" forceRecovery="false"/>
</nodeList>

The following table shows the possible attributes (some are optional) and their meaning:

In accordance to the component node the API offers nodeList which returns multiple instances of node.

Example XML:

<baseboard serialNumber="90380CA9D524" rcuPosition="0" baseboardType="u.RECS" id="RCU_0_BB_1" lastSensorUpdate="358" 
    rcuId="RCU_0" inputVoltage="22.93" boardVoltage1V0="1.97" boardVoltage1V2="2.05" boardVoltage1V5="2.05" 
    boardVoltage1V8="2.05" boardVoltage2V5="2.82" boardVoltage5V0="5.64" totalPowerUsage="11.24" usbPowerUsage="2.8" 
    mPciePowerUsage="1.64" m2PowerUsage="1.64" ethSwitchPowerUsage="0" poePowerUsagePort1="0" poePowerUsagePort2="0"
    regulatorsTemperature="0" ambientTemperature="0" fanSpeed="100" systemFan1Rpm="0" systemFan2Rpm="0" loraJoined="false"
    loraJoinEui="0000000000000000" loraDevEui="1234561234561234" loraAppKey="01234567890123456789012345678901"
    loraVendorID="FFFF" loraVendorProfileID="0001" loraRssi="16" poeDetectionStatusPort1="0" poeDetectionStatusPort2="0"
    firmwareVersion="0837db2">
  <nodeId>RCU_0_BB_1_0</nodeId>
  <nodeId>RCU_0_BB_1_1</nodeId>
</baseboard>

The attributes have the following meaning:

The output of the /REST/system API call returns a combined output of /REST/node and /REST/baseboard, which eases the monitoring of the whole system with one call.

Example XML:

<system>
  <baseboard serialNumber="90380CA9D524" rcuPosition="0" baseboardType="u.RECS" id="RCU_0_BB_1" lastSensorUpdate="1403" 
      rcuId="RCU_0" inputVoltage="22.93" boardVoltage1V0="1.97" boardVoltage1V2="2.05" boardVoltage1V5="2.05" 
      boardVoltage1V8="2.05" boardVoltage2V5="2.82" boardVoltage5V0="5.64" totalPowerUsage="11.24" usbPowerUsage="2.8" 
      mPciePowerUsage="1.64" m2PowerUsage="1.64" ethSwitchPowerUsage="0" poePowerUsagePort1="0" poePowerUsagePort2="0" 
      regulatorsTemperature="0" ambientTemperature="0" fanSpeed="100" systemFan1Rpm="0" systemFan2Rpm="0" loraJoined="false"
      loraJoinEui="0000000000000000" loraDevEui="1234561234561234" loraAppKey="01234567890123456789012345678901"
      loraVendorID="FFFF" loraVendorProfileID="0001" poeDetectionStatusPort1="0" poeDetectionStatusPort2="0" 
      firmwareVersion="0837db2-dirty">
    <nodeId>RCU_0_BB_1_0</nodeId>
    <nodeId>RCU_0_BB_1_1</nodeId>
  </baseboard>
  <nodeList>
    <node maxPowerUsage="26" baseboardPosition="0" architecture="unknown (SMARC)" baseboardId="RCU_0_BB_1" voltage="5.64" 
      actualNodePowerUsage="2.8" actualPowerUsage="2.8" state="0" lastPowerState="0" defaultPowerState="0" rcuId="RCU_0" 
      health="OK" lastSensorUpdate="1403" id="RCU_0_BB_1_0" present="true" bootDevice="0"/>
    <node maxPowerUsage="27" baseboardPosition="1" architecture="ARM + iGPU" baseboardId="RCU_0_BB_1" voltage="5.64" 
      actualNodePowerUsage="2.8" actualPowerUsage="2.8" state="0" lastPowerState="0" defaultPowerState="0" rcuId="RCU_0" 
      health="OK" lastSensorUpdate="1403" id="RCU_0_BB_1_1" present="false" mpciePresent="false" forceRecovery="false"/>
  </nodeList>
</system>

The resources are split into monitoring resources (for pure information gathering) and management resources (for changing the system configuration or state).

For monitoring the following resources are available:

The management of individual components can be found under the “manage” path of the component.

The LoRaWAN interface allows up and downlink connections to an application server. Payload can be scheduled and collected by interfacing the Management REST API.

Example HTTP Body on GET request:

<lorawan>
  <payload>{custom lorawan payload}</payload>
  <time>{timestamp}</time>
</lorawan>

Example HTTP Body on POST request:

<lorawan>
  <payload>{custom lorawan payload}</payload>
</lorawan>

The Frame Port (fport) separates different communication parties on the API, and functions as an identifyer for the message sender / reciever. When using the REST API, you are free to choose a value between 2 - 223. FPort 1 is reserved for the management controller.

Information about the success or failure of management requests are returned via HTTP status codes. Please have a look at RFC2616 for an overview about the defined HTTP status codes.

The u.RECS supports upstream and downstream LoRa messages to The Things Network (TTN). The following table gives the LoRa message meaning of version 0.

All system related management communication (excluding the REST API) uses FPort 1.

Upstream message payload layout:

The u.RECS supports basic control functions over LoRaWAN. Downstream message payloads:

Change power state for node:

Here is some C-Code to decode the PoE Status:

PoE Status Bytes:
switch (status & 0xF) {
  case 0: ret = "Detection unknown"; break;
  case 1: ret = "Short circuit"; break;
  case 2: ret = "Capacitive"; break;
  case 3: ret = "RLOW"; break;
  case 4: ret = "RGOOD"; break;
  case 5: ret = "RHIGH"; break;
  case 6: ret = "Open circuit"; break;
  case 7: ret = "PSE to PSE"; break;
  case 15: ret = "MOSFET fault"; break;
}
 
if ((status & 0xF) == 4) { // RGOOD
  switch ((status >> 4) & 0xF) {
    case 0: ret += ", class unknown"; break;
    case 1: ret += ", class 1"; break;
    case 2: ret += ", class 2"; break;
    case 3: ret += ", class 3"; break;
    case 4: ret += ", class 4"; break;
    case 6: ret += ", class 0"; break;
    case 7: ret += ", overcurrent"; break;
    case 8: ret += ", class 5 4P single signature"; break;
    case 12: ret += ", class 4 type 1 limited"; break;
    case 13: ret += ", class 5 legacy"; break;
    case 15: ret += ", class mismatch"; break;
}