Overview of the IoT FND North Bound API

This section describes the North Bound API (NB API) supported by the Cisco IoT Field Network Director (Cisco IoT FND or IoT FND).

Overview of the IoT FND North Bound API

IoT FND maintains a database of inventory information about network devices, groups, properties, metrics, and events. You can use NB API to retrieve network statistics and properties for deployed networked devices. You can also access the database using the IoT FND NB API (Database Queries).

The IoT FND NB API is a Simple Object Access Protocol (SOAP) API that provides methods for:

  • Read-only access to the IoT FND database

  • Push-based event reporting

  • Invoking management operations such as mesh firmware updates, rule creation, and mesh migration

Many APIs return lists of identifiers or objects. Because these lists could be very long in a large network, every method has three optional arguments: queryId, count, and offset. NB APIs use the Web Services Description Language (WDSL) to define network services.

When no argument is included, the call returns the first count list items. The maximum count is 1000 items.

To iterate through the full contents of a list, select a queryId, which is a random string. Then repeat the call using the same queryId, and increment the offset by count for each call, starting from 0. When the call returns an empty list, the iteration is complete, and the queryId is invalidated on the server. Reusing queryId starts the request from the beginning. If a particular queryId is not used for 10 minutes, it is cleared to conserve resources.

The API uses HTTPS and HTTP Basic Authentication for username and password authorization, and for sending event data.


Note


IoT FND Release 2.1.1-54 and later do not support TLSv1.0 or TLSv1.1 based connections. Only TLS1.2 based connections are supported.
Figure 1. Database Queries

Document Conventions

This document uses the following conventions:

Conventions

Indication

bold font Commands and keywords and user-entered text appear in bold font.
italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font.
[ ] Elements in square brackets are optional.
{x | y | z } Required alternative keywords are grouped in braces and separated by vertical bars.
[ x | y | z ] Optional alternative keywords are grouped in brackets and separated by vertical bars.
string A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.
courier font Terminal sessions and information the system displays appear in courier font.
< > Nonprinting characters such as passwords are in angle brackets.
[ ] Default responses to system prompts are in square brackets.
!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

Note


Means reader take note . Notes contain helpful suggestions or references to material not covered in the manual.

Caution


Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.


DANGER

IMPORTANT SAFETY INSTRUCTIONSMeans danger. You are in a situation that could cause bodily injury. Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with standard practices for preventing accidents. Use the statement number provided at the end of each warning to locate its translation in the translated safety warnings that accompanied this device.

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What’s New in Cisco Product Documentation at: http:/​/​www.cisco.com/​c/​en/​us/​td/​docs/​general/​whatsnew/​whatsnew.html .

Subscribe to What’s New in Cisco Product Documentation , which lists all new and revised Cisco technical documentation as an RSS feed and delivers content directly to your desktop using a reader application. The RSS feeds are a free service.

IoT FND NB API Modules

IoT FND defines the following API modules:

API Module

WSDL URL

Method Calls

audittrail

Audit Trail API

https://<server_address> /nbapi/audittrail?wsdl

deleteAuditTrailsByTime

getAuditTrailsByOperation

getAuditTrailsByTime

getAuditTrailsByUser

getAuditTrailsByUserAndIp

getAuditTrailsByUserAndOperation

getAuditTrailsByUserIpAndOperation

device

Device Management API

https://<server_address> /nbapi/device?wsdl

addDevices

exportDevices

getJob

removeDevices

setDevices

updateDevices

reprovision

Mesh Firmware Migration API

https://<server_address> /nbapi/reprovision?wsdl

cancelReprovision

showReprovisionStatus

startReprovisionByEidList

startReprovisionByEidListAbridged

startReprovisionByGroup

startReprovisionByGroupAbridged

meshDeviceOps

Firmware Upgrade API

https://<server_address> /nbapi/meshDeviceOps?wsdl

getFirmwareUploadStatus

getFirmwareImageInfoList

scheduleReload

setBackupFirmwareImage

