Merge pull request #1 from bmhughes/version-0-3-0

Version 0.3.0
bmhughes · Aug 9, 2020 · 3ac004d · 3ac004d
2 parents a664d93 + 7b0d93b
commit 3ac004d
Show file tree

Hide file tree

Showing 11 changed files with 383 additions and 80 deletions.
diff --git a/.github/lock.yml b/.github/lock.yml
@@ -0,0 +1,8 @@
+---
+daysUntilLock: 365
+exemptLabels: []
+lockLabel: false
+lockComment: >
+  This thread has been automatically locked since there has not been
+  any recent activity after it was closed. Please open a new issue for
+  related bugs.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,40 @@
+---
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Rubocop Linter Action
+        uses: andrewmcodes/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v2
+      - name: Run Markdown Lint
+        uses: actionshub/markdownlint@master
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.5', '2.6', '2.7' ]
+    name: Ruby ${{ matrix.ruby }}        
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: ruby -v
+      - run: bundle install          
+      - run: ./influx_hs110_energy.rb -h
+...
diff --git a/.mdlrc b/.mdlrc
@@ -0,0 +1 @@
+rules "~MD024", "~MD013"
diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
@@ -1,6 +1,5 @@
-# Offense count: 7
-# Cop supports --auto-correct.
-# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
-# URISchemes: http, https
-Metrics/LineLength:
-  Max: 140
+Layout/LineLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Max: 100
diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # tp_link_smartplug_influx
 
+## v0.3.0 (2019-09-26)
+
+- Add default tags with plug name
+- Add RSSI and power on time to default fields
+- Add support for multiple plugs per measurement
+- Added conditional fields
+
 ## v0.2.0 (2019-07-02)
 
 - Skip inaccessible hosts

diff --git a/Gemfile b/Gemfile
@@ -2,7 +2,7 @@
 
 source 'https://rubygems.org'
 
-gem 'tp_link_smartplug', '~>0.1.0'
+gem 'tp_link_smartplug', '~> 0.1.0'
 
 group :test do
   gem 'rspec'

diff --git a/README.md b/README.md
@@ -6,11 +6,18 @@ Ruby script to retrieve energy data from a TP Link HS110 smart plug and out it i
 ![License](https://img.shields.io/github/license/bmhughes/tp_link_smartplug_influx.svg)
 [![Build Status](https://travis-ci.org/bmhughes/tp_link_smartplug_influx.svg?branch=master)](https://travis-ci.org/bmhughes/tp_link_smartplug_influx)
 
+- [Usage](#usage)
+- [Tags](#tags)
+- [Fields](#fields)
+- [Calculated Fields](#calculated-fields)
+- [Configuration File Format](#configuration-file)
+- [Telegraf Configuration](#telegraf-configuration)
+
 ## Change Log
 
 - See [CHANGELOG.md](/CHANGELOG.md) for version details and changes.
 
-### Usage
+## Usage
 
 ```bash
 bundle install
@@ -21,44 +28,158 @@ bundle install
 Usage: influx_hs110_energy.rb [options]
     -h, --help                       Prints this help
     -v, --verbose                    Enable verbose output, breaks influx line format. TESTING ONLY
+    -d, --debug                      Enable debug output, breaks influx line format. TESTING ONLY
+    -s, --stop-on-error              Enable script execution stop on error when polling a plug
+    -m, --measurement-name NAME      Name for the Influx measurement
     -a, --address ADDRESS            IP or FDQN of plug to poll
     -c, --config FILE                Configuration file
 ```
 
 You can either specify a single host on the command line (via option `-a`) or provide multiple hosts in a configuration file in JSON format.
 
-### Configuration File
+## Tags
+
+By default the following tags are added to the measurement:
+
+- Plug name from configuratoin
+- Plug description from Kasa/Plug
+
+## Fields
+
+By default the following fields are added to the measurement:
+
+- Voltage (mV)
+- Current (mA)
+- Power (mW)
+- Relay State (0/1)
+- Power On Time (seconds)
+- WLAN RSSI (dBm)
+
+## Calculated Fields
+
+The script has supported for creating calculated fields by comparison with another field, this is a crutch to provide derived fields until Influx 2 adds conditional query support.
+
+### Example
+
+With the below configuration the `state` field will be `0` when the `power` field is between 30000mW and 100000mW and `1` when greater than `100000`.
+
+```json
+"calculated_fields": {
+                "state": {
+                    "default": -1,
+                    "field": "power",
+                    "conditions": {
+                        "0": {
+                            ">=": 30000,
+                            "<=" : 100000
+                        },
+                        "1": {
+                            ">": 100000
+                        }
+                    }
+                }
+            }
+```
+
+## Configuration File
 
 Configuration is performed via JSON file which is `config.json` by default although this can be overridden by the `-c/--config` command line argument.
 
-| Metric Name | Address    | Tags                                  |
-|-------------| -----------|---------------------------------------|
-| HS110-1     | 192.0.2.10 | test-tag-1 = true, test-tag-2 = false |
-| HS110-2     | 192.0.2.11 | None                                  |
+### Format
 
 ```json
 {
-    "HS110-1": {
-        "address": "192.0.2.10",
-        "tags": {
-            "test-tag-1": true,
-            "test-tag-2": false
+    "Measurement": {
+        "Plug": {
+            "address": "IP address/FQDN of plug",
+            "calculated_fields": {
+                "field_name": {
+                    "default": "Default value",
+                    "field": "Field to examine",
+                    "conditions": {
+                        "value": {
+                            "operator": "Comparison value"
+                        }
+                    }
+                }
+            },
+            "fields": {
+                "energy": {
+                    "Influx field name": "Field from plug energy data"
+                },
+                "info": {
+                    "Influx field name": "Field from plug info data"
+                }
+            },
+            "tags": {
+                "Tag name": "Tag value"
+            }
+        }
+    }
+}
+```
+
+### Example
+
+| Measurement Name | Metric Name | Address    | Tags                                  | Calculated Fields                                                    |
+|------------------|-------------| -----------|---------------------------------------|----------------------------------------------------------------------|
+| Measurement-01   | Plug-01     | 192.0.2.10 | test-tag-1 = true, test-tag-2 = false | None                                                                 |
+|                  | Plug-02     | 192.0.2.11 | None                                  | None                                                                 |
+| Measurement-02   | Plug-01     | 192.0.2.20 | None                                  | None                                                                 |
+| Measurement-03   | Plug-01     | 192.0.2.30 | None                                  | state: "0": { ">=": 30000 and "<=" : 100000 }, "1": { ">": 100000 }  |
+
+```json
+{
+    "Measurement-01": {
+        "Plug-01": {
+            "address": "192.0.2.10"
+        },
+        "Plug-02": {
+            "address": "192.0.2.11"
         }
     },
-    "HS110-2": {
-        "address": "192.0.2.11"
+    "Measurement-02": {
+        "Plug-01": {
+            "address": "192.0.2.20"
+        },
+    },
+    "Measurement-03": {
+        "Plug-01": {
+            "address": "192.0.2.30",
+            "calculated_fields": {
+                "default": -1,
+                "field": "power",
+                "conditions": {
+                    "0": {
+                        ">=": 30000,
+                        "<=" : 100000
+                    },
+                    "1": {
+                        ">=": 100000
+                    }
+                }
+            }
+        }
     }
 }
 ```
 
+Testing,plug=GBMDS-SPL-HS110-01,dev_alias=Garage\ Air\ Conditioning voltage=242107i,current=285i,power=61984i,relay_state=1i,on_time=1869899i,rssi=-37i,state=0i
+Testing,plug=GBMDS-SPL-HS110-02,dev_alias=Garage\ UPS\ 1 voltage=243168i,current=1942i,power=439368i,relay_state=1i,on_time=157603i,rssi=-38i
+Testing,plug=GBMDS-SPL-HS110-03,dev_alias=Garage\ UPS\ 2 voltage=242570i,current=1055i,power=153496i,relay_state=1i,on_time=54949i,rssi=-40i
+Testing,plug=GBMDS-SPL-HS110-04,dev_alias=Garage\ UPS\ 3 voltage=242248i,current=1656i,power=370625i,relay_state=1i,on_time=54881i,rssi=-39i
+Testing,plug=GBMDS-SPL-HS110-05,dev_alias=Garage\ UPS\ 4 voltage=245340i,current=1353i,power=292023i,relay_state=1i,on_time=54877i,rssi=-39i
+
 Will yield to STDOUT:
 
 ```bash
-Test Plug 1,test-tag-1=true,test-tag-2=false voltage=240657i,current=288i,power=62120i
-Test Plug 2 voltage=240657i,current=288i,power=62120i
+Measurement-01,plug=Plug-01,test-tag-1=true,test-tag-2=false voltage=240657i,current=288i,power=62120i
+Measurement-01,plug=Plug-02 voltage=240657i,current=288i,power=62120i
+Measurement-02,plug=Plug-01 voltage=240657i,current=288i,power=62120i
+Measurement-03,plug=Plug-01 voltage=240657i,current=288i,power=62120i,state=0i
 ```
 
-### Telegraf Configuration
+## Telegraf Configuration
 
 ```bash
 [[inputs.exec]]

diff --git a/config.example.json b/config.example.json
@@ -0,0 +1,10 @@
+{
+    "Measurement-01": {
+        "Plug-01": {
+            "address": "192.0.2.10"
+        },
+        "Plug-02": {
+            "address": "192.0.2.11"
+        }
+    }    
+}
diff --git a/helpers/helpers.rb b/helpers/helpers.rb
@@ -0,0 +1,14 @@
+# frozen_string_literal: false
+
+def debug_message(string)
+  caller_method = caller_locations(1..1).first.label
+  STDOUT.puts(Time.now.strftime('%Y-%m-%d %H:%M:%S: ').concat("#{caller_method}: ").concat(string))
+end
+
+def nil_or_empty?(object)
+  object.nil? || object.empty?
+end
+
+def seconds_since(time)
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - time).round(2)
+end