This article applies to all TeamViewer IoT users.
Using the IoT Agent MQTT API
Prerequisites:
- TeamViewer IoT Agent has been downloaded, installed, and provisioned to your TeamViewer Account (Reference: https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/Install-TeamViewer-IoT-Agent/ta-p/17084 for details)
- You will use three separate Command Line terminals to perform these steps:
- 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 & Data API
- You are logged into your TeamViewer IoT Cloud account (https://teamviewer-iot.com)
- Mosquitto Clients is installed on your Raspberry Pi/Linux machine
- sudo apt-get install mosquitto-clients
Getting Started:
- In a new terminal (Terminal 1) Subscribe to all Authentication and Authorization topics to receive data/messages form the IoT Agent MQTT API
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 API documentation. In this example, we have used the ‘#’ placeholder to subscribe to all topics, including success and error messages.
In a new terminal (Terminal 2) Generate a Certificate Signing Request and Private Keyopenssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem
- After entering your information for the Certificate Request, you will have two files created:
- privkey.pem (your private key to be used for publishing/subscribing to topics)
- csr.pem (will be presented to the TeamViewer IoT Agent to generate a certificate)
- In Terminal 2, Display the csr.pem and copy the output into your clipboard
cat csr.pem
- In Terminal 2, Publish the Certificate Signing Request to the API to receive a IoT Agent generated & signed certificate.
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-----"
- Note: the “----BEGIN CERTIFICATE REQUEST---- …..----END CERTIFICATE REQUEST----” should be the contents of your csr.pem enclosed in quotes [ “ ].
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-----
- 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.
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"
- For this example, my unique ID was “c6c5e217089743da8ec3f1d256fa99c2”
- In a new terminal (Terminal 3), using your private key and certificate, securely subscribe to all Registration & Data topics to receive data/messages form the IoT Agent MQTT API
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 API documentation. In this example, we have used the ‘#’ placeholder to subscribe to all topics, including success and error messages
- In Terminal 2, Verify your secure connection to the API is alive, by executing this command & verifying the message is received in Terminal 3.
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 that the command includes my unique Client ID (c6c5e217089743da8ec3f1d256fa99c2) as part of the message
- In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.
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 "{}"
- Note: Inventory should be empty [] as we haven’t registered any sensors yet
- In Terminal 2, execute this command to register a new Sensor called Temperature1; the result will appear in Terminal 3.
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\" }"
- Note: you can update the name value in the command below to customize your data
- Record the sensorId from the Terminal 3 output as it will be used in subsequent messages.
- In Terminal 2, execute this command to register 3 metrics for your Temperature1 sensor; the result will appear in Terminal 3.
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\"}]}"
- Note: you can update the valueUnit, valueType, valueAnnotation, & name values in the command below to customize your data
- Record the metricId for each Metric from the Terminal 3 output as it will be used in subsequent messages.
- In Terminal 2, execute this command to display details of one of your Metrics, which will be displayed in Terminal 3.
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 "{}"
- Note: Metric details displayed in Terminal 3 should be consistent with the Metric you created
- In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.
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 "{}"
- Note: Inventory displayed in Terminal 3 should be consistent with the Sensor and Metrics you created
- Navigate to the TeamViewer IoT Cloud “Metrics” Tab & verify the Sensor & Metric information is consistent with the information you registered with the API.
- In Terminal 2, execute this command to update the name of your Sensor to Temperature2; Terminal 3 will display that the change was made.
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\" }"
- Note: you can update the name value in the command below to customize your data
- Navigate to the TeamViewer IoT Cloud “Metrics” Tab & verify the Sensor Name has been updated
- In Terminal 2, execute this command to display your inventory, which will be displayed in Terminal 3.
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 "{}"
- Note: the Sensor Name should show the updated name, Temperature2.
- In Terminal 2, execute this command to delete a metric from your Sensor
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\" }]}"
- Note: “9712270f8fd04c2baab6a2409b3e4b9d” is the metricId of the Metric deleted
- In Terminal 2, execute this command to display your inventory, which be displayed in Terminal 3 and verify the Metric has been 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/list -m "{}"
- Note: Inventory displayed in Terminal 3 should no longer display the deleted Metric Id
- 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
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\" } ] }"
- Note: Metric “226ede40e42b458d88d09414fa44e7bf” was updated with a value of 21; Metric “520b4d8854454e0ea3a4f9a225afb862” was updated with a value of 215.
- Navigate to the TeamViewer IoT Cloud “Metrics” tab and pin the 2 metrics for your device to the dashboard.
- 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.
