Configuration of Management Events¶
The management events interface in IoT Connector provides an asynchronous stream of events that occur on the device. For more information on the actual JSON message format refer to the Management Events schema here. There are five different types of Management Events supported in IoT Connector.
Tip
All events can be configured except the firmwareUpdateProgress event.
Heartbeat¶
Heartbeat event is a periodic aysnchronous event sent from the device on the configured management events endpoint. The data payload sent is in JSON format. The event at a high level contains four sections as listed below. The frequency of the heartbeats and the parameters to be sent in each section of the heartbeat can be configured using the set_config command
Configuring Radio Control parameters in heartbeat¶
The Radio control section in the heartbeat contain the operational statistics of Radio Control. Table below lists the parameters supported in radio_control heartbeat.
Parameters in radio control section of the heartbeat¶ Field
Description
Default
ANTENNAS
Antenna connection status. Example: Antenna 1 is connected / disconnected.
Enabled
RADIO_ACTIVITY
Current Inventory State. Example: Radio Activity is active / inactive.
Enabled
RADIO_CONNECTION
Current radio connection status. Example: Radio is connected / disconnected.
Enabled
CPU
Radio Control application CPU utilization. Example CPU % between >= 0 and <= 100.
Enabled
RAM
Radio Control application RAM utilization. Example RAM % between >= 0 and <= 100.
Enabled
UPTIME
Radio Control Application uptime (days:hours:min).
Enabled
NUM_ERRORS
Number of Errors generated by Radio Control.
Enabled
NUM_WARNINGS
Number of Warnings generated by Radio Control.
Enabled
NUM_TAG_READS
Total number of Tags Read.
Enabled
NUM_TAG_READS_PER_ANTENNA
Number of Tags Read Per Antenna.
Enabled
NUM_DATA_MESSAGES_TXED
Number of Tag Data messages transferred.
Enabled
NUM_RADIO_PACKETS_RXED
Number of Radio Packets received.
Enabled
STATUS
Radio Control running status. Example: Radio control is running / stopped.
Enabled
The set of parameters to be included in the radio_control section of the heartbeat can be configured using the payload below in set_config command. Only the fields/parameters included in the list while configuring will be sent in the heartbeat.
{ "READER-GATEWAY": { "managementEventConfig": { "heartbeat": { "fields": { "radio_control": [ "ANTENNAS", "RADIO_ACTIVITY", "RADIO_CONNECTION", "CPU", "RAM", "UPTIME", "NUM_ERRORS", "NUM_WARNINGS", "NUM_TAG_READS", "NUM_TAG_READS_PER_ANTENNA", "NUM_DATA_MESSAGES_TXED", "NUM_RADIO_PACKETS_RXED", "STATUS" ] } } } } }
Configuring Reader Gateway parameters in heartbeat¶
The Reader Gateway section in the heartbeat contain the operational statistics of Reader Gateway. Table below lists the parameters supported in reader_gateway heartbeat.
Parameters in reader gateway section of the heartbeat¶ Field
Description
DEFAULT
NUM_DATA_MESSAGES_RXED
Number of Data Events Received.
Enabled
NUM_MANAGEMENT_EVENTS_TXED
Number of Management Events Sent to Cloud.
Enabled
NUM_DATA_MESSAGES_TXED
Number of Data Events sent to cloud.
Enabled
NUM_DATA_MESSAGES_RETAINED
Number of Data Events Retained.
Enabled
NUM_DATA_MESSAGES_DROPPED
Number of Data Events Dropped
Enabled
CPU
Reader Gateway application CPU utilization. Example CPU % between >= 0 and <= 100.
Enabled
RAM
Reader Gateway application RAM utilization. Example RAM % between >= 0 and <= 100.
Enabled
UPTIME
Reader Gateway Application uptime (days:hours:min).
Enabled
NUM_ERRORS
Number of Errors generated by Reader Gateway.
Enabled
NUM_WARNINGS
Number of Warnings generated by Reader Gateway.
Enabled
INTERFACE_CONNECTION_STATUS
Currently Tag data interface connection status.
Enabled
The set of parameters to be included in the reader_gateway section of the heartbeat can be configured using the payload below in set_config command. Only the fields/parameters included in the list while configuring will be sent in the heartbeat.
{ "READER-GATEWAY": { "managementEventConfig": { "heartbeat": { "fields": { "reader_gateway": [ "NUM_DATA_MESSAGES_RXED", "NUM_MANAGEMENT_EVENTS_TXED", "NUM_DATA_MESSAGES_TXED", "NUM_DATA_MESSAGES_RETAINED", "NUM_DATA_MESSAGES_DROPPED", "CPU", "RAM", "UPTIME", "NUM_ERRORS", "NUM_WARNINGS", "INTERFACE_CONNECTION_STATUS" ] } } } } }
Configuring System parameters in heartbeat¶
The system section in the heartbeat contain the operational statistics of the reader as a whole. Table below lists the parameters supported in system heartbeat.
Parameters in system section of the heartbeat¶ Field
Description
DEFAULT
CPU
Total CPU utilization.
Enabled
FLASH
Total Flash utilization.
Enabled
NTP
NTP synchronous status.
Enabled
RAM
Total RAM utilization.
Enabled
SYSTEMTIME
Reader System Time.
Enabled
TEMPERATURE
Reader temperature sensor readings.
Enabled
UPTIME
Reader uptime (%d days hours:min:sec)
Enabled
GPO
Current status of Reader GPO Pins.
Enabled
GPI
Current status of Reader GPI Pins.
Enabled
POWER_NEGOTIATION
Current status of Power Negotiation.
Enabled
POWER_SOURCE
Current power source, where reader is connected.
Enabled
System heartbeat event can be configured with the payload in set_config command. Only the fields/parameters included in the list while configuring will be sent in the heartbeat.
{ "READER-GATEWAY": { "managementEventConfig": { "heartbeat": { "fields": { "system": [ "CPU", "FLASH", "NTP", "RAM", "SYSTEMTIME", "TEMPERATURE", "UPTIME", "GPO", "GPI", "POWER_NEGOTIATION", "POWER_SOURCE" ] } } } } }
Configuring User Apps parameters in heartbeat¶
The User Apps section in the heartbeat contain the operational statistics of the user apps. Table below lists the parameters supported in User Apps heartbeat.
Parameters in user app section of the heartbeat¶ Field
Description
DEFAULT
STATUS
User Application running status.
Enabled
CPU
User application CPU utilization.
Enabled
RAM
User application RAM utilization
Enabled
UPTIME
User Application uptime (days:hours:min)
Enabled
NUM_DATA_MESSAGES_RXED
Number of Data Events Received.
Enabled
NUM_DATA_MESSAGES_TXED
Number of Data Events sent to Reader Gateway.
Enabled
INCOMING_DATA_BUFFER_PERCENTAGE_REMAINING
Percentage of Buffer to be Read.
Enabled
OUTGOING_DATA_BUFFER_PERCENTAGE_REMAINING
Percentage of Buffer to be Sent.
Enabled
User Apps heartbeat event can be configured with below the payload in set_config. Only the fields/parameters included in the list while configuring will be sent in the heartbeat.
{ "READER-GATEWAY": { "managementEventConfig": { "heartbeat": { "fields": { "userapps": [ "STATUS", "CPU", "RAM", "UPTIME", "NUM_DATA_MESSAGES_RXED", "NUM_DATA_MESSAGES_TXED", "INCOMING_DATA_BUFFER_PERCENTAGE_REMAINING", "OUTGOING_DATA_BUFFER_PERCENTAGE_REMAINING" ] } } } } }
Configuring Heartbeat Interval¶
By default heartbeats are sent onece every 60 seconds. Heartbeat interval can be configured using the below payload in set_config command.
{ "READER-GATEWAY": { "managementEventConfig": { "heartbeat": { "interval": 60 } } } }
Sample Heartbeat¶
{ "component": "RG", "data": { "radio_control": { "antennas": { "1": "connected", "2": "disconnected", "3": "disconnected", "4": "disconnected" }, "cpu": 0.4, "numDataMessagesTxed": 39, "numErrors": 3, "numRadioPacketsRxed": 6119, "numTagReads": 39, "numTagReadsPerAntenna": { "1": 39, "2": 0, "3": 0, "4": 0 }, "numWarnings": 0, "radioActivity": "active", "radioConnection": "connected", "ram": 2.1, "status": "running", "uptime": "00:16:01" }, "reader_gateway": { "cpu": 182.5, "dataPathStatistics": [ { "numDataMessagesDropped": 0, "numDataMessagesRetained": 0, "numDataMessagesRxed": 0, "numDataMessagesTxed": 39 } ], "interfaceConnectionStatus": { "data": [ { "connectionError": "", "connectionStatus": "connected", "description": "mqtt", "interface": "mqtt" } ] }, "numDataMessagesRxedFromExt": 39, "numErrors": 4, "numManagementEventsTxed": 19, "numWarnings": 0, "ram": 2.9, "uptime": "0:16:01" }, "system": { "GPI": { "1": "HIGH", "2": "HIGH", "3": "HIGH", "4": "HIGH" }, "GPO": { "1": "LOW", "2": "LOW", "3": "LOW", "4": "LOW" }, "cpu": { "system": 8, "user": 2 }, "flash": { "platform": { "free": 12443648, "total": 33554432, "used": 21110784 }, "readerConfig": { "free": 3006464, "total": 4194304, "used": 1187840 }, "readerData": { "free": 64118784, "total": 67108864, "used": 2990080 }, "rootFileSystem": { "free": 27488256, "total": 192937984, "used": 165449728 } }, "ntp": "NOT_CONFIGURED", "powerNegotiation": "DISABLED", "powerSource": "DC", "ram": { "free": 117518336, "total": 252334080, "used": 134815744 }, "systemtime": "2022-11-11T12:40:23.401+0530", "temperature": { "ambient": 26, "pa": 26 }, "uptime": "0:40:19" }, "userapps": [ { "cpu": 0.2, "incomingDataBufferPercentageRemaining": 99, "name": "sample", "numDataMessagesRxed": 0, "numDataMessagesTxed": 0, "outgoingDataBufferPercentageRemaining": 99, "ram": 4.9, "status": "running", "uptime": "0:00:20" } ] }, "eventNum": 20, "timestamp": "2022-11-11T12:41:08.443+0530", "type": "heartbeat" }
GPI Events¶
IoT Connector can send an event on the management interface on each tranistion of the GPI line. GPI Events can be enabled or disabled, using the below Payload in set_config API.
{ "READER-GATEWAY": { "managementEventConfig": { "gpiEvents": true } } }
Sample GPI Event¶
{ "component": "RG", "data": { "pin": 1, "state": "HIGH" }, "eventNum": 56, "timestamp": "2022-11-10T12:35:32.062+0000", "type": "gpi" }
GPO Events¶
IoT Connector can send an event on the management interface to tranistion the GPO line.
Sample GPO Event¶
{ "component": "RG", "data": { "pin": 1, "state": "HIGH" }, "eventNum": 56, "timestamp": "2022-11-10T12:35:32.062+0000", "type": "gpo" }
Userapp Events¶
User App Events can be used by the DA application to send any asynchronous events to the management events interface.
See also
User App Events can be enabled or disabled, using the below Payload in set_config API.
{ "READER-GATEWAY": { "managementEventConfig": { "userappEvents": true } } }
Sample User App Event¶
If the User App Events are enabled, we get a below response as part of management events whenever User App Events are triggered. The field component indicates the name of the user application that is sending the event and data contains the payload of the event sent from the DA application.
{ "component": "sample", "data": { "event": "0" }, "eventNum": 56, "timestamp": "2022-11-10T12:35:32.062+0000", "type": "userapp" }
Error Events¶
IoT Connector can be configured to monitor a set of parameters and generate error events when the monitored parameter exceeds the configured threshold. The frequency at which the error event should be reset can also be configured.
Parameters that can be monitored to generate error events.¶ Parameter
Description
Sample Event
Antenna
CPU
{“data”:{“message”: “CPU utilization @ <percent>%”}, “type”: “error”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
Database
Flash
{“data”:{“message”: “FLASH utilization @ <percent>%”}, “type”: “error”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
NTP
{“data”:{“message”: “NTP synchronization failed offset <offset> and reach <reach>”}, “type”: “error”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
Radio
Radio Control
RAM
{“data”:{“message”: “CPU utilization @ 90%”}, “type”: “error”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
Reader Gateway
userApp
IoT Connectorif the user installed DA app stops or does not send heartbeats.All DA apps are monitored by the reader gateway using the internal heartbeats.When the internal heartbeats are not received by the reader gateway for the configured amount of time then an error event is sent.{“data”:{“message”: “userapp <name> down. no heartbeat sine <number> seconds.”}, “type”: “error”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
..important:: The userApp events are not sent by IOT Connector if the app is stopped by issuing a stop command on the IoTConnector interface.
Tip
The above error events can be configured each separately or all together, Based on the need. If absent, default values will be taken.
Below example error event configuration can be used as a payload in set_config API.
{ "READER-GATEWAY": { "managementEventConfig": { "errors": { "antenna": false, "cpu": { "reportIntervalInSec": 1800, "threshold": 90 }, "database": true, "flash": { "reportIntervalInSec": 1800, "threshold": 90 }, "ntp": true, "radio": true, "radio_control": false, "ram": { "reportIntervalInSec": 1800, "threshold": 90 }, "reader_gateway": true, "userApp": { "reportIntervalInSec": 1800, "threshold": 120 } } } } }
Warning Events¶
User can enable or disable few of the warning events, also can modify the threshold of other warning events, like when the warning event should get reported.
Parameters that can be monitored to generate error events.¶ Parameter
Description
Sample Event
CPU
{“data”:{“message”: “CPU utilization @<number>%”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
Database
Flash
{“data”:{“message”: “FLASH utilization @<number>%”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
NTP
{“data”:{“message”: “NTP synchronization failed offset <offset> and reach <reach>”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
Radio API
{“data”:{“message”: “API Error: <warning_msg>”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
Radio Control
{“data”:{“message”: “<warning>”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
RAM
{“data”:{“message”: “RAM utilization @<number>%”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RC”, “eventNum”: 1}
Reader Gateway
Currently no warning events are sent for Reader Gateway.
Temperature
userApp
IoT Connectorif the user installed DA app stops or does not send heartbeats.All DA apps are monitored by the reader gateway using the internal heartbeats.When the internal heartbeats are not received by the reader gateway for the configured amount of time then an error event is sent.{“data”:{“message”: “userapp <name> down. no heartbeat sine <number> seconds.”}, “type”: “warning”, “timestamp”: “2019-08-24T14:15:22Z”, “component”: “RG”, “eventNum”: 1}
..important:: The userApp events are not sent by IOT Connector if the app is stopped by issuing a stop command on the IoTConnector interface.
..important:: The above warning events can be configured each separately or all together, Based on the need. If absent, default values will be taken.
Below example warning event Configuration can be used as a payload in set_config API.
{ "READER-GATEWAY": { "managementEventConfig": { "warnings": { "cpu": { "reportIntervalInSec": 1800, "threshold": 80 }, "database": true, "flash": { "reportIntervalInSec": 1800, "threshold": 80 }, "ntp": true, "radio_api": true, "radio_control": true, "ram": { "reportIntervalInSec": 1800, "threshold": 80 }, "reader_gateway": true, "temperature": { "ambient": 75, "pa": 105 }, "userApp": { "reportIntervalInSec": 1800, "threshold": 60 } } } } }
Firmware Update Progress Events¶
These events are sent when a firmware update is initiated. IoTConnector sends this event periodically untill the firmare update is complete. Below is a sample firmware update progress event.
{ "type": "firmwareUpdateProgress", "timestamp": "2019-08-24T14:15:22Z", "component": "RG", "eventNum": 1, "data": { "status": "started", "imageDownloadProgress": 10, "overallUpdateProgress": 1, "updateProgressDetails": { "os": 1, "rootFileSystem": 1, "applications": 3, "radioFirmware": 1, "platform": 1 } } }