Getting Started

Introduction to the Device Diagnostics API

Contents


The Device Diagnostics API lets you troubleshoot the connectivity of IoT devices. You can use the API with all Open Development certified IoT devices, for example routers, modems, vending machines with embedded modules, etc. However certain API functions work only with devices that at specifically certified for LwM2M protocol for Diagnostics as specified by the Open Development certification program. Device certification for LwM2M Diagnostics is now a mandatory requirement for all devices that support the LwM2M protocol and are submitted for certification. Some devices that have been certified through the Open Development program in the past may not have been certified for LwM2M Diagnostics then. To access the specific API functions that depend upon LwM2M protocol, such devices must be re-certified specifically for LwM2M Diagnostics. Note that the LwM2M protocol client typically resides and executes in the baseband processor of the radio (RF) communications module part of the IOT device. So, as long as the radio (RF) communications module inside an IOT device (such as a OEM router, gateway device, etc.) submitted for certification is already certified for LwM2M Diagnostics, there is no re-certification for LwM2M necessary for the device itself.


You cannot use the API to perform diagnostics on non-IoT devices such as Smartphones, Feature Phones, Tablets, Laptops and Netbooks.


Using the API, you can verify all information about the device including:

  • Make and model and its Verizon certification SKUv Verizon data and SMS plans and other features and subscriptions of the device
  • Device identifiers associated with the device such as device hardware IMEI, ICCID of the SIM in the device, and its mobile directory number (MDN or MSISDN).
  • Provisioning status (e.g. Active, Pending Activation, Deactive, Suspended) of the device on the Verizon network
  • Connectivity status of the device such as whether the device is Connected for data traffic, the IP address
  • Roaming status of the device with Country of roaming, Serving MNC (Mobile Network Code) and MCC (Mobile Country Code)
  • Billing cycle of the device and its current bill cycle usage for data traffic as well as SMS messages
  • Last known location of the Device*
  • Current software version of the device*
  • Type of IOT device** (e.g. smart meter)
  • Current hardware and communications firmware version of device**
  • Device Serial Number**
  • Available Power Sources**
  • Battery Level and Status**
  • Available Networks (e.g. LTE, CDMA2000) to connect**
  • Network Bearer (e.g. LTE) device is attached to**
  • RF Signal Strength**
  • RF Link Quality**
  • Cell Tower (Cell ID) device is attached to**
  • Verizon APN (Access Point Nodes) list where the device traffic is routed (e.g. Enterprise APN, Public Internet APN, etc.)**
  • Device Sleep Mode Timer Values (e.g. PSM and Active Timers for Power Save Mode sleep cycle, and eDRX Timer and Paging Time Window for eDRX paging/sleep cycle)**


Live Stream RF data from the device**

  • RF Signal Strength
  • RF Link Quality
  • Cell Tower (Cell ID) where the device is attached to the Verizon network
  • Network technology used by the device to connect to the Verizon network (e.g. 3G, EVDO, LTE, NB-IOT), etc.

*Dependent on a Location and Software Management subscriptions being available for the account. Please see section “About Subscriptions needed for Diagnostics API”
**Dependent on device being certified for LwM2M Diagnostics under Verizon Open Development certification program.

About Subscriptions Needed for Diagnostics API

Thingspace Services Subscriptions provide access to certain services offered by Thingspace, including Location, Software Management, Security and Diagnostics. While basic features such as a Data plan or an SMS plan are necessary for device connectivity and operation, Services Subscriptions are a value-adding option that must be purchased in addition to connectivity plans. The available Diagnostics APIs can be categorized as either needing some subscription or not needing any subscriptions:

Diagnostics APIs not needing any Subscription:

The Get Device Diagnostic Information and Get Device Extended Diagnostic Information APIs do not need any Service Subscription. However if subscriptions for Location and Software Management Services are purchased or if a subscription that bundles these services (Bundle Subscription) is purchased, the Get Device Extended Diagnostic Information API will return additional Location and device Software (firmware) information in its response. Furthermore, with a Bundle Subscription purchased, if the device being diagnosed is certified for LwM2M protocol, this API will also return RF information about the device (i.e., RF Signal Strength and Link Quality)

Diagnostics APIs needing a Subscription:

A Bundle Subscription is needed for the following APIs that are used for the RF Live Streaming features (see section About RF Live Streaming):

