# node-red-contrib-gapit-snmp The *gapit-snmp* Node-RED node queries all the OIDs listed in a *Gapit code* JSON structure using SNMP get. The *Gapit code* structures and names data, preparing it for insertion into a database. The complementary *gapit-results-to-influx-batch* node transforms the output of this node to the format required by the *influx batch* node (from `node-red-contrib-influxdb`). So to fetch a standard set of data and insert it into InfluxDB, a flow like this is all you need: ![Example Flow](images/example_flow.png) Here's a fragment of a *Gapit code* for UPSes: ```json { "objects": [ { "group_name": "Battery", "read_priority": 0, "group": [ { "description": "Battery status", "byte_type": "INT", "address": "1.3.6.1.2.1.33.1.2.1.0", "scaling_factor": 1, "unit": "1=Unknown, 2=Ok, 3=Low, 4=Depleted" }, { "description": "Seconds on battery", "byte_type": "INT", "address": "1.3.6.1.2.1.33.1.2.2.0", "scaling_factor": 1, "unit": "sec" } ] } ] } ``` This would get inserted into a InfluxDB measurement called "Battery" (from the *group_name* field), with fields called "Battery status" and "Seconds on battery" (from the *description* field). The output of `gapit-snmp`, which is parsed by `gapit-results-to-influx-batch`, is `msg.gapit_results`. This has the same structure as the *Gapit code*, except with `.value` added for each OID. ### Other destinations/databases? If you want to insert the data into a different database, you can parse the `msg.gapit_results` structure, and transform it into the required format. ### gapit-results-to-influx-batch node The gapit-results-to-influx-batch node is packaged as a separate module, `node-red-contrib-gapit-results`, which is automatically installed with this module. It is a packaged as a separate module to enable sharing with other nodes which yield results in the same `msg.gapit_results` structure. The `node-red-contrib-gapit-results` module may be expanded with new nodes in the future. ## Installation ### Install from the Node-RED interface Install using *Manage palette* -> *Install*. You need to refresh your browser for the `gapit-results-to-influx-batch` node to be available in the node palette. If you are running Node-RED 1.2 or older, you will need to restart Node-RED for it to be visible. If you are using an ancient version of NPM, you will need to manually install `node-red-contrib-gapit-results`. ### Install using the command line Run the following command in your Node-RED user directory - typically `~/.node-red` npm install @gapit/node-red-contrib-gapit-snmp and then restart Node-RED. ## Usage ### Example flow This is the JSON for the flow pictured above. ```json [{"id":"18636adc.5ff2c5","type":"tab","label":"Flow 1","disabled":false,"info":""},{"id":"e9fbc788.fe6a28","type":"inject","z":"18636adc.5ff2c5","name":"inject msg.ts","props":[{"p":"ts","v":"","vt":"date"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","x":170,"y":180,"wires":[["2216c2a5.f7ae6e"]]},{"id":"2216c2a5.f7ae6e","type":"gapit-snmp","z":"18636adc.5ff2c5","host":"192.168.122.52","community":"eaton-9PX-partial-walk","version":"1","tagname_device_name":"devname","tagvalue_device_name":"ups1","minion_ids":"","custom_tags":"{\"floor\":\"1\",\"room\":\"101\"}","gapit_code":"{\"objects\":[{\"group_name\":\"Battery\",\"read_priority\":20,\"next_read\":0,\"group\":[{\"description\":\"Flarb\",\"value\":\"f\",\"byte_type\":\"INT\",\"address\":\"1.3.6.1.4.1.534.1.4.7.0\",\"scaling_factor\":1,\"unit\":\"1=Unknow, 2=Ok, 3=Low, 4=Depleted\"},{\"description\":\"Flarb the Second\",\"value\":\"f\",\"byte_type\":\"INT\",\"address\":\"1.3.6.1.4.1.534.1.2.1.0\",\"scaling_factor\":1,\"unit\":\"1=Unknow, 2=Ok, 3=Low, 4=Depleted\"}]}]}","scaling":"general","skip_nonexistent_oids":true,"remove_novalue_items_from_gapit_results":true,"timeout":5,"name":"","x":400,"y":180,"wires":[["48874c94.c9c534"]]},{"id":"48874c94.c9c534","type":"gapit-results-to-influx-batch","z":"18636adc.5ff2c5","use_timestamp_from_msg":true,"timestamp_property":"ts","name":"","x":680,"y":180,"wires":[["f23c3400.74ae98"]]},{"id":"f23c3400.74ae98","type":"influxdb batch","z":"18636adc.5ff2c5","influxdb":"2aa4b01d.f511f","precision":"ms","retentionPolicy":"","name":"","database":"database","precisionV18FluxV20":"ms","retentionPolicyV18Flux":"","org":"organisation","bucket":"bucket","x":910,"y":180,"wires":[]},{"id":"2aa4b01d.f511f","type":"influxdb","hostname":"influx","port":"8086","protocol":"http","database":"db1","name":"influx","usetls":false,"tls":"","influxdbVersion":"1.x","url":"http://localhost:8086","rejectUnauthorized":true}] ``` ### Gapit codes A library of ready-made *Gapit codes* is forthcoming. ### gapit-snmp The node needs to be configured with, at a minimum: * SNMP config (host, community, etc.) * Gapit code | Parameter | Description | | ------ | ------ | | Name | Node name | | Host | SNMP host | | Community | SNMP community | | Version | SNMP version | | Timeout | SNMP timeout | | Device name | The device name database records will be tagged with (e.g. "ups1")| | Device name db-tag | The database tag for device name (e.g. "devname") | | Minion IDs | A list of minion IDs, see below | | Custom tags | Extra tags to add to database records, see below | | Gapit code | The Gapit code JSON | | Scaling | *General* or *Schleifenbauer* | | Skip nonexistent OIDs in subsequent queries | If an OID generates a "doesn't exist" error, stop querying it (*default on*) | | Remove items with no value from gapit_results | If checked, only those items where a value was returned is represented in `msg.gapit_results` (*default on*) | #### Minion IDs Using an SNMP bridge device, it is possible to query multiple devices "behind" the bridge. The bridges represent these devices using a variable ID as part of the OID, e.g. 1.2.3.4.x.1, and some *Gapit codes* are set up for this. Specify your device IDs in the *Minion IDs* field, separated by semicolons (**;**). If you specify more than one *Minion IDs*, the *Device name* field must have an equal number of names, also semicolon separated. #### Custom tags Add database tags, formatted as JSON with `tag_name: value`. If multiple minions are specified, tags must be in a child object named for the device name, or "all-minion-tags" for any tags that should be common for all minions. Example: ```json { "floor": "1", "room": "101" } ``` ### gapit-results-to-influx-batch To use a Node-RED timestamp with influxdb (enabled by default), add a property containing a timestamp in your inject node. The default name is `msg.ts`. | Parameter | Description | | ------ | ------ | | Name | Node name | | Use timestamp from Message | Use a timestamp injected in the flow (*default on*) | | Timestamp property | The `msg` property to get the timestamp from (*default: "ts"*) | #### N.B.! Check the InfluxDB time precision If using timestamps from Node-RED, note that while this works "out-of-the-box" with InfluxDB v2, you will have to set the `influx batch` node to match the millisecond resolution of Node-RED if you're using InfluxDB v1. You can do this by checking `Advanced Query Options` on the `influx batch` node, and then choosing `Milliseconds (ms)` from the `Time Precision` popup menu.