Utility Resources

Resources under the /util/ category are available by default on all Octave edge devices. They allow for control and monitoring of several edge system-level processes.

• /util/cellular and /util/sim are able to report information about the cellular connectivity status. For a complete list of connectivity states see Cellular Signal Status Values.
• /util/cellular/cells/value provides information about the current cellular connection and neighboring cellular connections detected. See Cells Resource below for more information.
• /util/time provides time information.
• /util/reboot/trigger is used to manually force the device to reboot. This is accomplished by clicking the Resource's Send Command button and then clicking Trigger. You can also set the value from a REST API call by passing { "elems" : { "/util/reboot/trigger" : 1 } } as the data. Note that you will need to use escape characters when invoking the call from programs like cURL.
• /util/ulpm is used to configure and operate ULPM as indicated here.
• /util/counter and /util/delay are used to handle periodic timers and delays on the Edge side. See Counter Resource and Delay Resource below for more information.

Cells Resource

The /util/cellular/cells/value Resource provides the following information about the current (serving) cell and neighboring cells detected:

• cid: cell ID
• lac: location area code for GSM cells.
• MCC: mobile country code
• MNC: mobile network code (current network public land mobile network (PLMN) information in numeric format)
• nb: collection of neighboring cells detected (i.e., the cells the device is aware of but not connected to)
• rat: radio access technology used by the cell. The values will be set to one of the following:
  • Firmware Prior to 3.3.0 (numbers): the following are the possible numbers:
    • 0: Unknown
    • 1: GSM network
    • 2: UMTS networks
    • 3: TD-SCDMA networks
    • 4: LTE network
    • 5: CDMA network
  • Firmware 3.3.0+ (strings): "GSM", "LTE", "UMTS", "CDMA", or "TD-SCDMA"
• rx: Rx level (in dBm)
• tac (FW 3.3.0+): tracking area code for LTE cells.

📘

Note:

lac is reported for GSM cells. For LTE cells, lac is replaced with tac.

The following subsections show examples of the JSON format for the /util/cellular/cells/value Resource.

Format Prior to Firmware 3.3.0

The following shows the format of the /util/cellular/cells/value Resource prior to Firmware 3.3.0 for a GSM cell:

{
    "cid": 10122,
    "lac": 12814,
    "mcc": "208",
    "mnc": "01",
    "nb": [
        {
            "cid": 10121,
            "lac": 12814,
            "rx": -77
        },
        {
            "cid": 10765,
            "lac": 12814,
            "rx": -84
        },
        {
            "cid": 5230,
            "lac": 12814,
            "rx": -93
        },
        {
            "cid": 10123,
            "lac": 12814,
            "rx": -94
        }
    ],
    "rat": 1,
    "rx": -71
}

Format in Firmware 3.3.0 and Above

There are a few key changes to the JSON format for the /util/cellular/cells/value Resource as of firmware 3.3.0:

1. The serving cell is now the first cell listed instead of the first neighboring cell.
2. The rx level information has been removed from the serving cell as it is already available through util/cellular/signal.
3. rat has been changed from a number to a string and will be set to one of the following: "GSM", "LTE", "UMTS", "CDMA", "TD-SCDMA".
4. For LTE, the Resource reports the global cell ID instead of the physical cell ID.
5. The tracking area code (tac) is reported for LTE cells.

GSM Example
The following shows an example of the JSON format for a GSM cell:

{
    "cid": 10122,
    "lac": 12814, // "tac" when device registered on LTE
    "mcc": "208",
    "mnc": "01",
    "nb": [
        {
            "cid": 10121,
            "lac": 12814,
            "rx": -77
        },
        {
            "cid": 10765,
            "lac": 12814,
            "rx": -84
        },
        {
            "cid": 5230,
            "lac": 12814,
            "rx": -93
        },
        {
            "cid": 10123,
            "lac": 12814,
            "rx": -94
        }
    ],
    "rat": "GSM"
}

LTE Example
The following shows an example of the JSON format for an LTE cell:

{
    "cid": 18479108,
    "mcc": "208",
    "mnc": "01",
    "nb": [
        {
            "cid": 462,
            "rx": -35
        },
        {
            "cid": 463,
            "rx": -63
        },
        {
            "cid": 474,
            "rx": -63
        }
    ],
    "rat": "LTE",
    "tac": 25637
}

Counter Resource

The /counter Resource is used to configure periodic executions on the Octave Edge side.

In order to configure a periodic counter:

• set /counter/enable to True
• set /counter/period to the desired period value (in seconds)

Once this is done, the /counter/value will be increased by one unit every time the period expires.

The typical usage is to observe this counter to trigger an Edge Action on a periodic basis.
To handle multiple periods, multiple Observations can be made on the same counter with a throttling introduced in the Observations. Or one unique Edge Action can compute different modulo values of the counter to run different parts of code.

/counter/trigger can be written to in order to force a counter increment at any time (the counter needs to be enabled, and this increment will be done on top of ongoing periodic increments).

📘

Use the Counter to Periodically Report Multiple Resource Values to the Cloud

The counter feature can be used as indicated in this reference implementation

Delay Resource

The Delay Resource is used to trigger an Event at a given time after an initial Event.

In order to use the Delay feature:

• set /delay/set to the desired delay value (in seconds)
• observe the /delay/value : it will be updated (to the delay value) as soon as the delay has expired

The typical method for using the delay feature is for an Edge Action to perform an action (based on other inputs/logic) and to initiate a given delay. Then, with an Observation on /delay/value targeting another Edge Action, this allows execution of a secondary action systematically, any given time after the initial Edge Action.

🚧

Only one Delay can be Handled at the Same Time

If delay is set before a previously ongoing delay has expired, the new delay will supersede the ongoing one.