Category     

NCOS: SDK Router API for Applications

« Go Back

Information

 
Content

NCOS: SDK Router API for Applications


Quick Links

Overview

Router Info

Router SDK and Application Info

Logging

Ping

GPIO

GPS

Modem

Overview

The router trees, also referred to as the router config store, are essentially the APIs to router query and control. One can read items to determine status or results and write to control and configure. All data is exchanged in the JSON format. The JSON format is described at http://www.json.org/. The data can be accessed via the router CLI, a python application, or using curl.

The router config store consist of the following trees:

  • control
    • Elements used for controlling functions of the router.
  • config
    • Elements used for router configuration.
  • status
    • Elements to get the status of the router.
  • state
    • Should not to be used by applications.

This document does not describe every item in the router config store. There are sections that cover functionality and how the config store can be used for that function (i.e. Ping, GPIO, GPS, Modem, etc.). Many functional areas will span multiple tree types depending on the use case. Anything which is done via the router UI, utilizes the router trees.

CLI Example

Below is an example of how to query the router system logging information using the cat or get command and then changing the logging level to info with the set command. Note the JSON format in the output. These trees can also be traversed using linux change directory command (i.e. cd /config/system/logging). This can be very useful to see what is contained in each branch of the tree.

    [admin@IBR900-267: /$ cat /config/system/logging
    {
        "console": false,
        "enabled": true,
        "firewall": false,
        "level": "debug",
        "max_logs": 1000,
        "modem_debug": {
            "lvl_error": false,
            "lvl_info": false,
            "lvl_trace": false,
            "lvl_warn": false
        },
        "remoteLogging": {
            "enabled": false,
            "serverAddr": "192.168.20.171",
            "server_port": 514,
            "system_id": false,
            "utf8_bom": false
        },
        "services": []
    }
    [admin@IBR900-267: /$ set /config/system/logging/level "info"

    [admin@IBR900-267: /$ cat /config/system/logging
    {
        "console": false,
        "enabled": true,
        "firewall": false,
        "level": "info",
        "max_logs": 1000,
        "modem_debug": {
            "lvl_error": false,
            "lvl_info": false,
            "lvl_trace": false,
            "lvl_warn": false
        },
        "remoteLogging": {
            "enabled": false,
            "serverAddr": "192.168.20.171",
            "server_port": 514,
            "system_id": false,
            "utf8_bom": false
        },
        "services": []
    }

Python Example

All sample apps include a cs.py file which contains the CSClient class. This class is a wrapper for the TCP interface to the router trees. Below is an example of how to query the router system logging information and then change the logging level to debug using the CSClient class.

    # Import the CSClient file which contains the necessary functions
    # for router config store access
    import cs

    appName = 'ref_app'

    cs.CSClient().log(appName, 'action({})'.format(command))

    # Read the logging level
    ret_value = cs.CSClient().get('/config/system/logging/level')

    # Output a syslog for the current logging level
    cs.CSClient().log(appName, 'Current Logging level = {}'.format(ret_value))
    ret_value = ''

    # Set the logging level to debug when the app is stopped.
    ret_value = cs.CSClient().put('/config/system/logging', {'level': 'debug'})

    # Output a syslog for the new current logging level
    cs.CSClient().log(appName, 'New Logging level = {}'.format(ret_value))

Curl Example

On Linux, the curl command can also be used to access items in the router trees. Use curl 'GET' to read and 'PUT' to write. Below is an example of getting the SDK status.

The user specific information in the curl command is:

  • router user name: admin
  • router password: 44224267
  • router IP address: 192.168.0.1

        $ curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X GET http://192.168.0.1/api/status/system/sdk | /usr/bin/env python3 -m json.tool
        {
            "success": true,
            "data": {
                "service": "started",
                "mode": "devmode",
                "summary": "Service started"
            }
        }
    
    
        curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X GET http://192.168.0.1/api/config/system/logging/level | /usr/bin/env python3 -m json.tool
        {
            "success": true,
            "data": "debug"
        }
    
    
        curl -s --digest --insecure -u admin:44224267 -H "Accept: application/json" -X PUT http://192.168.0.1/api/config/system/logging/level -d data='"info"' | /usr/bin/env python3 -m json.tool
        {
            "success": true,
            "data": "info"
        }        
    

Router Info

There are three different trees that provide router information. Most are self explanatory.

Product Info /status/product_info/:

    cat /status/product_info/
    {
        "company_name": "Cradlepoint, Inc.",
        "company_url": "http://cradlepoint.com",
        "copyright": "Cradlepoint, Inc. 2017",
        "mac0": "00:30:44:22:42:67",
        "manufacturing": {
            "board_ID": "909507",
            "mftr_date": "1643",
            "serial_num": "WA164300000518"
        },
        "product_name": "IBR900LP6"
    }

Firmware Info /status/fw_info/:

    cat /status/fw_info/
    {
        "build_date": "Wed Mar  8 18:57:21 MST 2017",
        "build_type": "RELEASE",
        "build_version": "cc2619b",
        "custom_defaults": false,
        "fw_update_available": false,
        "major_version": 6,
        "manufacturing_upgrade": false,
        "minor_version": 3,
        "patch_version": 1,
        "upgrade_major_version": 0,
        "upgrade_minor_version": 0,
        "upgrade_patch_version": 0
    }  

Feature Info /status/feature:

The feature information provides a list of feature license. The two SDK license will only exist if the features have been enabled via the NCM. The 'Router SDK' means that router apps have been enabled while the 'Router SDK - Dev Mode' means the the development mode is enabled.

    cat /status/feature
    {
        "db": [
            [
                "46a03bd2-91ae-11e2-a305-002564cb1fdc",
                "Extended Enterprise License",
                1123,
                1064
            ],
            [
                "b7b3eb09-53c5-4a5c-88d8-f9456870087c",
                "Router SDK - Dev Mode",
                7606,
                7597
            ],
            [
                "9568fa81-d8e0-4223-a18c-0b1784f21f2a",
                "Router SDK",
                7607,
                7597
            ]
        ],
        "expiring_alert": false
    }

System ID /config/system/system_id:

This is a customizable identity that will be used in router reporting and alerting. The default value is the product name and the last three characters in the MAC address of the router. It is used as a hostname to DHCP, so it must conform to standard hostname conventions.

    cat /config/system/system_id
    "IBR900-267"

Ethernet /status/ethernet:

Shows current state of the Ethernet ports and their speed.

    cat /status/ethernet
    [
        {
            "link": "up",
            "link_speed": "1000FD",
            "port": 0
        },
        {
            "link": "up",
            "link_speed": "1000FD",
            "port": 1
        },
        {
            "link": "down",
            "link_speed": "Unknown",
            "port": 2
        }
    ]

SDK and Application Info

SDK and application information can be found in /status/system/sdk. It contains the state of the Router SDK service and any application. If there are any error with installing or starting an application, it will be contained in this tree.

/status/system/sdk:

The main items in SDK status tree are:

  • mode
    • This indicates the route SDK mode which affects how apps can be installed.
      • standard - Normal router mode when apps can be installed via NCM.
      • devmode - Development mode which allows apps to be installed directly from a computer. This is set from the Tools menu of NCM.
  • service
    • The state of the Router SDK service in the router.
  • summary
    • A more detailed version of the Router SDK service state.
  • apps
    • A list of any apps that are installed with details about each app. Most are items self explanatory. However, note the 'state' which indicated the current state of the app. This can be installing, started, error, etc.

No App installed:

    cat /status/system/sdk
    {
        "mode": "devmode",
        "service": "started",
        "summary": "Service started"
    }

After App installed:

    cat /status/system/sdk
    {
        "apps": [
            {
                "_id_": "616acd0c-0475-479e-a33b-f7054843c971",
                "app": {
                    "auto_start": true,
                    "date": "2017-03-31T15:49:17.537335",
                    "name": "hello_world",
                    "reboot": true,
                    "restart": false,
                    "uuid": "616acd0c-0475-479e-a33b-f7054843c971",
                    "vendor": "Cradlebpoint",
                    "version_major": 1,
                    "version_minor": 0
                },
                "state": "started",
                "summary": "Started Application",
                "type": "developer"
            }
        ],
        "mode": "devmode",
        "service": "started",
        "summary": "Service started"
    }

Logging

Router logging can be queried or configured via /config/system/logging. This includes setting the log level along with sending logs to a syslog server.

    cat /config/system/logging/
    {
        "console": false,
        "enabled": true,
        "firewall": false,
        "level": "debug",
        "max_logs": 1000,
        "modem_debug": {
            "lvl_error": false,
            "lvl_info": false,
            "lvl_trace": false,
            "lvl_warn": false
        },
        "remoteLogging": {
            "enabled": false,
            "serverAddr": "192.168.0.171",
            "server_port": 514,
            "system_id": false,
            "utf8_bom": true
        },
        "services": []
    }
  • console
    • Not Used.
  • enabled
    • Not Used.
  • firewall
    • Not Used.
  • level
    • Setting the log level controls which messages are stored or filtered out. A log level of Debug will record the most information while a log level of Critical will only record the most urgent messages.
  • max_logs
    • This is the maximum number of log messages the service will store. After this limit is reached, the oldest are lost as new messages come in. However, based on the platform, the limit may be smaller.
  • modem_debug
    • Used to set the modem logging level. Not recommended for application use.
  • remoteLogging
    • enabled
      • Set true to send log messages to the specified Syslog Server.
    • serverAddr
      • The Hostname or IP address of the Syslog Server.
    • server_port
      • The Port Number of the Syslog Server.
    • system_id
      • Set true to include the routers "System ID" at the beginning of every log message. This is often useful when a single remote syslog server is handling logs for several routers.
    • utf8_bom
      • The log message is sent using a UTF-8 encoding. By default the router will preprend the Unicode Byte Order Mark (BOM) to the syslog message in compliance with the Syslog protocol, RFC5424. Some syslog servers may not support, fully, RFC5424 and will treat the BOM as ASCII text which will appear as garbled characters in the log. If this occurs, set this option to false.
  • services
    • Not recommended for application use.

Ping

Ping can be used to test communication to another host on the network. All ping operations and results are found in the /control/ping tree.

    cat /control/ping
    {
        "result": "",
        "start": {
            "bind_ip": false,
            "deadline": "Same as timeout",
            "df": "do",
            "family": "inet",
            "fwmark": null,
            "host": null,
            "iface": null,
            "interval": 1,
            "num": 4,
            "size": 56,
            "srcaddr": null,
            "timeout": 11
        },
        "status": "",
        "stop": ""
    }

Starting a Ping:

Write operations to control/ping/start will initiate a ping. The following will start a basic ping when written: {"host": "www.google.com", "size": 64}. An IP address can also be used.

NOTE: Concurrent ping operations are not supported.

Ping Options for control/ping/start:

  • iface: device UID, interface name, or Network name
    • Allows ping to be sourced from an interface
  • bind_ip: boolean
    • Causes ping to bind to an IP on the interface specified by "iface".
  • srcaddr: IP Address
    • Causes ping to be sourced from the specified IP address.
  • deadline: seconds
  • timeout: seconds
    • If specified, ping will continue until either "num" packets are sent, or "timeout" seconds have elapsed. The two options are equivalent, and if both are specified, the lesser of the two is used
  • df: {do, want, or dont}
    • Specify the Path MTU discovery option:
      • do: Asserts the "Don't Fragment" flag in the ICMP requests, prohibiting fragmentation
      • want: Allows local fragmentation, and will fragment the ICMP request if the ICMP request exceeds the outbound interfaces' MTU
      • dont: Do not assert the "Don't Fragment" flag, allowing fragmentation, and will fragment the ICMP Requests in response to ICMP fragmentation responses
  • fwmark: null/non-null
    • If non-null, then the SO_MARK socket option is set, causing the packetssent through the socket to be marked.
  • family: {inet or inet6}
    • If inet, then ping for IPv4 is used; if inet6, then the equivalent of ping6 is used.
  • host: Hostname, or IP address
    • Specifies the destination for the ICMP requests
  • interval: seconds
    • The number of seconds to wait between each ICMP request
  • num: integer
    • The number of ICMP requests to send before exiting. If "deadline" or "timeout" is also specified, then ping will exit after "num" packets have been sent, or min(deadline, timeout") seconds have elapsed.
  • size: bytes
    • Size of the ICMP request

Stopping a Ping:

Write operations to control/ping/stop will halt the ping in progress, if any. If a ping is not in progress, this is ignored.

Retrieving Results and Status:

Reading from control/ping/results will return the additional results since the last read, or the start of the ping, whichever is most recent. Reading the results will clear out the results immediately after they are read; the reader will need to concatenate the results if desired.

NOTE: If more than 10 results accumulate between reads, the oldest results will be truncated such that the maximum number of result lines will never exceed 10.

Reading from control/ping/status will return the current state of the ping in progress. Unlike the results, this will persist through multiple reads. The status can be one of 'running', 'done', 'stopped', or 'error'. If any packets were transmitted during the Ping, then when the ping stops, the result summary will be posted to control/ping/results (and cleared when read)

GPIO

Some of the Cradlepoint routers have GPIO connectors as well as GPIO pins built into the power connectors Below is information related to GPIO router config store tree items.

/config/system/gpio_actions

Includes configuration data for all user configurable pins - if the pin is enabled, it's direction, and what action it is currently assigned to. The available actions are:

if value of direction is in, available values for "current_action" are:

  • in_action_sensing Input Sensing:
    • In this mode the logic state (high or low) is automatically sensed by the router and is readable as the Current Value.
  • in_action_ignition Ignition Sensing:
    • (available on power connector only) In this mode the router will turn off after the input has been held low for the timeout period in seconds. The router will then reboot when the input is returned to high. If the input is held low for less than the timeout period before returning to high, no action is taken.
  • in_action_reset Router Reset:
    • (available on power connector only) In this mode an external device can reset the router by holding the input low for 10-seconds.

if value of direction is out, available values for "current_action" are:

  • out_action_low Default/Open:
    • In this mode the output pin is not used and is at 0V (ground potential).
  • out_action_high or out_action_router_running Set Closed/Router Running:
    • In these modes the output pin is logic low while the router is booting and transitions to logic high when the router is fully running. If the router is reset, the output returns to low until the router has fully rebooted.
  • out_action_modem_connected Modem Connected:
    • In this mode the output pin is logic low until the modem has connected to the tower. If the connection drops, this output is set low until the connection is restored.

The "pin" value is for internal purposes only. Please see /status/gpio_action for more information.

/status/gpio_actions

Used to view capabilities of the GPIOs. Here you can see what actions a pin supports, and what direction it can be set to (some pins are fixed direction and some are bidirectional). You can also get the "pretty_value" string, which outputs the current state of the GPIO in human readable form. It is updated every time this field is accessed.

/control/gpio

Used to bypass the GPIO service and set values to gpio pins manually. Not recommended

/status/gpio

Used to read the GPIO values directly from the pins.

/config/system/connector_gpio

Deprecated - DO NOT USE.

GPS

GNSS vs GPS

GNSS stands for Global Navigation Satellite Systems and GPS stand for Global Positioning System. GNSS is an umbrella term for all the satellite-based positioning systems, including GPS. GPS itself is the US satellite system and, however, GPS is used interchangeably for all satellite positioning systems. See https://en.wikipedia.org/wiki/Satellite_navigation for more details about satellite navigation.

The most common assumption is that all modems are capable of GPS. In order for a cellular modem to support GPS, GPS must be a function of both the modem and carrier. GPS requires the following four elements:

  • A cellular modem that supports GPS.
  • A cellular carrier that allows the GPS functionality on that modem.
  • Sufficient GPS signal level at the modem deployment location.
  • GPS antenna (depending on the model of modem or Cradlepoint).

From an app access perspective, most use cases only needs to verify that GPS is enabled and get the GPS location data. This is described below.

config/system/gps/enabled

This is either true or false and indicates gps enablement.

config/system/gps/enable_gps_keepalive

When "GPS Keepalive" is enabled, the GPS service will poll the GPS hardware every 10 seconds. The GPS hardware goes into a low power state after a certain interval of inactivity. Setting this flag will prevent the GPS from going into that low power state. Coming out of a low power state takes extra time to regain the GPS lock so set this flag to keep the hardware from falling asleep. Note this flag has no effect if the GPS service itself is not enabled.

Get GPS location data

The current GPS data can be found in /status/gps/.

This contains two fields: fix and nmea.

  • fix:
    • a struct containing parsed information about the current GPS fix.
  • nmea
    • an array of National Marine Electronics Association (NMEA) strings.

An example output is:

    cat /status/gps
    {
    'fix': {'age': 1.2596200000261888,
             'altitude_meters': 850.8,
             'ground_speed_knots': 0.0,
             'heading': 323.4,
             'latitude': {'degree': 43.0,
                          'minute': 37.0,
                          'second': 10.84808349609375},
             'lock': True,
             'longitude': {'degree': -116.0,
                           'minute': 12.0,
                           'second': 20.53081512451172},
             'satellites': 9,
             'time': 204921},
    'nmea': ['$GPGSV,4,1,16,05,14,275,24,07,61,082,30,08,40,063,28,09,29,167,26*71\r\n',
              '$GPGSV,4,2,16,11,18,116,27,13,17,316,27,17,02,189,23,27,12,036,24*77\r\n',
              '$GPGSV,4,3,16,28,53,243,25,30,67,317,32,33,,,35,38,,,34*7B\r\n',
              '$GPGSV,4,4,16,39,,,34,40,,,34,41,,,34,42,,,34*73\r\n',
              '$GPGGA,204920.0,4337.180827,N,11612.342184,W,1,09,0.9,850.8,M,-11.0,M,,*61\r\n',
              '$GPVTG,323.4,T,308.9,M,0.0,N,0.0,K,A*27\r\n',
              '$GPRMC,204920.0,A,4337.180827,N,11612.342184,W,0.0,323.4,110417,14.6,E,A*27\r\n',
              '$GPGSA,A,2,05,07,08,09,11,13,27,28,30,,,,1.2,0.9,0.8*3C\r\n']
    }

Modem

The modem status and control information is part of the wan tree. This is a very critical and complicated aspect of the router functionality. Please note that there is no direct access to the modem AT commands. For now, this section will only describe how to enable and disable a modem, along with some status information, as this has been requested by several application developers. More information will be added as needed.

The list of modems in the system can be found here: get /status/wan/devices. While this will list all the wan devices, not all modems may be configured with a SIM card.

    get status/wan/devices
    {
        "ethernet-wan": {
            ...
        },
        "mdm-feb80139": {
            ...
        },
        "mdm-fee5c7f2": {
            ...
        }
    }

To determine if a modem does not have SIM card inserted, see here: get status/wan/devices/mdm-/status/error_text. Where is the modem's unique identifier. The response will be 'null' if the card exist.

    get status/wan/devices/mdm-fee5c7f2/status/error_text
    "SIM error: NOSIM"

Here is an example of the diagnostic information for a modem with a SIM. This contains much data about the modem including its signal quality. Note that the "DBM" field is the modems RSSI.

    get status/wan/devices/mdm-fee5c7f2/diagnostics/
    {
        "BANDDLFRQ": "2110-2155",
        "BANDULFRQ": "1710-1755",
        "CARRID": "Verizon Wireless",
        "CARRIER_SWITCH_DEFAULTS": "VERIZON,ATT,SPRINT,GENERIC",
        "CELL_ID": "2934137 (0x2cc579)",
        "CFGAPNMASK": "8",
        "CGSN": "356526070342666",
        "CHIPSET": "9X30C",
        "CUR_PLMN": "311480",
        "DBM": "-60",
        "DEFAPN": "3",
        "DEFAPNTYPE": "IP",
        "DISP_IMEI": "356526070342666",
        "DISP_MEID": "35652607034266",
        "EMMCOMMSTATE": "RRC Idle",
        "EMMSTATE": "Registered",
        "EMMSUBSTATE": "Normal Service",
        "FW_CARRIER_LOAD": "VERIZON",
        "GSN": "356526070342666",
        "HM_PLMN": "311480",
        "HOMECARRID": "Verizon",
        "HW_VER": "1.0",
        "ICCID": "89148000003136071391",
        "IMSI": "311480313413488",
        "LAST_PIN": "",
        "LAST_PIN_VALID": "False",
        "LTEBANDWIDTH": "10 MHz",
        "MDL": "Internal LP6 (SIM1)",
        "MDM_CONTROL_TYPE": "NORMAL",
        "MDM_DRIVER_CAPABILITIES": "1547313",
        "MDM_MODE_CAPABILITIES": "21",
        "MDN": "+12086310191",
        "MFG": "CradlePoint Inc.",
        "MFG_MDL": "MC7455-CP",
        "MODEMIMSSTATE": "Full Service",
        "MODEMOPMODE": "Online",
        "MODEMPSSTATE": "Attached",
        "MODEMSYSMODE": "LTE",
        "MODEMTEMP": "33",
        "MSID": "2086310191",
        "PIN_RETRIES": "3",
        "PIN_STATUS": "READY",
        "PRD": "Internal LP6 (SIM1)",
        "PRI_ID": "9905117",
        "PRI_VER": "000.005",
        "PRLV": "15504",
        "PUK_RETRIES": "10",
        "RFBAND": "Band 4",
        "ROAM": "1",
        "RSRP": "-84",
        "RSRQ": "-7",
        "RXCHANNEL": "2000",
        "SCELLACTIVE": "Not Registered",
        "SELAPN": "3",
        "SIM_LOCK": "FALSE",
        "SINR": "9.2",
        "SS": "100",
        "SUPPORTED_TECH": "lte/3g",
        "TXCHANNEL": "20000",
        "VER": "SWI9X30C_02.05.07.00 r5154 CARMD-EV-FRMWR2 2015/12/04 22:23:15",
        "VER_PKG": "02.05.07.00_VERIZON,002.008_002",
        "VER_PREF_PKG": "02.05.07.00_VERIZON,002.008_002",
        "VER_PRETTY": "2.5.7.0"
    }

The modem can be enabled and disabled by changing the testmode/ready flag in the control tree (true to enable and false to diasable). 

    get control/wan/devices/mdm-fee5c7f2/testmode
    {
        "ready": true,
    }

Published Date: 10/17/2017

This article not have what you need? Not find what you were looking for? Think this article can be improved? Please let us know at suggestions@cradlepoint.com.


 
Knowledge Home | Product