MQTT command and control (automatic subscription topics)
When the data logger successfully connects to an MQTT broker, it will subscribe to a single topic to perform command and control.
<groupID>/cc/<deviceID>/#
Command response
For commands that elicit a response, the response will come on either the <groupID>/state/<deviceID> or on the targeted topic: <groupID>/cr/<deviceID>/ccCmd. The use of state vs. cr depends on the nature of the data returned in the response. If the response is just an acknowledgment, it is returned on state. If there is specific information to be returned, it is published on a targeted topic.
|
Command and control |
Topic |
Description |
|---|---|---|
|
OS |
|
Download OS |
|
program |
|
Download CRBasic program |
|
mqttConfig |
|
Download new MQTT configuration |
|
fileControl |
|
Perform file control actions |
|
editConst |
|
Update the
constant |
|
setting |
|
Set/Retrieve a Device Configuration setting |
|
historicData |
|
Retrieve past
data from a |
|
talkThru |
|
Perform
serial talk thru to |
|
setVar |
|
Set a variables value in a Public, Status or Structure table |
|
getVar |
|
Get variable from table |
|
reboot |
|
Reboot the data logger |
OS download
An OS can be updated by publishing the following JSON object to:
<groupID>/cc/<deviceID>/OS
{
“url”: “url of OS file location”
}
Example:
{
“url” : “https://example.123.xyz”
}
CRBasic program download
A CRBasic Program file can be downloaded and run by publishing the following JSON object to:
Publish on <groupID>/cc/<deviceID>/program with the following JSON payload:
{
“url” : ”https://example.123.xyz”,
“filename”:”MyProg.crb”
}
The data logger will issue a HTTP(s) GET to the specified URL and report success or failure on the <groupID>/state/<deviceID> topic. If successful, the program will be set to run now and run on power up and the data logger will restart and compile and run the program.
Example: With a GRANITE6 using the Base topic: cs/v1/ and a serial number of 123.
Publish to topic: cs/v1/cc/granite6/123/program
{
"url":"https://s3.us-west-2.amazonaws.com/bucket.cr-basic/mqttPub27.cr6?X-Amz-Expires=3593&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4MADCTNFDCYIQHED/20200826/us-west-2/s3/aws4_request&X-Amz-Date=20200826T150138Z&X-Amz-SignedHeaders=host&X-Amz-Signature=496fccd4d14edfe39d270ccee8ae0247ee1b256d01e1810b2c288de940b58507",
"fileName":"MyPub.crb"
}
New mqtt configuration
The mqttConfig command is used to set up the data logger. The file received from this command must follow the proprietary binary format expected by the parsing routine.
Example:
Publish on <groupID>/cc/<deviceID>/mqttConfig with the following JSON payload:
{
“url” : “https://example.123.xyz”
}
The data logger will issue an HTTP(s) GET to the specified URL and report success or failure on the <groupID>/state/<deviceID> topic. Once this file is received, it will be parsed as a binary settings file and if valid, the settings applied, and the data logger restarted.
Edit constant table (editConst)
To edit the constant table via MQTT, publish the new Const table values in a JSON object. The JSON keys and the values must be a string. The string values will be converted to the appropriate types by the data logger. Only the values to be changed are required in the JSON object.
Example:
Publish on <groupID>/cc/<deviceID>/editConst with the following JSON payload:
{
“key1” : “value1”,
“key2” : “value2”,
“keyN” : “valueN”
}
The data logger will publish results on <groupID>/state/<deviceID>/.
Reboot data logger
To remotely reboot (restart) the data logger, use the topic <groupID>/cc/<deviceID>/reboot with the following JSON payload:
{
"action” : "reboot",
}
The additional JSON provides more safety when rebooting.
If successful, the data logger will report on <groupID>/state/<deviceID>, that it is rebooting:
{
"clientId" : "CR6_966",
"state" : "online",
"fileTransfer" : "Rebooting Datalogger"
}
File control
Use the fileControl topic to perform file manipulation commands. Part of the payload will be the action indicating which file function to perform. Since file control, in the full context of data logger capability, is too complex for the thing shadow, file control will be best handled while the data logger is online. The file control functions can be automated by triggering file transfer events via AWS lifecycle events.
Each file control action has a unique JSON object payload. Each of the unique JSON objects must contain the cmd key and fileControl value to perform the file control functions. Each file control function is described below:
list
The data logger can store more files than can be listed in one MQTT publish packet. Therefore, a file list request will return a list of file names containing a maximum of 4800 characters. The names will be published on the fileList topic.
Publish on <groupID>/cc/<deviceID>/fileControl/ with the following JSON payload:
{
“action” : “list”
“drive” :”USR”, (optional – default is CPU)
}
The data logger will publish on the topic:
<groupID>/cr/<deviceID>/fileControl/list
Example:
Publish topic: cs/v2/cc/cr6/ABCDEF/fileControl
JSON:
{"action" : "List"}
Response topic: cs/v2/cr/cr6/ABCDEF/fileControl/list
JSON:
{
"drive" : "CPU",
"clientID" : "CR6_966",
"fileList" : [ "simple.CR6", "spectrum_krohn_cal.crb", "spectrum_cal.crb", "PeriodAvg_testingDaveI.CR6", "spectrum_cal_check.crb", "mqttPub27.cr6", "WatchdogInfo.txt" ]
}
Settings
An individual Device Configuration Utility setting can be set or published via MQTT by publishing the following JSON object.
set
A single setting can be changed in each message. To set multiple settings, a series of messages will be sent with the last having apply set to true.
{
“action” : “set”,
“name” :”Setting name”,
“value” : “XXX”,
“apply” :”true” { this is optional }
}
The data logger will notify success or failure on the topic <groupID>/state/<deviceID>/.
Example:
Publish Topic: cs/v2/cc/cr6/ABCDEF/setting
JSON:
{"name": "PakBusAddress", "action" : "set", "value" : "3", "apply" : "true"}
Response topic: cs/v2/state/cr6/ABCDEF/
{
"clientId" : "CR6_966",
"state" : "Set Setting Succeeded"
}
{
"clientId" : "CR6_966",
"state" : "Applying Settings"
}
Delete a file
Action to delete a file on the data logger. If the file being deleted is the running program, the program will not be stopped, only the associated text file will be deleted.
{
“action” : “delete”
“filename” : “name of file on device”
“drive” :”USR”, (optional – default is CPU)
}
The data logger will publish on topic <groupID>/state/<deviceID>/.
Stop
Action to stop the currently running program.
{
“action” : “stop”
}
The data logger will publish on topic <groupID>/state/<deviceID>/.
Run
Action to stop the currently running program.
{
“action” : “run”,
“filename” : “name of file on device”
}
The data logger will publish on topic <groupID>/state/<deviceID>/.
publish
To read the value of a setting the topic <groupID>/cc/<deviceID>/setting is used with a payload:
{
“action” : “publish”,
“name” :”Setting name”,
}
The setting value will be published on:
<groupID>/cr/<deviceID>/setting
Example:
Publish topic: cs/v2/cc/cr6/ABCDEF/setting
JSON:
{"name" : "PakBusAddress", "action" : "Publish"}
Response topic: cs/v2/cr/cr6/ABCDEF/setting
JSON:
{
"setting" : "PakBusAddress",
"value" : " 3"
}
apply
To apply previously set settings, <groupID>/cc/<deviceID>/setting is used with a payload:
{
“apply” :”true”
}
The data logger will notify success or failure on the topic <groupID>/state/<deviceID>. If successful, this will commit settings to non-volatile memory and restart the data logger.
Historic Data Collection
Historic data can be requested via MQTT by publishing the appropriate JSON payload on the following topic:
<groupID>/cc/<deviceID>/historicData
The payload published on the topic must be in the JSON format as follows:
{
“table”: “{table name}”,
“start”: “{utc time stamp}”,
“end”: “{utc time stamp}”
}
Only data from a DataTable containing the MQTTPublishTable instruction will be published. The data will be published in the same format as indicated in the table publish instruction. In the case of GEOJSON, the point coordinates used when re-publishing the data will be the latest values passed into the table publish instruction. GEOJSON coordinates are not stored.
The historic data will be published on the following topic:
<groupID>/cr/<deviceID>/historicData/TableName
{
"cmd" : "HistoricData",
"table" : "ThirtySecond",
"start" : "2020-04-14T10:10:24.865Z",
"end" : "2020-04-14T10:20:32.176Z"
}
Set Public Variable
A value can be set in a CRBasic program Public table by using the a setVar topic. To set the value of the public table variable, publish associate JSON object to the following topic.
setVar
To change a variable in the running program of the data logger publish to <groupID>/cc/<deviceID>/setVar with a payload like:
{
"name” : "VarOne",
"value" : "12.345"
}
The data logger will report on <groupID>/state/<deviceID>.
The stringified value will be converted to the type of the variable by the data logger.
Get Public variable
A value can be set in a CRBasic programs Public table by using a getVar topic. To get the value of the public table variable, publish associate JSON object to the following topic.
getVar
To read a variable in the running program of the data logger publish to <groupID>/cc/<deviceID>/getVar with a payload similar to this, where VarOne is the variable name:
{
"name” : "VarOne",
}
The data logger will report on <groupID>/state/<deviceID>.
The value will be converted from the type of the variable to a string by the data logger.
Serial talkThru
Serial talkThru allows remote interaction with sensors connected to data logger serial ports. It works similar to the terminal mode serial talk through.
Talk through to sensor
Serial talk through is initiated by sending a JSON payload to the topic <groupID>/cc/<deviceID>/talkThru. The data logger will transmit to the serial sensor and receive one response. One transmission is required for each response from sensor. This feature is not designed to sniff serial sensor output. The desired communications port must be configured prior to using serial talk through. This command causes the data logger to enter a “talk through session”. The session will stay active, meaning that the sensor port will remain in a state of not transferring data through to the instructions using the port until it is aborted or times out. The timeout associated with a talkThru session is 1 minute. If no further talkThru commands are received within a minute, the session will end, and normal communications port operations will resume. The session can also be ended by publishing to the talkThru topic with the JSON key value pair with the key of “abort” (the value does not matter).
The talk thru payload must follow the described format and be published to:
<groupID>/cc/<deviceID>/talkThru
{
“comPort”: “{Port Description}”,
“outString”: “{ASCII string to be sent to sensor}”,
“numberTries”: “{ASCII number string indicating number of transmissions of outString}” (Optional),
“respDelay”: “{ASCII number string indicating time (milliseconds) to wait for the complete response from sensor}” (Optional)
“abort” : “true”
}
TalkThru from sensor
A serial string response from a smart sensor can only be received as a response to a transmission to a sensor. The response will be published to the following topic in the specified JSON format.
<groupID>/cr/<deviceID>/talkThru
TalkThru response JSON payload:
{
“response”: “{String response from Sensor}”
}
If an error occurred, the response will contain an error message:
- Illegal ComPort
- ComPort must be open to use MQTT
talkThru - No response received
Allowable Com port values
The Com port values must follow the case shown.