Before you start
This article explains how you can add these types of devices into your Viakoo configuration from the Viakoo CA Console. This functionality requires Agents version 4069 or greater. Talk to your Viakoo Support representative to make sure you have the right level of agents for IoT.
You should have identified the scope of your projects: all the recorders, management servers, workstations, and switches you want to see in Viakoo.
Topics in this section include:
- IoT Device Tracking
- Adding IoT Devices into Your Configuration
- Objection IDentifiers (OIDs)
- Current Limitations
This mechanism allows you to monitor the status of IP-based devices that may be in your area of responsibility but that aren’t necessarily part of your video surveillance or access control systems. For example, you may have alarm sensors, unmanaged switches, uninterruptible power-supplies(UPS), HVAC systems, et cetera, that have IP connections to your networks. These devices can now be monitored through the Viakoo system, and can be viewed alongside the rest of your infrastructure in the Viakoo Web Application.
The Viakoo Agents can be configured to support simple devices using PING or more sophisticated devices using SNMP protocols. The devices you configure will show up in “IoT Devices” tables in your site’s Details Tab, in “IoT Devices” Device Reports, and performance measures for IoT Devices can be plotted in Performance Tabs.
The simplest internet connected devices should respond to ICMP protocol (PING). This is a very simple call-response that confirms that the device is reachable on the network and is electrically responsive. It can be unreliable for two reasons:
- It is not guaranteed a response, so a single request can fail even if the device is actually present on the network and electrically alive.
- The device can be electrically responsive but not actually functioning properly.
This minimal test may be the only network test supported by the device. To reduce error rates, Viakoo will repeat the PING request six times by default. If the device responds to pings, then the status will be set to “Okay”. If it does not respond, it will show a status of “Failed”.
A ticket will open using the standard rules depending on priority. Specifically, this means:
- For NORMAL PING Devices, a warning level ticket will open after the Ticket Throttling Delay (defaults to 40 minutes) has elapsed.
- For CRITICAL PING Devices, a Critical level ticket will open immediately.
- For IGNORE PING Devices, no tickets will be created.
Additionally, the PING protocol collects network latency data which can be graphed in the Performance Tab for Viakoo Predictive Service customers. This can be used to identify problems affecting network performance if the device is alive and responding.
For devices that will respond to SNMP polling, the Viakoo Agent can test the SNMP port to better identify whether the device is functioning. Unlike PING, a response from the SNMP port indicates that the operating system on the device is working. If Viakoo Agents get a response from SNMP, then we know the device is functioning to some degree and the PING information is redundant. However, if the device is not responding to SNMP, we can still use the PING information to decide whether the device is electrically connected and is inoperable for some other reason (i.e., software is hung or overloaded).
Additionally, SNMP allows Viakoo to collect additional information from the device which can be used to better identify its configuration or measure its performance. Performance measures collected can also be used as testing Thresholds, which can create tickets in Viakoo based on device specific measures.
SNMP is a protocol which allows you to programmatically ask a device for information about itself. A device may have many different configuration attributes or performance parameters that can be asked for. A single request uses an Object IDentifier (OID) to specify what attribute or parameter is being requested. When configuring devices in the Viakoo Agents, you must also provide the set of OIDs you want to request from the device.
OID specifications are described in SNMP MIBs associated with a device. A given make and model of device may have one or more MIBs that document which OIDs are available for SNMP requests of the device. Viakoo needs the individual OIDs to collect and upload data from the device.
The process requires you to first choose a Viakoo Reader Agent (ViakooRA) to be responsible for collecting the new device(s) data. From there, you will get to a screen that shows you all the devices a given server is responsible for.
Clicking on this link brings up the "Add IoT Device" Pop-up
Selecting SNMPv2 or SNMPv3 probe type devices expands the fields appropriately as follows:
To add an IoT Device, you need the following:
- IP Address of the Device
- Name you want to appear associated with the device
- Probe Type [ PING | SNMPv2 | SNMPv3]
- [optional] Device Type, text associated with the device, such as “Sensor”, “Switch” or “UPC” which will allow you to sort and filter your IoT Devices.
- [optional] Description, text to be associated with the device.
- (SNMP fields)
- Read Community Name, which gives our agent read permissions on the device, and defaults to ‘public’.
- Port Number, which defaults to the standard SNMP port, 161.
- [optional] OID Collections, which defines one or more sets of OIDs to pull for this device.
- (SNMPv3 Only fields)
- Authentication Protocol - This could be MD5 or SHA1
- Authentication Password
- Privacy Password
Enter values for required and optional fields as appropriate and click “Save”.
Successfully added devices will show up in the “Current IoT Devices” list. Each device in the list has an “Edit” and “Delete” button. Use “Edit” to modify any of the fields. Use “Delete” to remove the device from this Viakoo RA.
NOTE: if you want to move a device from one RA to another RA at the same site, you have to first Delete from the RA you are currently associating it and then Add it to the other RA in your configuration.
Adding Multiple Devices at Once
The Viakoo CA has the ability to add multiple IoT devices at once. Simply go to the menu and select "IoT Devices" from the "Add Multiple:" section of the menu. This brings you to the bulk adding interface for IoT Devices:
Simply by entering values in the field of the first row, a second entry row will appear. As you enter values in the second row, a third row will appear. In this way, you can continue to add devices incrementally.
Importing a List from a CSV Spreadsheet File
Another useful way of adding several devices is to load them from a spreadsheet file in Comma Separated Values (CSV) format. Using standard spreadsheet software such as Microsoft Excel or Google Sheets, you can create a CSV file that contains the necessary information:
This is particularly useful because you may already have spreadsheets with devices and their IPs, making it a simple step to convert to the necessary import format. Moreover, if you make a mistake, it is easy to correct and re-import a corrected list of devices. The Viakoo CA will only support one device per IP address so reimporting the same device will overwrite the existing entry. If this entry is a correction, then the device in question will be corrected.
Note: it is important the headers and format of your import file are consistent with what the CA expects or it will not work as intended. Make sure your column headers match and are in the order of the "Add Multiple IoT Devices" template.
Importing this modified device CSV file will yield the following:
Notice importing the file still leaves the window in "Edit" mode allowing you to add more devices or change entries of existing entries before saving.
When you save your entries, Viakoo CA will check each device to make sure it is accessible by the the Viakoo RA you assigned the device to. Devices that are successfully reached by their RAs will get added. Devices that fail to respond will be indicated. You can choose to return to the editing mode to correct any issues associated with failed devices or add more devices. When you have completed adding devices, you can return to the home screen to view your configuration:
You can modify any device in the list by clicking on the "Settings" icon (). You can also return to the "Add Multiplle: Iot Devices" page and use the CSV import to modify devices that already exist in the configuration for an RA.
When importing, the service will use the IP address to determine whether a new device is being added or an old device is being modified. If you modify some of the fields in your csv but leave the IP address the same, the service will apply those modifications to the device with that IP address. If you change the IP address, then the service will create a new device with that configuration.
SNMP devices have additional support that makes monitoring them more useful than simple PING devices. The first is that the SNMP mechanisms inside the device can already tell us whether the device is functioning at a logical level where PING is merely telling us whether the device is electrically alive and connected to the network. More importantly, the SNMP support in a device can give the Viakoo system more useful, device-specific information that can be helpful in troubleshooting issues with the device and related applications. However, to collect of SNMP values from devices, users first have to tell Viakoo what to collect and how Viakoo should interpret the data.
To make best use of the SNMP support in Viakoo, it will be useful to read up on SNMP, MIBs and OIDs. There are numerous SNMP MIB readers that are available and device manfacturers will have information about MIBS supported by devices.
OIDs as the Mechanism to Get Data
Device manufacturers will have one or more SNMP MIBs that define the associated SNMP OID’s and their syntax that a device supports. Users will need to specify OIDs in an OID Table in the CA. Then, when defining an SNMP device, you can specify which collections of OIDs to use for a given device.
Since the Viakoo system is only reading information from the configuration and not modifying it, we will only use SNMP Get requests. The get request uses the following to make requests from the device:
- the IP Address of the device
- the SNMP Port Number to contact the device,
- a Community String to identify what permissions the request has
- and the OID to determine what information needs to be returned
- Syntax (format) of the response value
- Name you would like Viakoo to use in displaying the value
Finding OID Entry Information (OID and Syntax) from MIBs
There is a wide variety of MIBS ranging from industry standard MIBs defined by certain industries to the numerous device manufacturers and their individual MIBs for each class and model of device. To parse these MIBs, you can use any of a number of MIB Parsers, many offered for free or have a free trial available. Here’s and example of one from iReasoning.
MIB browsers allow you to parse MIB files or connect to a device and explore the MIBs and OIDs the device supports directly. Your device manufacturer is likely to have the necessary MIBs available through a support website. There are also repositories of industry standard and a large variety of manufacturers MIBs.
For example, if you wanted to turn on some capabilities of your wireless access point device, you could connect directly to the device with a MIB browser and load the MIB, as seen below:
The OID for the sysDescr, is “188.8.131.52.184.108.40.206.0” and its syntax is OCTET STRING. It is a property of the device so you would consider it an “ATTRIBUTE.” You can also choose to use sysUpTime which returns “TIMETICKS” and can be a “PERFORMANCE” value as well as “sysName” which is another OCTET STRING “ATTRIBUTE”.
OID Entries in the Viakoo Service
To specify collection of arbitrary SNMP values from devices, users first have to add the associated SNMP OID’s to an OID Table in the CA. Then, when defining an SNMP device, you can specify which collections of OIDs to use for a given device.
For the Viakoo Agents to collect and format the requests so that the responses can be meaningfully used in the Viakoo service, it needs to know the following for each SNMP device:
- What OIDs do you want to collect from each device,
- What is the syntax of the associated messages for each OID,
- What name do you want to apply to the parameter for each OID,
- Whether the value is an attribute (e.g., serial number) or a performance value (e.g., CPU load).
- if it is a performance parameter, what are the units of the value.
OIDs represent a point in an overall, cross-industry hierarchy, which means each OID can be a long and complex sequence of numbers. To reduce errors and duplication, Viakoo Agents offer a simple way of sharing them between devices, the OID Table, and a simplified way of associating them with devices, OID Collections.
OID Tables & OID Collections
To allow users to share OID entries, users specify OIDs in a shared OID Table. Users add an OID entry in the OID table specifying the OID, the names associated with the values collected, whether its an attribute or performance parameter, its syntax and, if it is a performance parameter, its units so that it can be properly rendered in the Viakoo UI.
Each MIB may have definitions for one or more OIDs, so make sure to include all of the ones you want to collect. Moreover, devices can have multiple MIBs that apply to them. For example, they may comply with industry standard MIBs for common system or network information, but also have company and model specific MIBs that provide unique and differentiating features. You may have devices of different models that share the same industry standard or manufacture MIBs, but have different model specific MIBs.
To save effort and reduce mistakes users specify an “OID Collection” label for each OID entry in the table. This associates the OID entry with a collection, which may include other previously defined OIDs. Using the same Collection label with more than one OID Entry allows you to group them together, so for example you can make a collection of OIDs grouped by the MIB they came from, or any other identifying feature you wish to connect them by. Then, when users are specifying SNMP devices, they simply need to choose the same OID Collection label and all of the OID entries associated with that Collection will be retrieved for that device. This will save users from having to re-enter OIDs for each device, and allows them to use the same collection of OIDs for similar devices that share similar OIDs. This will help to ensure that similar IoT devices will collect the same attributes and performance values and that they will display in the same way in the Viakoo UI after they are collected.
Adding OIDs into Your Configuration
To Add, View, Modify or Remove entries in the OID table, go to the menu and click on the “OID Entries”:
This interface gives you two options to add OID entries:
- You can add them individually, one at a time by clicking on “Add New OID Entry” ,
- You can load them from a CSV file.
To add an OID, you need the following:
- OID Collection - label to associate a collection of multiple OIDs
- OID - specific OID entry for the parameter you want collected (refer to MIB)
- Object Descriptor - label for this specific OID
- Syntax - structure of the returning data associated with this OID (refer to MIB)
- Attribute/Performance - Is this OID a configuration attribute that seldom changes or is it a performance value that you would like to see trended over time?
- (Performance Only)
- Performance Units - what are the units associated with the performance values so they can be plotted usefully.
To get the correct values for the OID, Syntax and Performance Units, refer to the device’s MIB.
After entering the fields, click “Save” to have the OID entry added to the OID Table.
Importing OID Entries from CSV
If you have a lot of OIDs to enter, it may be useful creating your OID table in a spreadsheet and saving the output to a CSV file. Then use the “Import OIDs from CSV” button to load the list of OIDs into the table on your Viakoo CA.
To create a spreadsheet file in the correct format, you may first want to “Export OIDs to CSV”. This will get you a file with the correct column headers and in the right format.
Adding OID Collections to IoT Devices
Once your OIDs are loaded into the CA you may add them to any new or existing SNMP-based IoT Devices. To add them to an existing device simply click the EDIT button in the Action column for that device. From the ADD/EDIT dialog you can choose any of the OID Collections you defined. For example, in the image below you could select the “myMib1” collection, the “System” collection, or if your device required you could Ctrl + Click to include both of them.
In this example, the new device uses the “System” collection, which includes the sysDescr, sysName and sysUpTime OIDs.
IoT Devices in Viakoo Web UI
After you finish configuring your devices and trigger an initial send, Preemptive and Predictive customers will see their devices in the the “Details” tab under the “IoT Devices” accordion fold. Predictive customers will also see “IoT Devices” show up as an option in the “Performance” tab with the various performance values graphable over time.
- Users need to upgrade to versions of the agents that support IoT devices. This would be versions 4069 and greater. Contact Viakoo Support to upgrade your infrastructure to the necessary agents.
- In the first release, Name, IP Address, Mac Address, Device Type, and Description are the only attributes visible in the “IoT Devices” tables and device reports. To verify that other attributes you may define are uploading and currently working properly, you can view them in the device’s events stream on the Device Overview pane.
- If you would like Mac Address to display in the “IoT Devices” table, make sure the Object Descriptor for your OID Entry is set to “macAddress”.
- Scaling is not yet configured into the Performance data for IoT Devices. For example, TimeTicks may be in units that are fractions or multiples of a second. However, the current mechanism will assume that each time tick equals one second.
If you have any questions concerning adding your IoT Devices into Viakoo, please reach out to us through the live-chat feature or contact us at firstname.lastname@example.org.
We love hearing from you!
1 (855) 585-3400