startUpload

stopUpload

Note    Firmware upgrades are only supported on Cisco IOS.

workorder

Workorders API

https://<server_address> :portnumber/nbapi/workorder

RequestUserAuthentication

RequestSignedAuthorization

UploadServiceReport

event

Event API

https://<server_address> /nbapi/event?wsdl

searchEvents

subscribeForCgmeshOutage

subscribeForEvents

unSubscribeForCgmeshOutage

unSubscribeForEvents

issue

Issues API

https://<server_address> /nbapi/issue?wsdl

searchIssues

rules

Rules API

https://<server_address> /nbapi/rules?wsdl

activateRule

createRule

deactivateRule

dropRule

findRulesByName

findRulesByUsername

search

Search API

https://<server_address> /nbapi/search?wsdl

getDeviceDetails

getDeletedDevices

getUpdatedDeviceDetails

getGroups

getMetricHistory

searchDevices

findEidsForIpAddress

findEidsForIpAddressByDeviceType

To view the WSDL of the API in a Web browser, use this URL format:

https://<server_address >/nbapi/<api> ?wsdl

For example:

https://10.27.167.19/nbapi/event?wsdl

Query Syntax

The IoT FND NB API supports the following simple query language:

  • Search := filter ?[filter ...]

  • Filter := Filter := <fieldName><operator><value>

  • Operator := < | <= | > | >= | <> | = | :

Search query examples:

"deviceType:cgr1000 uptime>=100 uplinkTxDrops<-50"
"deviceType:cgmesh uptime>=100"
"" (search everything)
"uptime>=100 status:up"
"eid:xyz"
"xyz" 

Property Field Names for All Devices

The following table describes the property field names available to all devices. Field names are case sensitive.

Table 1 Property Field Names for All Devices

Field Name

Type

Description

Example

eid

string

Unique identifier for the device. For routers and communication modules, this is the string representation of the X.500 distinguished name subject ID contained in the devices X.509 certificate. This field name is obtained from the notice-of-shipment file.

CGR1240/K9

CGR1120/K9

deviceType

enum

Identifier for the device type that indicates which IoT FND module coordinates communications with the device.

  • Cisco Connected Grid Routers 1000 series are cgr1000

  • Cisco Aggregation Services Routers 1000 series are asr1000

  • Cisco Integrated Service Routers 3900 series are isr3900

  • Cisco 800 Series Integrated Services Routers (ISR 800s) are c800

  • Cisco 800 Series Integrated Services Routers (IR 800s) are ir800

  • Cisco 800 Series Access Points are ap800

  • Cisco 500 Series Wireless Personal Area Network (WPAN) Industrial Routers (IR 500) are ir500

  • Communications modules are cgmesh

  • The IoT FND database is db

This identifier is obtained from the notice-of-shipment file.

cgmesh

cgr1000

ip

string

Primary IP address that IoT FND uses to contact the device. Can be IPv4 or IPv6. This address is obtained when the device registers with IoT FND.

1.1.1.1

lat

decimal

Latitude of the device obtained from manual CSV import.

10

lng

decimal

Longitude of the device obtained from manual CSV import.

-11.1

alt

decimal

Altitude of the device obtained from manual CSV import.

10

mapLevel

decimal integer

Minimum map zoom level at which the device is displayed on the map. This is useful for viewing large networks. This value is obtained from manual CSV import and is an optional field.

16

geoHash

string

String hash latitude and longitude values used for automatic hierarchical grid-based clustering of the devices.

s1qeg9spc8n95rrw1dww7

lastHeard

timestamp

Time when the device was last heard from or contacted. This is used as the primary determiner of device activity level and status.

This value is automatically set when the device reports to the IoT FND or the IoT FND contacts the device.

2011-05-02 00:00:00

status

enum

Current status of the device automatically set by IoT FND. Values are limited to up, down, and unheard.

up

certC

string

X.500 country name from the certificate subject, if one exists. This value is obtained from the notice-of-shipment file, as are all “cert” properties.

