Module Twin
ThingsPro Agent exposes up-to-date configuration of connected devices via Reported Properties and allows you to re-configure devices and turn on/off services via Desired Properties. In the current version, ThingsPro Agent allow the following sections to be update via Desired Properties.
Desired/Reported Properties Sections
| No | Origin | Resource | Desired | Description |
|---|---|---|---|---|
| 1 | "apps runtime" | applications | List of all applications installed on ThingsPro Edge | |
| 2 | "system services" | httpserver | Support | HTTP server setting and status |
| 3 | "system services" | sshserver | Support | SSH server setting and status |
| 4 | "system services" | discovery | Support | Discovery service status (enable/disable) |
| 5 | "system services" | serialconsole | Support | Serial console status (enable/disable) |
| 6 | "device" | wan | Network interface connected to WAN | |
| 7 | "device" | route | Routing priority for each network interface | |
| 8 | "device" | dhcpservers | Support | DHCP server status and configuration |
| 9 | "device" | serials | Support | Serial port configuration |
| 10 | "device" | time | Support | System timezone and NTP settings |
| 11 | "device" | ethernets | Support | Ethernet interface status and configuration |
| 12 | "device" | general | Support | Device general properties such as CPU type, firmware version, and ThingsPro Edge version |
| 13 | "device" | gps | Support | GPS settings |
| 14 | "system services" | installations | OTA upgrade progress and result | |
| 15 | "device" | wifi | Support | Wi-Fi settings |
| 16 | "device" | cellulars | Support | Cellular interface status and configuration |
These Reported Properties enabled by default:
general,wan
You can enable other Reported Properties via API. Here is an example for enable properties supported by TPE.curl -X PUT "http://127.0.0.1:59000/api/v1/azure-iotedge/twin/properties" \
-H "accept: application/json" \
-H "mx-api-token:$(cat /var/thingspro/data/mx-api-token)" -k \
-d '{"system services":{"httpserver":[{"reportedPath":"httpserver","desiredPath":"httpserver"}]}}'
A Sample for Reported Properties
{
"applications": {
"list": {
"0": {
"description": "MOXA Modbus TCP Client (Master)",
"desiredState": "ready",
"displayName": "Modbus TCP Client (Master)",
"hardwares": {
"arraySize": 0
},
"health": "good",
"icon": "/app-icons/modbusmaster-tcp.png",
"id": "modbusmaster-tcp",
"name": "modbusmaster-tcp",
"state": "ready",
"version": "3.14.0-278"
},
"arraySize": 1
}
},
"httpserver": {
"certFileName": "default.crt",
"httpEnable": true,
"httpPort": 80,
"httpsEnable": true,
"httpsPort": 8443,
"keyFileName": "default.key"
},
"sshserver": {
"enable": true,
"port": 22
},
"discovery": {
"enable": true
},
"serialconsole": {
"enable": true
},
"wan": {
"displayName": "LAN1",
"dns": {
"0": "10.128.8.5",
"arraySize": 1
},
"gateway": "10.144.51.254",
"ip": "10.144.48.128",
"name": "eth0",
"netmask": "255.255.252.0",
"type": "wan"
},
"route": {
"priorityList": {
"0": "Cellular1",
"1": "LAN1",
"arraySize": 2
},
"type": "route"
},
"dhcpservers": {
"0": {
"available": false,
"displayName": "LAN1",
"domainName": "",
"domainNameServers": {
"0": "8.8.8.8",
"1": "8.8.4.4",
"arraySize": 2
},
"enable": false,
"endIp": "192.168.3.250",
"id": 1,
"leaseTime": 3600,
"name": "eth0",
"netmask": "255.255.255.0",
"startIp": "192.168.3.200",
"status": false,
"type": "dhcpservers"
},
"arraySize": 1
},
"serials": {
"0": {
"baudRate": 9600,
"dataBits": 8,
"device": "/dev/ttyM0",
"displayName": "PORT 1",
"flowControl": "none",
"id": 1,
"mode": "rs232",
"parity": "none",
"stopBits": 1,
"type": "serials"
},
"arraySize": 1
},
"time": {
"ntp": {
"enable": false,
"interval": 7200,
"server": "pool.ntp.org"
},
"timezone": "Asia/Taipei",
"type": "time"
},
"general": {
"cpu": "ARMv7 Processor rev 2 (v7l)",
"description": "",
"deviceType": "gateway",
"firmwareVersion": "3.0",
"hostName": "Moxa",
"lastBootTime": "2019-11-13T11:42:51Z",
"lastRebootTime": "",
"memorySize": 524333056,
"modelName": "UC-8112-LX",
"serialNumber": "TAIAB1021075",
"thingsproVersion": "1.1.0-348",
"type": "general"
},
"ethernets": {
"0": {
"broadcast": "10.144.51.255",
"displayName": "LAN1",
"dns": {
"0": "10.128.8.5",
"arraySize": 1
},
"enable": true,
"enableDhcp": false,
"gateway": "10.144.51.254",
"id": 1,
"ip": "10.144.48.128",
"mac": "00:90:e8:77:06:61",
"name": "eth0",
"netmask": "255.255.252.0",
"status": "connected",
"subnet": "10.144.48.0",
"type": "ethernets",
"wan": true
},
"arraySize": 1
},
"gps": {
"interface": "",
"location": {
"lat": 14,
"lng": 15
},
"mode": "manual",
"type": "gps"
},
"installations": {
"completedTask": 0,
"id": 3,
"isDeleted": false,
"jobID": 3,
"lastState": "",
"owner": "admin",
"parameter": {
"download": false,
"install": true,
"jobID": 2
},
"state": "created"
},
"wifi": {
"0": {
"ap": {
"band": "band24",
"broadcastSsid": true,
"channel": 6,
"region": "TW",
"security": {
"mode": "wpa2",
"password": "",
"encryption": "aes"
},
"ssid": "moxa-sample-ap"
},
"enable": true,
"id": 1,
"type": "wifi",
"name": "wlan0",
"mode": "ap"
},
"arraySize": 1
},
"cellulars": {
"0": {
"autoDetect": false,
"available": true,
"capabilities": {
"sim": 1
},
"currentProfileId": 0,
"displayName": "Cellular1",
"enable": false,
"iccid": "",
"id": 1,
"imei": "",
"imsi": "",
"keepalive": {
"enable": false,
"intervalSec": 120,
"targetHost": "8.8.8.8"
},
"mac": "02:01:02:18:00:0b",
"module": "u-blox TOBY-L2 series",
"name": "usb0",
"operatorName": "",
"pinRetryRemain": 0,
"profileTimeout": 140,
"profiles": {
"0": {
"id": 1,
"init": {
"0": "sim:1",
"arraySize": 1
},
"name": "SIM1",
"pdpContext": {
"apn": "internet",
"auth": {
"password": "",
"protocol": "none",
"username": ""
},
"id": 1,
"static": true,
"type": "ipv4"
},
"pinCode": "0000"
},
"arraySize": 1
},
"rat": "",
"status": "disconnected",
"type": "cellulars",
"wan": true
},
"arraySize": 1
}
}
Note:
These two keys are commonly used in the Desired Properties:
- id: A device may own multiple interfaces for the same kind of resource. The id specifies the interface to be configured for the resouce. The id starts at 1.
- arraySize: Azure device twin currently does not support an array. Hence, an array and an arraySize key is encoded in an object with child objects. The arraySize value must match the number of child objects, else the remaining objects will be discarded.
Desired Properties Sections
HTTP(S) Server
Use this to update HTTP(S) server configuration.
{
"desired": {
"httpserver": {
"httpEnable": true,
"httpPort": 80,
"httpsEnable": true,
"httpsPort": 8443
}
}
}
SSH Server
Use this to update the SSH server configuration.
{
"desired": {
"sshserver": {
"enable": true,
"port": 22
}
}
}
Discovery Service
Use this to updates the discovery service status.
{
"desired": {
"discovery": {
"enable": true
}
}
}
Serial Console Port
Use this to enable/disable serial console port.
{
"desired": {
"serialconsole": {
"enable": true
}
}
}
DHCP Server
Use this to update the DHCP server.
{
"desired": {
"dhcpservers": {
"0": {
"id": 1,
"enable": true,
"startIp": "192.168.3.100",
"endIp": "192.168.3.200",
"netmask": "255.255.255.0",
"domainNameServers": {
"0": "8.8.8.8",
"arraySize": 1
},
"domainName": "example.com",
"leaseTime": 2592000
},
"arraySize": 1
}
}
}
Serial Port
Use this to update the Serial Port to RS-232 mode.
{
"desired": {
"serials": {
"0": {
"id": 1,
"mode": "rs232",
"displayName": "PORT 1",
"baudRate": 115200,
"parity": "none",
"dataBits": 8,
"stopBits": 1,
"flowControl": "software"
},
"arraySize": 1
}
}
}
| No | Name | Available Values |
|---|---|---|
| 1 | mode | rs232, rs422, rs4852w, rs4854w |
| 2 | baudRate | 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600 |
| 3 | parity | none, even, space, mark |
| 4 | dataBits | 5,6,7,8 |
| 5 | stopBits | 1,2,1.5 |
| 6 | flowControl | none, hardware, software |
Time Service
Use this to update the NTP settings.
{
"desired": {
"time": {
"ntp": {
"enable": true,
"interval": 6000,
"server": "tock.stdtime.gov.tw"
}
}
}
}Use this to update the timezone.
{
"desired": {
"time": {
"timezone": "Asia/Taipei"
}
}
}A list of all the timezones can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Ethernet
Use this to update an Ethernet Interface for Dynamic IP.
{
"desired": {
"ethernets": {
"0": {
"id": 1,
"enable": true,
"enableDhcp": true,
"wan": true
},
"arraySize": 1
}
}
}Use this to update an Ethernet Interface for Static IP.
{
"desired": {
"ethernets": {
"0": {
"id": 1,
"dns": {
"0": "1.2.3.4",
"arraySize": 1
},
"enable": true,
"enableDhcp": false,
"gateway": "1.2.3.5",
"ip": "1.2.3.6",
"netmask": "255.255.255.0",
"wan": true
},
"arraySize": 1
}
}
}
General
Use this to update the device host name.
{
"desired": {
"general": {
"hostName": "MyHost"
}
}
}Use this to update the device description.
{
"desired": {
"general": {
"description": "MyDevice"
}
}
}
GPS
Use this to manually update the GPS lat and lng values.
{
"desired": {
"gps":{
"mode": "manual",
"location": {
"lat": 11,
"lng": 12
}
}
}
}Use this to update GPS parameters using the auto mode.
{
"desired": {
"gps":{
"mode": "auto",
"interface": "/dev/ttyUSB0"
}
}
}
Wi-Fi
Use this to enable/disable the Wi-Fi AP mode.
{
"desired": {
"wifi": {
"0": {
"ap": {
"band": "band24",
"broadcastSsid": true,
"channel": 6,
"region": "TW",
"security": {
"mode": "wpa2",
"password": "",
"encryption": "aes"
},
"ssid": "moxa-sample-ap"
},
"enable": true,
"id": 1,
"type": "wifi",
"name": "wlan0",
"mode": "ap"
},
"arraySize": 1
}
}
}
Cellulars
Use this to update the cellular pin code.
{
"desired": {
"cellulars": {
"0": {
"autoDetect": false,
"available": true,
"capabilities": {
"sim": 1
},
"currentProfileId": 0,
"displayName": "Cellular1",
"enable": false,
"iccid": "",
"id": 1,
"imei": "358503060483337",
"imsi": "",
"keepalive": {
"enable": false,
"intervalSec": 120,
"targetHost": "8.8.8.8"
},
"mac": "02:01:02:18:00:0b",
"module": "u-blox TOBY-L2 series",
"name": "usb0",
"operatorName": "",
"pinRetryRemain": 0,
"profileTimeout": 140,
"profiles": {
"0": {
"id": 1,
"init": {
"0": "sim:1",
"arraySize": 1
},
"name": "SIM1",
"pdpContext": {
"apn": "internet",
"auth": {
"password": "",
"protocol": "none",
"username": ""
},
"id": 1,
"static": true,
"type": "ipv4"
},
"pinCode": "0000"
},
"arraySize": 1
},
"rat": "",
"signal": {
"csq": 0,
"ecio": 0,
"indicator": "",
"level": 0,
"rat": "",
"rscp": 0,
"rsrp": 0,
"rsrq": 0,
"rssi": 0,
"rxqual": 0
},
"status": "disconnected",
"type": "cellulars",
"wan": true
},
"arraySize": 1
}
}
}
Last updated on 2022-07-22 by Cecilia Fernandes