Example: Connect a sensor to the TeamViewer IoT Agent - TeamViewer Support
<main> <article class="userContent"> <p><br></p><p>This example provides a quick overview of how to use the <strong>TeamViewer IoT Agent MQTT API</strong> to securely (encrypted and trusted) connect, to register sensors and metrics, to view device inventory, and to push data to the <strong>TeamViewer IoT Cloud</strong>.</p><p>For more information see <a href="https://community.teamviewer.com/English/kb/articles/109884-teamviewer-iot-agent-mqtt-api" rel="nofollow noreferrer ugc">TeamViewer IoT Agent MQTT API</a>.</p><p>📌<strong>Note:</strong> In this example, you will use multiple terminals at once. Always make sure that you use the correct terminal as described in this example.</p><p>You will use three separate terminals to perform this example:</p><ul><li><strong>Terminal 1</strong> will be used to receive messages from the <strong>Authentication API</strong>.</li><li><strong>Terminal 2</strong> will be used to publish commands to the <strong>API</strong>.</li><li><strong>Terminal 3</strong> will be used to receive messages from the <strong>Registration </strong>and <strong>Data API</strong>.</li></ul><p><br></p><h3></h3><h2 data-id="what-you-will-need">What you will need</h2><ul><li>The edge device is set up with a TeamViewer IoT Agent.</li><li>Your login credentials for the edge device (user name, and password).</li><li>You are logged in to the <strong>IoT Management Console</strong>. To log in to the <strong>IoT Management Console</strong>, open <a href="https://teamviewer-iot.com/?_ga=2.225050905.2061074140.1679400704-933174053.1679400704" rel="nofollow noreferrer ugc">https://teamviewer-iot.com</a> and use your TeamViewer account credentials.</li><li>A tool to access the edge device remotely via ssh (e.g. <a href="https://www.putty.org/" rel="nofollow noreferrer ugc">Putty</a>).</li><li>Advanced knowledge of <strong>Linux systems</strong> and <strong>command line operations</strong>.</li></ul><p><br></p><h3 data-id="-1"></h3><h2 data-id="setup">Setup</h2><p>1. Create <strong>Terminal 1</strong>. Log in to the <strong>Edge Device</strong> and use your credentials by using a <strong>ssh-tool</strong>.</p><p>2. Create <strong>Terminal 2</strong>. Log in to the <strong>Edge Device</strong> and use your credentials by using a <strong>ssh-tool</strong>.</p><p>3. Create <strong>Terminal 3</strong>. Log in to the <strong>Edge Device</strong> and use your credentials by using a <strong>ssh-tool</strong>.</p><p>4. Install the <strong>Mosquitto Clients</strong>. In the <strong>Terminal 1</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">sudo apt-get install mosquitto-clients </pre><p>5. Subscribe to all <strong>Authentication and Authorization</strong> topics to receive data/messages from the <strong>TeamViewer IoT Agent MQTT API</strong>. In the <strong>Terminal 1</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_sub -h localhost -p 18883 --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /# </pre><p>📌<strong>Note:</strong> You can subscribe to each topic separately as illustrated in the TeamViewer IoT Agent MQTT API documentation. In this example, the <code class="code codeInline" spellcheck="false" tabindex="0">#</code> is used as placeholder to subscribe to all topics, including success and error messages.</p><p>6. Generate a <strong>Certificate Signing Request</strong> and <strong>Private Key</strong>. In the <strong>Terminal 2</strong> type in the following command and press return. Type in your specific information when prompted (e.g. <code class="code codeInline" spellcheck="false" tabindex="0">company name</code>).</p><pre class="code codeBlock" spellcheck="false" tabindex="0">openssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem </pre><p>Two files are created:</p><ul><li><strong>privkey.pem</strong> (your private key file will be used for publishing / subscribing to topics)</li><li><strong>csr.pem</strong> (this file will be presented to the TeamViewer IoT Agent to generate a certificate)</li></ul><p>7. Publish the <strong>Certificate Signing Request </strong>(<code class="code codeInline" spellcheck="false" tabindex="0">csr.pem</code>) to the API to receive a <strong>TeamViewer IoT Agent</strong> generated and signed certificate. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18883 --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/createClient -m < (echo -n """ && cat csr.pem && echo -n """) </pre><p>8. Copy the certificate content into a new file called <code class="code codeInline" spellcheck="false" tabindex="0">clientCert.crt</code> and save in the same location as your <code class="code codeInline" spellcheck="false" tabindex="0">privkey.key</code>. In the <strong>Terminal 1</strong> type in the following command and press return. Replace path (<code class="code codeInline" spellcheck="false" tabindex="0">PATH</code>) with the path where your file <code class="code codeInline" spellcheck="false" tabindex="0">privkey.key</code> is located.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">cp csr.pem PATH/clientCert.crt </pre><p>9. Parse the unique <strong>client Id</strong> to be used for your secure connection for all subsequent messages. Record the <strong>resulting Id</strong> for future use. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">openssl x509 -noout -subject -in clientCert.crt -nameopt multiline | grep commonName | sed -r 's/commonName/ /g' | sed -r 's/=/ /g' | xargs | tr -d " tnr" </pre><p>📌<strong>Note:</strong> The <strong>resulting Id</strong> for this example is <code class="code codeInline" spellcheck="false" tabindex="0">c6c5e217089743da8ec3f1d256fa99c2</code>.</p><p>10. Use your <strong>private key</strong> and <strong>certificate</strong>, securely subscribe to all <strong>Registration</strong> and <strong>Data</strong> topics to receive data and messages from the <strong>TeamViewer IoT Agent MQTT API</strong>. In the <strong>Terminal 3</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /# </pre><p>📌<strong>Note: </strong>You can subscribe to each topic separately as illustrated in the TeamViewer IoT Agent MQTT API documentation. In this example, the <code class="code codeInline" spellcheck="false" tabindex="0">#</code> is used as placeholder to subscribe to all topics, including success and error messages.</p><p>11. Verify your secure connection to the <strong>API</strong> is alive, by executing this command and verifying the message is received in <strong>Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/ping -m "{ "request" : "Some Message" }" </pre><p>📌<strong>Note: </strong>The command includes the <strong>example Id</strong> from a previous step (<code class="code codeInline" spellcheck="false" tabindex="0">c6c5e217089743da8ec3f1d256fa99c2</code>).</p><p>12. Display your <strong>Inventory</strong>, which will be <strong>displayed in Terminal 3</strong>. The Inventory should be empty (<code class="code codeInline" spellcheck="false" tabindex="0">[]</code>) as we haven’t registered any sensors yet. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/list -m "{}" </pre><p>13. Register a new <strong>sensor </strong>called <code class="code codeInline" spellcheck="false" tabindex="0">Temperature1</code>. The result will be <strong>displayed in Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return. Record the <code class="code codeInline" spellcheck="false" tabindex="0">sensordId </code>from the <strong>Terminal 3</strong> output as it will be needed later.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/create -m "{ "name" : "Temperature1" }" </pre><p>14. Register <strong>three metrics</strong> for your <strong>Temperature1 sensor</strong>. The result will be <strong>displayed in Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return. Record the <code class="code codeInline" spellcheck="false" tabindex="0">metricId</code> for each Metric from the <strong>Terminal 3</strong> output as it will be needed later.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/d43862fd65ac4a0f9054cfe1749cad82/metric/create -m "{"metrics" : [{"matchingId" : "1", "valueUnit": "NoSI.Dimensionless.PERCENT", "name" : "CPUUsage" },{"matchingId" : "2","valueUnit": "NoSI.Dimensionless.PERCENT", "name" :"CPUIdle" }, {"matchingId" : "3", "valueType" : "integer" , "valueAnnotation": "goods per minute", "name" : "ShopFloor1"}]}" </pre><p>15. Display details of one of your <strong>metrics</strong>, which will be displayed in <strong>Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/d43862fd65ac4a0f9054cfe1749cad82/metric/226ede40e42b458d88d09414fa44e7bf/describe -m "{}" </pre><p>16. Display your <strong>Inventory</strong>, which will be displayed in <strong>Terminal 3</strong>. The Inventory should be consistent with the <strong>sensor</strong> and <strong>metrics</strong> you created. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/list -m "{}" </pre><p>17. From the <strong>IoT Management Console</strong> navigate to <strong>Metrics</strong> and verify the <strong>sensor </strong>and <strong>metric information</strong> is consistent with the information you registered with the <strong>API</strong>.</p><p>18. Update the name of your <strong>sensor</strong> to <code class="code codeInline" spellcheck="false" tabindex="0">Temperature2</code>. The result will be <strong>displayed in Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/d43862fd65ac4a0f9054cfe1749cad82/update -m "{ "name" : "Temperature2" }" </pre><p>19. From the <strong>IoT Management Console</strong> navigate to <strong>Metrics</strong> and verify the <strong>sensor</strong> has been updated.</p><p>20. Display your <strong>Inventory</strong>, which will be displayed in <strong>Terminal 3</strong>. The Inventory should display the updated the <strong>sensor</strong>. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/list -m "{}" </pre><p>21. Delete a metric from your Sensor. In the <strong>Terminal 2</strong> type in the following command and press return. In this example the metric with the <strong>metricId</strong> <code class="code codeInline" spellcheck="false" tabindex="0">9712270f8fd04c2baab6a2409b3e4b9d</code> will be deleted.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/d43862fd65ac4a0f9054cfe1749cad82/metric/delete -m "{"metrics": [{"metricId" : "9712270f8fd04c2baab6a2409b3e4b9d" }]}" </pre><p>22. Send <strong>data values</strong> for the two remaining <strong>metrics</strong>. The result will be <strong>displayed in Terminal 3</strong>. In the <strong>Terminal 2</strong> type in the following command and press return.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/c6c5e217089743da8ec3f1d256fa99c2/sensor/d43862fd65ac4a0f9054cfe1749cad82/metric/pushValues -m "{ "metrics": [ {"value" : 21, "metricId" : "226ede40e42b458d88d09414fa44e7bf" }, {"value" : 215, "metricId" : "520b4d8854454e0ea3a4f9a225afb862" } ] }" </pre><p>23. From the <strong>IoT Management Console</strong> navigate to <strong>Metrics</strong> and pin the two metrics to the dashboard (See <a href="https://community.teamviewer.com/English/kb/articles/109861-add-a-widget" rel="nofollow noreferrer ugc">Add A Widget</a>).</p><p>24. From the <strong>IoT Management Console</strong> navigate to <strong>Dashboard</strong> and verify the two new widgets with the created metrics.</p><p><br></p><h3 data-id="-2"></h3> </article> </main>