US

certST

string

X.500 state or province name, if one exists.

CA

certL

string

X.500 locality name, if one exists.

San Jose

certO

string

X.500 organization name, if one exists.

Cisco Systems, Inc.

certOU

string

X.500 organizational unit name, if one exists.

Operations Department

certCN

string

X.500 common name, if one exists.

App Client

certSN

string

X.500 serial number, if one exists.

12:34:A4:B9

pid

string

Product ID for the device. For routers and communication modules, this is the Cisco Secure Unique Device Identifier (SUDI) product ID from the certificate.

CGR1240/K9

vid

string

Version ID for the device. Obtained from the SUDI for routers and communication modules.

1.0

sn

string

Serial number for the device.

JAF1741ALPA

Property Field Names for Supported Routers

The following table describes the property field names available to supported Connected Grid routers. The field names are case sensitive.

Table 2 Property Field Names for Supported Routers

Field Name

Type

Description

activeLinkType

string

Physical link type over which device communicates with other devices, including IoT FND.

endUserIPv6Prefix

string

End user IPv6 address for basic mapping rule for the device.

endUserIPv6PrefixLen

string

Prefix length for the end user IPv6 address.

mapTipv6Address

string

Map-T settings IPv6 address.

mapTipv4Address

string

Map-T settings IPv4 address.

mapTpsid

string

Map-T status PSID.

meshAddress

string

IP address of the mesh link automatically assigned by IoT FND during registration.

meshLocalAddress

string

Local WPAN address of the mesh link automatically assigned by IoT FND during registration.

meshPrefix

string

Subnet prefix address.

meshPrefixLength

string

Subnet prefix address length.

meshPanid

string

Subnet Private Area Network (PAN) ID.

Property Field Names for Range Extenders

The following table describes the property field names available to range extenders. The field names are case sensitive.

Table 3 Property Field Names for Range Extenders

Field Name

Type

Description

batteryState

string

Determine the current battery state.

bbuManufacturer

string

The manufacturer of the Battery Backup Unit (BBU).

bbuPid

string

The physical model name of the BBU.

bbuPresent

string

The BBU hardware is present.

bbuReady

string

The BBU is ready.

bbuSn

string

The serial number of the BBU.

bbuVid

string

The physical hardware version of the BBU.

powerSource

string

Determine if the device is running on AC or DC power.

Property Field Names for Communications Modules

The following table describes the property field names available to communications modules. The field names are case sensitive.

Table 4 Property Field Names for Communications Modules

Field Name

Type

Description

meshAddress

string

The IP address of the mesh link automatically assigned by IoT FND during registration.

meshLocalAddress

string

Local WPAN address of the mesh link automatically assigned by IoT FND during registration.

meshPrefix

string

Subnet prefix address.

meshPrefixLength

string

Subnet prefix address length.

meshPanid

string

Subnet PAN ID.

Metrics Field Names

Metrics collected by IoT FND are defined per device type, and maintained in a XML file specific to each device type. IoT FND locates the XML files after it loads the boot strap image.


Note


Do not use metrics defined for interfaces for searches.

Metrics for Communication Modules

The following table describes the metrics for communication modules.

Table 5 Metrics for Communication Modules

Metric Name

Unit

Min

Max

Description

uptime

sec

0

31536000

Amount of time, in seconds, that the module has been running since last boot.

meshTxSpeed

b/s

0

76800

Current speed of data transmission over the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

meshTxDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the uplink interface because the outbound queue was full.

meshRxSpeed

b/s

0

76800

Rate of data received by the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

meshRxReassemblyDrops

drops/sec

0

1

Rate of incoming packet fragments dropped because there was no space in the reassembly buffer.

meshHops

hops

1

8

Number of hops the element is from the root of its RPL routing tree.

meshLinkCost

1

3

RPL cost value for the link between the element and its uplink neighbor.

meshPathCost

1

24

RPL path-cost value between the element and the root of the routing tree.

