This example provides a quick overview of how to use the TeamViewer IoT 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 IoT Cloud.
For more information see TeamViewer IoT Agent MQTT API.
What you will need
- The edge device is set up with a TeamViewer IoT Host or Windows (TeamViewer Service and Mosquitto broker process running) and has internet access.
- Your login credentials for the edge device (user name, and password).
- You are logged in to the IoT Management Console. To log in to the IoT Management Console, open https://iot.teamviewer.com/ and use your TeamViewer account credentials.
- Mosquitto is installed. Add Mosquitto installation path to Environment Variables.
- Install Git Bash for Windows, this is needed to create CSR and Request Client Certificate
- Advanced knowledge of Windows systems and command line operations.
Setup
Create MQTT Client
1. Generate A CSR using Git Bash
Open a Git Bash window and type in the following command:
openssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem
2. Get the hash of CSR using Git Bash. It is the SHA-256, which will be used in subscribe topic
Open a Git Bash window and type in the following command:
openssl dgst -sha256 csr.pem
In this example the hash is 83a32b8cbae161ab995b1d3bce24715579c4c672f69ca48a24350baaaed40d17
3. Request a client certificate using Command Prompt.
Open a Command Prompt window (run as an administrator) and subscribe for the response:
mosquitto_sub -h localhost -p 18883 --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /certBack/83a32b8cbae161ab995b1d3bce24715579c4c672f69ca48a24350baaaed40d17
📌Note: Do not close this window. The signed certificate will be sent back here in the subscribe topic (this cmd window). Copy the received signed certificate and save as a file (e.g., clientCert.crt) for future use.
Open a command prompt window (as an administrator) and publish the csr.pem
mosquitto_pub -h localhost -p 18883 --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/createClient -f csr.pem
4. Get Client ID for future use within MQTT topics using Git Bash.
Open a Git Bash window and type in the following command:
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"
In this example the ClientID is 6d69c58223fb44a7b76ae61a18faf37c
Create MQTT Client
1. Monitoring
This publish request updates metric values. Prior creation of sensor and metrics is not required. The system checks for the existence of the given sensor and metric IDs. If those do not exist, the system creates missing sensor or metric.
mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6c4a946918dc4facbe354279752a9ddd/sensor/weather/metric/pushValues -m "{ \"metrics\": [{\"value\" : 5, \"metricId\" : \"temperature\" }] , \"timestamp\": 1590394246545}"
Alternatively, you can follow the steps below to create Sensors with Metrics.
Create sensor
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/inbox
📌Note: Do not close this window. A message containing a JSON object with the name of the sensor and a unique ID will be received in this window.
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/create -m "{ \"name\" : \"SensorName\" }"
In this example the name of the sensor and the unique ID are { “name”: “SensorName”, “sensorId”: “d4170d999b9240a5863df622aad9fc4a” }
Create metrics
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/inbox
📌Note: Do not close this window. A message containing a JSON object with the matchingIDs and a unique IDs will be received in this window.
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/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\"}]}"
In this example the metrics and the uniques IDs are:
[{ “matchingId” : “1”, “metricId” : “94c2c5e193bb437195368c08f0bd86ab”},
{ “matchingId” : “2”, “metricId” : “94c2c5e193bb437195368c08f0bd86ac”},
{ “matchingId” : “3”, “metricId” : “94c2c5e193bb437195368c08f0bd86ad”}]
Push data to a Sensor
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/info/inbox
📌Note: Do not close this window. A message will appear that the data is pushed in this window.
Open a Command Prompt window (run as an administrator) and type in the following command:
mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile "C:\Program Files (x86)\Teamviewer\certs\TeamViewerAuthority.crt" -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/6d69c58223fb44a7b76ae61a18faf37c/metric/pushValues -m "{ \"metrics\": [ {\"value\" : 21.5, \"metricId\" : \"94c2c5e193bb437195368c08f0bd86ab\" }, {\"value\" : 21.5, \"metricId\" : \"94c2c5e193bb437195368c08f0bd86ac\" }, {\"value\" : 55, \"metricId\" : \"temperature\" }] , \"timestamp\": \"1590394246545\"}"
From the IoT Management Console navigate to Metrics and verify the created metrics.
