This example provides a quick overview of how to use the TeamViewer Embedded Agent MQTT API to securely (encrypted and trusted) connect, to register sensors and metrics, to view device inventory, and to push data to the TeamViewer Embedded Cloud.
For more information see TeamViewer Embedded Agent MQTT API.
📌Note: In this example, you will use multiple terminals at once. Always make sure that you use the correct terminal as described in this example.
You will use three separate terminals to perform this example:
- Terminal 1 will be used to receive messages from the Authentication API.
- Terminal 2 will be used to publish commands to the API.
- Terminal 3 will be used to receive messages from the Registration and Data API.
What you will need
- The edge device is set up with a TeamViewer Embedded Agent.
- Your login credentials for the edge device (user name, and password).
- You are logged in to the Embedded Management Console. To log in to the Embedded Management Console, open https://iot.teamviewer.com/ and use your TeamViewer account credentials.
- A tool to access the edge device remotely via ssh (e.g. Putty).
- Advanced knowledge of Linux systems and command line operations.
Setup
1. Create Terminal 1. Log in to the Edge Device and use your credentials by using a ssh-tool.
2. Create Terminal 2. Log in to the Edge Device and use your credentials by using a ssh-tool.
3. Create Terminal 3. Log in to the Edge Device and use your credentials by using a ssh-tool.
4. Install the Mosquitto Clients. In the Terminal 1 type in the following command and press return.
sudo apt-get install mosquitto-clients
5. Subscribe to all Authentication and Authorization topics to receive data/messages from the TeamViewer Embedded Agent MQTT API. In the Terminal 1 type in the following command and press return.
mosquitto_sub -h localhost -p 18883 --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /#
📌Note: You can subscribe to each topic separately as illustrated in the TeamViewer Embedded Agent MQTT API documentation. In this example, the # is used as placeholder to subscribe to all topics, including success and error messages.
6. Generate a Certificate Signing Request and Private Key. In the Terminal 2 type in the following command and press return. Type in your specific information when prompted (e.g. company name).
openssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem
Two files are created:
- privkey.pem (your private key file will be used for publishing / subscribing to topics)
- csr.pem (this file will be presented to the TeamViewer Embedded Agent to generate a certificate)
7. Publish the Certificate Signing Request (csr.pem) to the API to receive a TeamViewer Embedded Agent generated and signed certificate. In the Terminal 2 type in the following command and press return.
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 """)
8. Copy the certificate content into a new file called clientCert.crt and save in the same location as your privkey.key. In the Terminal 1 type in the following command and press return. Replace path (PATH) with the path where your file privkey.key is located.
cp csr.pem PATH/clientCert.crt
9. Parse the unique client Id to be used for your secure connection for all subsequent messages. Record the resulting Id for future use. In the Terminal 2 type in the following command and press return.
openssl x509 -noout -subject -in clientCert.crt -nameopt multiline | grep commonName | sed -r 's/commonName/ /g' | sed -r 's/=/ /g' | xargs | tr -d " tnr"
📌Note: The resulting Id for this example is c6c5e217089743da8ec3f1d256fa99c2.
10. Use your private key and certificate, securely subscribe to all Registration and Data topics to receive data and messages from the TeamViewer Embedded Agent MQTT API. In the Terminal 3 type in the following command and press return.
mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /#
📌Note: You can subscribe to each topic separately as illustrated in the TeamViewer Embedded Agent MQTT API documentation. In this example, the # is used as placeholder to subscribe to all topics, including success and error messages.
11. Verify your secure connection to the API is alive, by executing this command and verifying the message is received in Terminal 3. In the Terminal 2 type in the following command and press return.
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" }"
📌Note: The command includes the example ID from a previous step (c6c5e217089743da8ec3f1d256fa99c2).
12. Display your Inventory, which will be displayed in Terminal 3. The Inventory should be empty ([]) as we haven’t registered any sensors yet. In the Terminal 2 type in the following command and press return.
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 "{}"
13. Register a new sensor called Temperature1. The result will be displayed in Terminal 3. In the Terminal 2 type in the following command and press return. Record the sensordId from the Terminal 3 output as it will be needed later.
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" }"
14. Register three metrics for your Temperature1 sensor. The result will be displayed in Terminal 3. In the Terminal 2 type in the following command and press return. Record the metricId for each Metric from the Terminal 3 output as it will be needed later.
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"}]}"
15. Display details of one of your metrics, which will be displayed in Terminal 3. In the Terminal 2 type in the following command and press return.
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 "{}"
16. Display your Inventory, which will be displayed in Terminal 3. The Inventory should be consistent with the sensor and metrics you created. In the Terminal 2 type in the following command and press return.
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 "{}"
17. From the Embedded Management Console navigate to Metrics and verify the sensor and metric information is consistent with the information you registered with the API.
18. Update the name of your sensor to Temperature2. The result will be displayed in Terminal 3. In the Terminal 2 type in the following command and press return.
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" }"
19. From the Embedded Management Console navigate to Metrics and verify the sensor has been updated.
20. Display your Inventory, which will be displayed in Terminal 3. The Inventory should display the updated the sensor. In the Terminal 2 type in the following command and press return.
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 "{}"
21. Delete a metric from your Sensor. In the Terminal 2 type in the following command and press return. In this example the metric with the metricId 9712270f8fd04c2baab6a2409b3e4b9d will be deleted.
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" }]}"
22. Send data values for the two remaining metrics. The result will be displayed in Terminal 3. In the Terminal 2 type in the following command and press return.
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" } ] }"
23. From the Embedded Management Console navigate to Metrics and pin the two metrics to the dashboard (See Add A Widget).
24. From the Embedded Management Console navigate to Dashboard and verify the two new widgets with the created metrics.