meshRssi

dBm

-80

20

Measured RSSI value of the primary mesh RF uplink.

meshReverseRssi

dBm

-80

20

RSSI value measured by the mesh uplink neighbor.

Metrics for Communication Module Loopback Interface

The following table describes the metrics for communication modules loopback interface.

Table 6 Metrics for Communication Modules Loopback Interface

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period (for example, an hour).

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

rxSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period (for example, an hour).

txUnicastPackets

packets/sec

0

76800

Current packet receive rate over the interface, measured in packets per second, averaged over a short element-specific time period (for example, an hour).

Metrics for WPAN Module Interfaces

The following table describes the metrics for WPAN module interfaces.

Table 7 Metrics for the WPAN Module Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period (for example, an hour).

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period (for example, an hour).

txUnicastPackets

packets/sec

0

76800

Current packet send rate over the interface, measured in packets per second, averaged over a short element-specific time period (for example, an hour).

rxUnicastPackets

packets/sec

0

76800

Current packet receive rate over the interface, measured in packets per second, averaged over a short element-specific time period (for example, an hour).

Metrics for PPP Interfaces

The following table describes the metrics for PPP interfaces.

Table 8 Metrics for PPP Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

rxSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

txUnicastPackets

packets/sec

0

76800

Current packet send rate over the interface, measured in packets per second, averaged over a short element-specific time period.

rxUnicastPackets

packets/sec

0

76800

Current packet receive rate over the interface, measured in packets per second, averaged over a short element-specific time period.

Metrics for RPL Interfaces

The following table describes the metrics for Routing Protocol for Low Power and Lossy Networks (RPL) interfaces..

Table 9 Metrics for RPL Interfaces

Metric Name

Unit

Min

Max

Description

hops

hops

1

8

Number of hops the element is from the root RPL tree.

linkCost

1

3

RPL cost value for the link between the element and its uplink neighbor.

pathCost

1

24

RPL path cost value between the element and the root of the routing tree.

rssi

dBm

-80

20

Measured RSSI value of the primary mesh RF uplink.

reverseRSSI

dBm

-80

20

RSSI value measured by the element’s mesh uplink neighbor.

Metrics for Supported Connected Grid Routers

The following table describes the metrics for supported routers.

Table 10 Metrics for Supported Routers

Metric Name

Unit

Min

Max

Description

batteryLevel

%

0

100

Percentage of charge remaining in the first battery.

batteryLevel2

%

0

100

Percentage of charge remaining in the second battery.

batteryRuntime

minutes

0

65535

Runtime remaining on the first battery.

batteryRuntime2

minutes

0

65535

Runtime remaining on the second battery.

cellRSSI

dBm

-100

0

Cell Received Signal Strength Indicator (RSSI).

chassisTemp

Celsius

0

100

Internal temperature of the device.

meshEndpointCount

devices

0

10000

Number of active mesh endpoints connected to this element.

meshRoutes

entries

0

1000

Number of entries that a given router has in its source-route table. This is a method to measure the number of elements in a given PAN.

meshRxReassemblyDrops

drops/sec

0

1

Rate of incoming packet fragments dropped because there was no space in the reassembly buffer.

meshRxSpeed

b/s

0

76800

Rate of data received by the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

meshTxDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the uplink interface because the outbound queue was full.

meshTxSpeed

b/s

0

76800

Current speed of data transmission over the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

serial0rxSpeed

b/s

0

100000000

Receive rate for the Serial 0 interface.

serial0txSpeed

b/s

0

100000000

Transmit rate for Serial 0 interface.

serial1rxSpeed

b/s

0

100000000

Receive rate for the Serial 1 interface.

serial1txSpeed

b/s

0

100000000

Transmit rate for Serial 1 interface.

uplinkRssi

dBm

-100

-50

Measured RSSI value of the primary RF uplink used for all RF uplinks.

uplinkRxDrops

drops/sec

0

1

Rate of packets received on the uplink interface, but then dropped because the inbound queue was full.

