node-red-contrib-domotz

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> <title>tutorial</title> <style> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} .display.math{display: block; text-align: center; margin: 0.5rem auto;} </style>  </head> <body> <h1 id="introduction">Introduction</h1> <p>Node-red-domotz is a <a href="https://nodered.org/">Node-Red</a> plugin providing easy access to the Domotz Public API. It offers a convenient way to explore the APIs, automate flows, create custom dashboards and integrate Domotz data with external tools. With Node-red-domotz you don’t have to be a skilled programmer to get the most out of the public API.</p> <p>The following tutorial will help you get started with Node-red-domotz and learn how to build a custom dashboard with it.</p> <h3 id="installation">Installation</h3> <p>For the installation instructions of Node-Red please refer to the <a href="https://nodered.org/docs/getting-started/">official guide</a>. You can install the Domotz node from the ‘manage palette’ menu of Node-Red. Just search for <code>node-red-contrib-domotz</code> and install it. In the rest of this tutorial we will rely on the excellent <a href="https://flows.nodered.org/node/node-red-dashboard">node-red-dashboard</a> plugin, so I recommend installing it as well.</p> <h3 id="your-first-node">Your first node</h3> <p>After a successful installation the domotz-api node should be available in the palette, ready to be dragged in the workspace.</p> <figure> <img src="img1.png" alt="palette" /><figcaption aria-hidden="true">palette</figcaption> </figure> <p>For the node to be functional you need to configure the access info using your API-Key and your endpoint. Multiple access keys are supported, thus you can manage multiple accounts from the same workspace.</p> <figure> <img src="img2.png" alt="node configuration" /><figcaption aria-hidden="true">node configuration</figcaption> </figure> <p>Once the access info is configured you can select any API method from the dropdown list.</p> <figure> <img src="img3.png" alt="api methods" /><figcaption aria-hidden="true">api methods</figcaption> </figure> <p>Let’s select <code>agent.listAgents</code> to retrieve the IDs of all the available agents and click ‘Deploy’. If the provided access configuration is valid you should see a green marker next to the node.</p> <figure> <img src="img4.png" alt="valid conf" /><figcaption aria-hidden="true">valid conf</figcaption> </figure> <p>Now we can create an <code>inject</code> node to trigger the API call and a <code>debug</code> node to display the output. The <code>inject</code> node can be easily configured to send a periodic trigger, enabling auto refresh of the data. Again, deploy and click inject. In the debug space you will see the API output from which you can extract all the available information about your agents.</p> <figure> <img src="img5.png" alt="node debug output" /><figcaption aria-hidden="true">node debug output</figcaption> </figure> <h3 id="creating-a-custom-dashboard">Creating a custom dashboard</h3> <p>Now that we learned how to deploy a Domotz node let’s see how we can parse the output to create a custom dashboard displaying camera snapshots, RTD and SNMP charts. The API methods of the following examples require some additional configuration, namely agent, device, and SNMP sensor IDs. Make sure you have them ready, you can retrieve them using <code>agent.listAgents</code>, as seen before, <code>device.listDevices</code> and <code>eyes.listEyesSNMP</code>. You can specify the IDs directly in the node’s configuration window or pass them in the input message (e.g., using and injector node with a payload like this <code>{"params": {"agent_id": "123456"}}</code>)</p> <h4 id="snmp-data-chart">SNMP data chart</h4> <p>Select <code>eyes.getEyesSNMPHistory</code>, configure it with the right agent, device and sensor ID and connect its main output to a <code>function</code> node. Then connect the <code>function</code> node to a chart widget. The following function code transforms the input data sequence (msg.payload.message) in the format required by the chart.</p> <pre class="$js"><code>data = [ { 'series': ['CPU % 5 min'], 'data': [ [], ], 'labels': ['CPU % 5 min'], }, ]; dataIn = msg.payload.message; for (var i = 0; i < dataIn.length; i++) { sample = dataIn[i]; ts = sample.timestamp; data[0]['data'][0].push({'x': ts, 'y': sample.value}); } msg = { payload: data, }; return [msg];</code></pre> <p>The following images display the wiring and the resulting chart. <img src="img6.png" alt="snmp wiring" /></p> <figure> <img src="img7.png" alt="snmp chart" /><figcaption aria-hidden="true">snmp chart</figcaption> </figure> <h4 id="round-trip-delay-chart">Round Trip Delay chart</h4> <p>For <code>metrics.getDeviceRTDHistory</code> we can use a similar approach, only this time we have three different data series to display: maximum, minimum and median.</p> <pre class="$js"><code>data = [ { 'series': ['median', 'min', 'max'], 'data': [ [], [], [], ], 'labels': ['median', 'min', 'max'], }, ]; dataIn = msg.payload.message; for (var i = 0; i < dataIn.length; i++) { sample = dataIn[i]; ts = sample.timestamp; data[0]['data'][0].push({'x': ts, 'y': sample.median}); data[0]['data'][1].push({'x': ts, 'y': sample.min}); data[0]['data'][2].push({'x': ts, 'y': sample.max}); } msg = { payload: data, }; return [msg];</code></pre> <figure> <img src="img8.png" alt="rtd_chart" /><figcaption aria-hidden="true">rtd_chart</figcaption> </figure> <h4 id="lights-actioncamera">Lights, action…camera!</h4> <p>The <code>multimedia.onvifSnapshot</code> allows taking a snapshot from an Onvif camera. To display the image in our dashboard we won’t need a specific function node as we will perform the data parsing in a <code>template</code> node, directly connected to the main output of the snapshot node. The following code, (to be added to the template node) waits for a new message, creates a Blob from the binary data and sets it as source of an image tag.</p> <pre class="$html"><code><div> <style> img { border: 1px solid #ddd; border-radius: 4px; padding: 5px; width: 400px; } </style> <script> (function (scope) { scope.$watch('msg', function (msg) { if (msg) { var b = new Blob([msg.payload.message], {type: 'image/jpeg'}); scope.image = URL.createObjectURL(b); } }); })(scope); </script> <img ng-src="{{image}}"/> </div></code></pre> <p><img src="img9.png" alt="snapshot wiring" /> <img src="img10.png" alt="snapshot" /></p> <h3 id="summary">Summary</h3> <p>In this tutorial we’ve seen how to create a custom dashboard using data extracted from the Domotz API. With little programming effort, the Domotz Node Red package allows to easily interact with the Domotz API.</p> <h3 id="next-steps">Next steps</h3> <p>In the next tutorial we’ll see how the leverage Domotz Webhooks and the Public API to create automated response to network event notifications.</p> </body> </html>