Getting Started: An example of how to Connect your Sensor to the TeamViewer IoT Agent - TeamViewer Support
<main> <article class="userContent"> <p><em>This article applies to all TeamViewer IoT users.</em></p><p><strong>Using the IoT Agent MQTT API</strong></p><ul><li>Full API details can be found at: <a href="https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/Teamviewer-IoT-device-MQTT-API/ta-p/17116" rel="nofollow noreferrer ugc">https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/Teamviewer-IoT-device-MQTT-API/ta-p/17116</a></li><li>The steps below provide a quick overview of how to use the IoT Agent MQTT API to securely (encrypted and trusted) connect to the IoT Agent MQTT API to register sensors & metrics, view device inventory, and push data to the TeamViewer IoT Cloud.</li></ul><p><strong>Prerequisites:</strong></p><ol><li>TeamViewer IoT Agent has been downloaded, installed, and provisioned to your TeamViewer Account <em>(Reference: </em><a href="https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/Install-TeamViewer-IoT-Agent/ta-p/17084" rel="nofollow noreferrer ugc"><em>https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/Install-TeamViewer-IoT-Agent/ta-p/17084</em></a><em> for details)</em></li><li>You will use three separate Command Line terminals to perform these steps:<ul><li>Terminal 1 will be used to receive messages from the Authentication API</li><li>Terminal 2 will be used to publish commands to the API</li><li>Terminal 3 will be used to receive messages from the Registration & Data API</li></ul></li><li>You are logged into your TeamViewer IoT Cloud account (<a href="https://teamviewer-iot.com" rel="nofollow noreferrer ugc">https://teamviewer-iot.com</a>)</li><li>Mosquitto Clients is installed on your Raspberry Pi/Linux machine<ul><li>sudo apt-get install mosquitto-clients</li></ul></li></ol><p><strong>Getting Started:</strong></p><ol><li>In a new terminal <strong><em>(Terminal 1) </em></strong>Subscribe to all <strong>Authentication and Authorization</strong> topics to receive data/messages form the IoT Agent MQTT API</li></ol><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><ul><li><em>Note: you can subscribe to each topic separately as illustrated in the API documentation. In this example, we have used the ‘#’ placeholder to subscribe to all topics, including success and error messages.</em></li></ul><pre class="code codeBlock" spellcheck="false" tabindex="0">In a new terminal (Terminal 2) Generate a Certificate Signing Request and Private Keyopenssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem </pre><ul><li>After entering your information for the Certificate Request, you will have two files created:<ul><li><strong>privkey.pem</strong> <em>(your private key to be used for publishing/subscribing to topics)</em></li><li><strong>csr.pem</strong> <em>(will be presented to the TeamViewer IoT Agent to generate a certificate)</em></li></ul></li></ul><ol><li>In Terminal 2, Display the <strong>csr.pem </strong>and copy the output into your clipboard</li></ol><pre class="code codeBlock" spellcheck="false" tabindex="0">cat csr.pem </pre><ol><li>In Terminal 2, Publish the <strong><em>Certificate Signing Request </em></strong>to the API to receive a IoT Agent generated & signed certificate.</li></ol><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 "-----BEGIN CERTIFICATE REQUEST-----MIICijCCAXICAQAwRTELMAkGA1UEBhMCREUxEzARBgNVBAgMClNvbWUtU3RhdGUx ITAfBgNVBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBALxww/Pyulld+zK2I3EeokpxvmD/y2xS/x0/bDwx bHIl4Apk8CebpZRil+VhtDwHwwkHk90jMuRbEOeYsXvuoE7r7EUbQnpf8/WO+orL yBwFO0x7BP1GYuene78b9jkWRaKVaek5uhldN4I3WBKDj2mdxzTS1ZoZIoyFYD5L zCDXcm4igfyEZutHa0757gHNrVRbe3iWNpVYw9wqoTGPvH2G+Hcvec64hYHccVOu R/UEbcSb553wLnFWKRWLGi6f3WJFGX6tqFw1QoLyE2p24mrUAqP0/myDbEc+dEPk sbYqPunz/0d71jtS+W+/XmTAw5WyLq3D/k8iNQI/ODzGho0CAwEAAaAAMA0GCSqG SIb3DQEBCwUAA4IBAQA+tuZW9o7BkC4wGZyrtqKFSfS7KWAYDId15Zb34DBDg4c2 HPhhA7KRCtxY30nM+EpDp0MU95VgLFo6NmMY3MR/E4aoZwO60K+NdHvkPaqNo57t eqycZchcsJx/jKGQwagBp4CjNKtenR3TiE0sHCoCEEwC5+tuPD1p6z64OdbS/w8k HIXVhC/W2/1GEE7K15n9fdrtObUY36IOf8bPAfJNexaeoy/eTFzq5bvEcY7DS1XO YxyLqWtcaatysudJNRH33nb/ow2RMU0Q694Q2GAsQXgW90vdZtoAaQfAyg/gz/AC wTvOtbP9xVULQQR8+krTRDn0JWFPuHpjTSF6eSEH-----END CERTIFICATE REQUEST-----" </pre><ul><li>Note: the “----BEGIN CERTIFICATE REQUEST---- …..----END CERTIFICATE REQUEST----” should be the contents of your <strong>csr.pem</strong> enclosed in quotes [ “ ].</li></ul><pre class="code codeBlock" spellcheck="false" tabindex="0">In Terminal 1, your certificate should be displayed as shown in the example below. Copy the certificate content into a new file called clientCert.crt and save in the same location as your privkey.key-----BEGIN CERTIFICATE----- MIIEPjCCAiagAwIBAgIBADANBgkqhkiG9w0BAQsFADBEMQswCQYDVQQGEwJERTEc MBoGA1UEAwwTVGVhbVZpZXdlckF1dGhvcml0eTEXMBUGA1UECgwOVGVhbVZpZXdl EwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50ZXJuZXQgV2lk NmZhOTljMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOc6fESUBd2l NdaofgstrysWaJQsQmFEFay7GIqk3AO6JUrPzfo4v2+3Yrb3RYOo3PvqphyBnvi9 UN4a+nu1kwIGu9sLetWL8RDvySF5GnXBdMCiwG9pJ/tfLy300t+9LgIgG54QZhXw +9BP8KXbiQMJiAoOvkW4nNGUCsGUOBA9fwZ4SKqkTsKoF3GyJWf+Zr1Ge5X7LqRb 9Wh+VKPP7wFsLr/P4bu9ELxQV5lPLTnyoWaZJIvjZFRmfg== -----END CERTIFICATE----- </pre><ol><li>In Terminal 2, execute the following command to parse the unique Client ID to be used for your secure connection for all subsequent messages. Record the resulting ID for future use.</li></ol><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 " \t\n\r" </pre><ul><li>For this example, my unique ID was “c6c5e217089743da8ec3f1d256fa99c2”</li></ul><ol><li>In a new terminal <strong><em>(Terminal 3), </em></strong>using your private key and certificate, securely subscribe to all <strong>Registration & Data</strong> topics to receive data/messages form the IoT Agent MQTT API</li></ol><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><ul><li>Note: you can subscribe to each topic separately as illustrated in the API documentation. In this example, we have used the ‘#’ placeholder to subscribe to all topics, including success and error messages</li></ul><ol><li>In Terminal 2, Verify your secure connection to the API is alive, by executing this command & verifying the message is received in Terminal 3.</li></ol><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><ul><li>Note that the command includes my unique Client ID (c6c5e217089743da8ec3f1d256fa99c2) as part of the message</li></ul><ol><li>In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.</li></ol><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><ul><li><em>Note: Inventory should be empty [] as we haven’t registered any sensors yet</em></li></ul><ol><li>In Terminal 2, execute this command to register a new Sensor called <strong><em>Temperature1</em></strong>; the result will appear in Terminal 3.</li></ol><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><ul><li><em>Note: </em>you can update the <strong>name</strong> value in the command below to customize your data</li><li>Record the <em>sensorId </em>from the Terminal 3 output as it will be used in subsequent messages.</li></ul><ol><li>In Terminal 2, execute this command to register 3 metrics for your <strong><em>Temperature1 </em></strong>sensor; the result will appear in Terminal 3.</li></ol><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><ul><li><em>Note: </em>you can update the <strong>valueUnit, valueType, valueAnnotation, & name</strong> values in the command below to customize your data</li><li>Record the <em>metricId for each Metric </em>from the Terminal 3 output as it will be used in subsequent messages.</li></ul><ol><li>In Terminal 2, execute this command to display details of one of your Metrics, which will be displayed in Terminal 3.</li></ol><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><ul><li><em>Note: Metric details displayed in Terminal 3 should be consistent with the Metric you created</em></li></ul><ol><li>In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.</li></ol><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><ul><li><em>Note: Inventory displayed in Terminal 3 should be consistent with the Sensor and Metrics you created</em></li></ul><ol><li>Navigate to the <strong><em>TeamViewer IoT Cloud</em></strong> “Metrics” Tab & verify the Sensor & Metric information is consistent with the information you registered with the API.</li><li>In Terminal 2, execute this command to update the name of your Sensor to <strong><em>Temperature2</em></strong>; Terminal 3 will display that the change was made.</li></ol><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><ul><li><em>Note: </em>you can update the <strong>name</strong> value in the command below to customize your data</li><li>Navigate to the <strong><em>TeamViewer IoT Cloud</em></strong> “Metrics” Tab & verify the Sensor Name has been updated</li></ul><ol><li>In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.</li></ol><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><ul><li><em>Note: the Sensor Name should show the updated name, Temperature2.</em></li></ul><ol><li>In Terminal 2, execute this command to delete a metric from your Sensor</li></ol><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><ul><li><em>Note: “9712270f8fd04c2baab6a2409b3e4b9d” is the metricId of the Metric deleted</em></li></ul><ol><li>In Terminal 2, execute this command to display your inventory, which be displayed in Terminal 3 and verify the Metric has been deleted</li></ol><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><ul><li><em>Note: Inventory displayed in Terminal 3 should no longer display the deleted Metric Id</em></li></ul><ol><li>In Terminal 2, execute this command to send data values for the two remaining Metrics, Terminal 3 will show that the values were updated successfully</li></ol><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><ul><li><em>Note: Metric “226ede40e42b458d88d09414fa44e7bf” was updated with a value of 21; Metric “520b4d8854454e0ea3a4f9a225afb862” was updated with a value of 215.</em></li></ul><ol><li>Navigate to the <strong><em>TeamViewer IoT Cloud</em></strong> “Metrics” tab and pin the 2 metrics for your device to the dashboard.<ul><li>View the “Dashboard” tab to see your two widgets. The widgets should show the data point that was pushed in the previous step for each metric.</li></ul></li></ol><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://community.teamviewer.com/resources/emoji/confused.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://community.teamviewer.com/resources/emoji/confused.png" alt=":\" height="180" width="320" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p><br></p> </article> </main>