uplinkRxSpeed

b/s

0

3000000

Rate of data received by the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

uplinkTxDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the uplink interface because the outbound queue was full.

uplinkTxSpeed

b/s

0

500000

Current speed of data transmission over the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

uptime

sec

0

31536000

Amount of time, in seconds, that the element has been running since last boot.

Metrics for Supported Connected Grid Routers

The following table describes the metrics for supported routers.

Table 11 Metrics for Supported Routers

Metric Name

Unit

Min

Max

Description

batteryLevel

%

0

100

Percentage of charge remaining in the first battery.

batteryLevel2

%

0

100

Percentage of charge remaining in the second battery.

batteryRuntime

minutes

0

65535

Runtime remaining on the first battery.

batteryRuntime2

minutes

0

65535

Runtime remaining on the second battery.

cellRSSI

dBm

-100

0

Cell Received Signal Strength Indicator (RSSI).

chassisTemp

Celsius

0

100

Internal temperature of the device.

fourTo6Translations

0

100000000

MAP-T metrics map4to6Translations.

meshEndpointCount

devices

0

10000

Number of active mesh endpoints connected to this element.

meshRoutes

entries

0

1000

Number of entries that a given router has in its source-route table. This is a method to measure the number of elements in a given PAN.

meshRxReassemblyDrops

drops/sec

0

1

Rate of incoming packet fragments dropped because there was no space in the reassembly buffer.

meshRxSpeed

b/s

0

76800

Rate of data received by the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

meshTxDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the uplink interface because the outbound queue was full.

meshTxSpeed

b/s

0

76800

Current speed of data transmission over the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

serial0rxSpeed

b/s

0

100000000

Receive rate for the Serial 0 interface.

serial0txSpeed

b/s

0

100000000

Transmit rate for Serial 0 interface.

serial1rxSpeed

b/s

0

100000000

Receive rate for the Serial 1 interface.

serial1txSpeed

b/s

0

100000000

Transmit rate for Serial 1 interface.

sixTo4Translations

0

100000000

MAP-T metrics map6to4Translations.

uplinkRssi

dBm

-100

-50

Measured RSSI value of the primary RF uplink used for all RF uplinks.

uplinkRxDrops

drops/sec

0

1

Rate of packets received on the uplink interface, but then dropped because the inbound queue was full.

uplinkRxSpeed

b/s

0

3000000

Rate of data received by the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

uplinkTxDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the uplink interface because the outbound queue was full.

uplinkTxSpeed

b/s

0

500000

Current speed of data transmission over the uplink network interface, measured in bits per second, averaged over a short element-specific time period.

uptime

sec

0

31536000

Amount of time, in seconds, that the element has been running since last boot.

Metrics for VPN Interfaces

The following table describes the metrics for the VPN interfaces.

Table 12 Metrics for VPN Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for 3G Interfaces

The following table describes the metrics for 3G interfaces.

Table 13 Metrics for 3G Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for WiMAX Interfaces

The following table describes the metrics for WiMAX interfaces.

Table 14 Metrics for WiMAX Module Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for WPAN Interfaces

The following table describes the metrics for the WPAN interfaces.

Table 15 Metrics for WPAN Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for Management Interfaces

The following table describes the metrics for management interfaces.

Table 16 Metrics for Management Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for Ethernet Interfaces

The following table describes the metrics for Ethernet interfaces.

Table 17 Metrics for Ethernet Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.

Metrics for Serial Interfaces

The following table describes the metrics for the serial interfaces.

Table 18 Metrics for Serial Interfaces

Metric Name

Unit

Min

Max

Description

txSpeed

b/s

0

76800

Current speed of data transmission over the interface, measured in bits per second, averaged over a short element-specific time period.

txDrops

drops/sec

0

1

Rate of packets dropped while trying to transmit on the interface because the outbound queue was full.

txSpeed

b/s

0

76800

Rate of data received by the network interface, measured in bits per second, averaged over a short element-specific time period.