Get Diagnostics Subscriptions
Start Diagnostics Observation
Stop Diagnostics Observation
Get Diagnostics History Data
Get Diagnostics Settings
Register Diagnostics Callbacks Listener
Get Diagnostics Callback
Delete Diagnostics Callback

About RF Live Streaming

The RF Live Streaming feature makes it possible to observe and monitor in real time the RF performance of an IOT device. This is particularly useful for 4G and 5G IOT devices that are capable of sleeping for long durations (e.g., several hours, days, or even months) in order to conserve battery power. When asleep, such devices are not reachable from the network for any data communication thus making it difficult to know whether such devices are really connecting to the network per their scheduled wakeup cycle to perform IOT tasks such a reporting sensor reading, location etc. For example, devices equipped with 4G LTE M (Category M) RF modules can show this behavior based on their sleep cycle settings. The device will sleep for its configured duration, then wake up and report some information, then wait for some time looking for any incoming data from the network and then go back to sleep again.

The RF live streaming APIs below all work together to start the monitoring of a device’s RF parameters for a specifiable time window: RF Signal Strength, RF Link Quality, Cell Tower ID and the Network Bearer type (e.g. 3G, EVDO, LTE etc.). The parameters being monitored are returned to the calling application at the registered callback URL. The application can also read all current diagnostic monitoring settings (i.e. frequency of RF information reporting and the overall time duration of the monitoring window), stop monitoring and reset the monitoring settings as well managing the callbacks. There is also an API that allows retrieving historical monitoring data from past RF monitoring events. More details on each API are provided in the API listings.

Get Diagnostics Subscriptions
Start Diagnostics Observation
Stop Diagnostics Observation
Get Diagnostics History Data
Get Diagnostics Settings
Register Diagnostics Callbacks Listener
Get Diagnostics Callback
Delete Diagnostics Callback

About RF Parameters that can be Streamed

Signal Strength: This parameter reports the strength of the RF signal as received at the device. Signal strength is reported in units of dBm (milliDecibels), which is the power ratio in decibels of the received signal per milliwatt. A signal of -65 dBm or better would be considered excellent and a signal worse than -85dBm would be considered low. At -112dBm would be considered very poor possibly causing the connection to drop. If the signal is at around – 75 to -85 dBm, it would be considered average (somewhat akin to 4 bars on a cell phone).

Link Quality: This parameter reports the quality of the radio link between the IOT device and the cell tower. This parameter is reported in units of dB (Decibels) and provides a sense of how noisy the RF environment is in which the RF signal from the cell tower is being transmitted. For example, a device could have a poor connection if Link Quality was poor ( < -11 dB), even if the Signal Strength was good (e.g. -80 dBm). A Link Quality > -5 dB is considered excellent. A Link Quality of -6 to -10 range would be considered good to average.

Network Bearer: The is the type of technology that a IOT device uses to attach to the network. For example a 4G capable IOT device would typically attach using LTE as the bearer. However in some situations the device may fall back to using a slower connection provided by 3G (CDMA/EVDO aka CDMA2000 bearer). Such situations can occur in real time as the device moves and the RF conditions around it change causing a fallback to CDMA2000 or regaining the LTE bearer. When troubleshooting device, it can be useful to know if this is happening with the IOT device.

Cell ID: This parameter identifies the cell tower to which the device is attached. Note that this does not directly provide the geo-location of the device or the cell tower itself. This is useful for trouble-shooting the placement of a device (such as a vending kiosk or a router). If there are too many rapid changes in the cell tower to which the device attaches to it could indicate that a device may be residing on the boundary of coverage areas provided by different towers and this could be impacting its communication to the network. The Cell ID is returned as a numeric (Integer) value.

To get started

You can follow these general steps to get started with the Device Diagnostics API:

  1. Read the documentation to understand what capabilities are available in the API.
  2. If you would like to use the LwM2M streaming APIs (see About RF Live Streaming section) and also have richer device diagnostic information provided in the Get Device Extended Diagnostic Information API, two criteria must be met. Please contact your Verizon account representative for more information on these criteria: a. Your IOT devices must use RF communication modules that are certified for LwM2M Diagnostics through the Verizon Open Development program b. You must purchase a Bundle Subscription.
  3. Register on the ThingSpace Develop site to get access to the API.
  4. Sign up for Connectivity Management login credentials.
  5. Once you have both a ThingSpace account and a Connectivity Management account, try the API requests in the API Console, and then start coding your own application.