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:
Live Stream RF data from the device**
*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.
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:
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)
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
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. LTE). 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
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.
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.
You can follow these general steps to get started with the Device Diagnostics API: