feat (template): provide template for Particle IoT devices

influxdata · Dec 3, 2021 · ea39f2c · ea39f2c
1 parent e90186a
commit ea39f2c
Show file tree

Hide file tree

Showing 4 changed files with 330 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -65,6 +65,7 @@ Start by reading [how to use a template](docs/use_a_template.md), then check eac
 | [Nextcloud](nextcloud/) | Show stats about your Nextcloud Instance. | [Ignacio Van Droogenbroeck](https://github.com/xe-nvdk) |
 | [Nginx Ingress Controller](nginx-ingress-controller/) | Monitor NGINX Ingress Controller with Prometheus metrics | [@bonitoo.io](https://github.com/bonitoo-io) |
 | [Node.js](node_js/) | Monitor Node.js application. CPU, Memory, HTTP response time and more | [@bonitoo.io](https://github.com/bonitoo-io) |
+| [Particle](particle/) | Sample dashboard displaying data published by Particle IoT devices | [bonitoo.io](.) |
 | [Postgres Monitor](postgresql/) | Monitor Postgres Server. CPU, Deadlocks, Data and more | [Ignacio Van Droogenbroeck](https://github.com/xe-nvdk) |
 | [Prometheus Monitor](prometheus/) | Monitor Prometheus | [bonitoo.io](.) |
 | [Raspberry Pi System Monitor](raspberry-pi/) | System overview monitoring for your Raspberry Pi with Raspbian. | [@bonitoo.io](https://github.com/bonitoo-io) |

diff --git a/particle/particle.yml b/particle/particle.yml
@@ -0,0 +1,230 @@
+apiVersion: influxdata.com/v2alpha1
+kind: Label
+metadata:
+  name: elastic-albattani-2d7001
+spec:
+  color: '#00a3ff'
+  name: Particle
+---
+apiVersion: influxdata.com/v2alpha1
+kind: Variable
+metadata:
+  name: hardcore-nobel-2d7005
+spec:
+  associations:
+    - kind: Label
+      name: elastic-albattani-2d7001
+  language: flux
+  name: particle_Room
+  query: |-
+    import "influxdata/influxdb/v1"
+    v1.measurementTagValues(bucket: "telegraf", measurement: "particle", tag: "room")
+  type: query
+---
+apiVersion: influxdata.com/v2alpha1
+kind: Dashboard
+metadata:
+  name: silly-wiles-6d7001
+spec:
+  associations:
+    - kind: Label
+      name: elastic-albattani-2d7001
+  charts:
+    - colors:
+        - hex: '#22ADF6'
+          id: "0"
+          name: pool
+          type: min
+          value: 15
+        - hex: '#DC4E58'
+          id: "1"
+          name: fire
+          type: max
+          value: 40
+      decimalPlaces: 1
+      height: 3
+      kind: Gauge
+      name: Room Temperature
+      queries:
+        - query: |-
+            from(bucket: "telegraf")
+              |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+              |> filter(fn: (r) => r["_measurement"] == "particle")
+              |> filter(fn: (r) => r["_field"] == "temp_c")
+              |> filter(fn: (r) => r["room"] == v.particle_Room)
+              |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false)
+              |> yield(name: "last")
+      staticLegend: {}
+      suffix: ' °C'
+      width: 3
+    - axes:
+        - name: x
+          scale: linear
+        - name: "y"
+          scale: linear
+          suffix: ' °C'
+      colorizeRows: true
+      colors:
+        - hex: '#FD7A5D'
+          id: 2abee602-93be-44c6-82ab-685a82e34e2f
+          name: Delorean
+          type: scale
+        - hex: '#5F1CF2'
+          id: 0bf53022-27c2-4cae-b514-f001be94e2b0
+          name: Delorean
+          type: scale
+        - hex: '#4CE09A'
+          id: aa2ffaf3-e65e-413d-bf51-ac3b042faf3d
+          name: Delorean
+          type: scale
+      geom: line
+      height: 3
+      hoverDimension: auto
+      kind: Band
+      legendColorizeRows: true
+      legendOpacity: 1
+      legendOrientationThreshold: 1e+08
+      mainColumn: last
+      name: Room Temperature
+      opacity: 1
+      orientationThreshold: 1e+08
+      queries:
+        - query: |-
+            from(bucket: "telegraf")
+              |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+              |> filter(fn: (r) => r["_measurement"] == "particle")
+              |> filter(fn: (r) => r["_field"] == "temp_c")
+              |> filter(fn: (r) => r["room"] == v.particle_Room)
+              |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false)
+              |> yield(name: "last")
+      staticLegend:
+        colorizeRows: true
+        opacity: 1
+        orientationThreshold: 1e+08
+        widthRatio: 1
+      width: 2
+      widthRatio: 1
+      xCol: _time
+      xPos: 3
+      yCol: _value
+    - colors:
+        - hex: '#545667'
+          id: "0"
+          name: graphite
+          type: min
+        - hex: '#4591ED'
+          id: "1"
+          name: ocean
+          type: max
+          value: 100
+      decimalPlaces: 0
+      height: 3
+      kind: Gauge
+      name: Relative Humidity
+      queries:
+        - query: |-
+            from(bucket: "telegraf")
+              |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+              |> filter(fn: (r) => r["_measurement"] == "particle")
+              |> filter(fn: (r) => r["_field"] == "humidity")
+              |> filter(fn: (r) => r["room"] == v.particle_Room)
+              |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false)
+              |> yield(name: "last")
+      staticLegend: {}
+      suffix: ' %'
+      width: 3
+      xPos: 5
+    - axes:
+        - name: x
+          scale: linear
+        - name: "y"
+          scale: linear
+          suffix: ' %'
+      colorizeRows: true
+      colors:
+        - hex: '#31C0F6'
+          id: 72120251-3bff-4e4c-a7af-7f3346e63a0d
+          name: Nineteen Eighty Four
+          type: scale
+        - hex: '#A500A5'
+          id: b9d8e028-7a5c-4047-8eb3-45943cf5e5dd
+          name: Nineteen Eighty Four
+          type: scale
+        - hex: '#FF7E27'
+          id: 1377d0b3-ed70-4862-9b5d-7aaa6672e824
+          name: Nineteen Eighty Four
+          type: scale
+      geom: line
+      height: 3
+      hoverDimension: auto
+      kind: Band
+      legendColorizeRows: true
+      legendOpacity: 1
+      legendOrientationThreshold: 1e+08
+      mainColumn: last
+      name: Relative Humidity
+      opacity: 1
+      orientationThreshold: 1e+08
+      queries:
+        - query: |-
+            from(bucket: "telegraf")
+              |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+              |> filter(fn: (r) => r["_measurement"] == "particle")
+              |> filter(fn: (r) => r["_field"] == "humidity")
+              |> filter(fn: (r) => r["room"] == v.particle_Room)
+              |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false)
+              |> yield(name: "last")
+      staticLegend:
+        colorizeRows: true
+        opacity: 1
+        orientationThreshold: 1e+08
+        widthRatio: 1
+      width: 2
+      widthRatio: 1
+      xCol: _time
+      xPos: 8
+      yCol: _value
+  name: Particle - Room Sensors
+---
+apiVersion: influxdata.com/v2alpha1
+kind: Telegraf
+metadata:
+  name: ridiculous-lehmann-ad7001
+spec:
+  associations:
+    - kind: Label
+      name: elastic-albattani-2d7001
+  config: |
+    [agent]
+    interval = "10s"
+    round_interval = true
+    metric_batch_size = 1000
+    metric_buffer_limit = 10000
+    collection_jitter = "0s"
+    flush_interval = "10s"
+    flush_jitter = "0s"
+    precision = ""
+    hostname = ""
+    # do no set the "host" tag in the telegraf agent
+    omit_hostname = true
+
+    ###############################################################################
+    #                            OUTPUT PLUGINS                                   #
+    ###############################################################################
+
+    [[outputs.influxdb_v2]]
+    urls = ["$INFLUX_HOST"]
+    token = "$INFLUX_TOKEN"
+    organization = "$INFLUX_ORG"
+    bucket = "telegraf"
+
+    ###############################################################################
+    #                            INPUT PLUGINS                                    #
+    ###############################################################################
+
+    [[inputs.webhooks]]
+    service_address = ":1619"
+    [inputs.webhooks.particle]
+    path = "/particle"
+  name: Particle
+
diff --git a/particle/readme.md b/particle/readme.md
@@ -0,0 +1,99 @@
+# Particle Template
+
+Provided by: [bonitoo.io](.)
+
+**Sample dashboard displaying data published by [Particle](https://www.particle.io/) IoT devices.**
+
+This template provides a sample dashboard displaying data published by [Particle](https://www.particle.io/) IoT devices
+in a Home Automation System and a Telegraf configuration file to integrate with [Particle](https://www.particle.io/).
+
+Particle + Influxdata integration is described in more detail in the following document:
+https://docs.particle.io/tutorials/integrations/influxdata/.
+
+![Dashboard Screenshot](screenshot.png)
+
+### Quick install
+
+#### InfluxDB UI
+
+In the InfluxDB UI, go to Settings->Templates and enter this URL:
+https://raw.githubusercontent.com/influxdata/community-templates/master/particle/particle.yml
+
+#### Influx CLI
+
+If you have your InfluxDB
+credentials [configured in the CLI](https://v2.docs.influxdata.com/v2.0/reference/cli/influx/config/), you can install
+this template with:
+
+```
+influx apply -u https://raw.githubusercontent.com/influxdata/community-templates/master/particle/particle.yml
+```
+
+## Included Resources
+
+This template includes the following:
+
+- 1 Label: `Particle`
+- 1 Dashboard: `Particle - Room Sensors`
+- 1 Variable: `particle_Room`
+- 1 Telegraf Configuration: `Particle`
+
+## Setup Instructions
+
+1. **Create bucket `telegraf`** (if it does not exist yet)
+    * this template is configured to use bucket `telegraf`
+
+2. **Setup Telegraf** using the configuration included in this template
+    * environment variables to be set are described in section [Telegraf Configuration](#TelegrafConfiguration) below
+
+3. **Configure a Webhook on the [Particle console](https://console.particle.io/integrations)** pointing to your running
+   Telegraf host
+    * follow section [Particle Console](https://docs.particle.io/tutorials/integrations/influxdata/#particle-console) on
+      particle.io
+    * make sure that the URL ends with `/particle`
+    * use the following custom JSON data:
+      ```
+      {
+        "event": "{{{PARTICLE_EVENT_NAME}}}",
+        "data": {{{PARTICLE_EVENT_VALUE}}},
+        "published_at": "{{{PARTICLE_PUBLISHED_AT}}}",
+        "measurement": "particle"
+      }
+      ```
+
+4. **Modify your Particle IoT devices' firmware** to publish events
+    * follow section [Firmware](https://docs.particle.io/tutorials/integrations/influxdata/#firmware) on particle.io
+    * use method `Particle.publish()` to publish events from the IoT devices
+    * the sample dashboard in this template uses fields `temp_c` and `humidity` and tag `room`
+    * sample event data to send from the IoT device:
+      ```
+      {
+        "tags": {
+          "room": "Kitchen"
+        },
+        "values": {
+          "temp_c": 25.3,
+          "humidity": 65
+        }
+      }
+      ```
+
+### <a name="TelegrafConfiguration"></a>Telegraf Configuration
+
+The Telegraf configuration requires the following environment variables to be defined:
+
+- `INFLUX_HOST` - The URL for your InfluxDB host.
+- `INFLUX_TOKEN` - The token with the permissions to read Telegraf configs and write data to the `telegraf` bucket. You
+  can just use your operator token to get started.
+- `INFLUX_ORG` - The name of your organization in InfluxDB.
+
+You **MUST** set these environment variables before running Telegraf using something similar to the following commands
+
+- This can be found on the `Load Data` > `Tokens` page in your browser: `export INFLUX_TOKEN=TOKEN`
+- Your Organization name can be found on the Settings page in your browser: `export INFLUX_ORG=my_org`
+
+## Contact
+
+Author: Jan Simon, https://www.bonitoo.io
+
+Github: @jansimonb
diff --git a/particle/screenshot.png b/particle/screenshot.png