Each Ingestor will have a specific inbound translator with which it is associated,
and each Command will have a specific command translator with which it is associated. The inbound translator's purpose is to convert the data received via the ingestor listener and handler to the EdgeIQ report JSON format. The command translator's purpose is to convert a command represented as JSON into the device's native command format.
Cloud vs Edge Translators
Translators can be run either in the cloud or on a downstream device such as a gateway running EdgeIQ's Edge service. If the cloud_translator parameter is true, the translator will be installed in the EdgeIQ Cloud ingest engine. If it is false, the translator will be passed to the associated Edge Gateway.
Translator Types (inbound "ingest")
| Translator Type | Attributes | Example |
|---|---|---|
anko | type, name, script | { "type" : "anko", "name" : "Anko Translator 01", "value" : "...escaped anko script..." } |
javascript | type, name, script | { "type" : "javascript", "name" : "JS Translator 02", "script" : "...escaped javascript script..." } |
csv | type, name | See detailed example below. |
The anko type is only valid for edge translators (i.e., cloud_translator=false).
Translator Types (command)
| Translator Type | Attributes | Example |
|---|---|---|
anko_cmd | type, name, script | { "type" : "anko_cmd", "name" : "Anko Translator 01", "script" : "...escaped anko script..." } |
javascript_cmd | type, name, script | { "type" : "javascript_cmd", "name" : "JS Translator 02", "script" : "...escaped javascript script..." } |
template_cmd | type, name, script | { "type" : "template_cmd", "name" : "Template Translator 02", "script" : "...escaped golang template..." } |
csv_cmd | type, name, options | { "type" : "csv_cmd", "name" : "CSV Translator 03", "options": { "delim": " |
shell_cmd | type, name | { "type" : "shell_cmd", "name" : "Shell Translator" } |
The anko_cmd type is only valid for edge translators (i.e., cloud_translator=false).
Translator Variables
Inside the translator, for translators of type template, anko, and javascript, certain variables are available based on the type of listener configured for the ingestor.
All Polling Listeners
| Name | Description |
|---|---|
| gateway_unique_id | Unique ID of Gateway device where Ingestor is running |
| device_unique_id | Unique ID of device that Ingestor is associated with. If device is attached to a gateway, than gateway_unique_id and device_unique_id will be different. They will be identical when the Ingestor is associated with the gateway. |
| unique_id | alias for device_unique_id |
| device | The Device resource that is associated with the Ingestor. All data fields in Device are available |
| device_type | The Device resource that is associated with the Ingestor. All data fields in DeviceType are available |
HTTP Client Listener
| Name | Description |
|---|---|
| output | The HTTP response body. If the Content Type is application/json, then the output variable will support JSON querypaths, i.e. output.foo for { "foo": "bar" } |
| body | alias for output |
| status_code | The HTTP Response status code value as an integer. |
ICMP Client Listener
| Name | Description |
|---|---|
| output | success/fail |
| status | alias for output |
| error | if status is fail, then the error value as a string. if status is success, than an empty string. |
| time_in_ms | latency in milliseconds |
SNMP Client Listener
| Name | Description |
|---|---|
| output | A JSON map where key is the SNMP Object ID and its value as either a string or integer |
| error | Error information as a string |
Script Example
This is an example of an inbound anko Edge Translator that translates a fixed-length binary message to the EdgeIQ JSON report format. The script follows a pattern
The anko script:
# anko "package" imports
time = import("time")
math = import("math")
json = import("encoding/json")
# vars that will be set and/or read from go
incomingMsg = nil
dataSourceId = ""
errMsg = ""
func isValid() {
if len(incomingMsg) == 21 {
return true
}
return false
}
func getMfrId() {
return toHexString(incomingMsg[2:8])
}
func translate() {
now = time.Now().UTC()
battery = readIntFromBytes(incomingMsg[16:17])
onExtPower = battery >= 128
level = battery
if onExtPower {
level -= 128
}
tempUint32 = readUint32FromBytes(incomingMsg[17:21])
tempFloat = math.Float32frombits(tempUint32)
retMap = {
"device_id": dataSourceId,
"device_datetime": now.Format("2006-01-02T15:04:05.999Z07:00"),
"payload": {
"device_name": getMfrId(),
"function_code": readIntFromBytes(incomingMsg[0:2]),
"interval": readIntFromBytes(incomingMsg[12:16]),
"external_power": onExtPower,
"battery_level": level,
"temperature": tempFloat
},
"raw_data": toHexString(incomingMsg)
}
marshaledBytes, err = json.Marshal(retMap)
return toString(marshaledBytes)
}
The full translator JSON (including above script):
{
"name": "XW110 Sensor Translator",
"type": "anko",
"cloud_translator": false,
"script": "# anko \"package\" imports\ntime = import(\"time\")\nmath = import(\"math\")\njson = import(\"encoding/json\")\n\n# vars that will be set and/or read from go\nincomingMsg = nil\ndataSourceId = \"\"\nerrMsg = \"\"\n\nfunc isValid() {\n\tif len(incomingMsg) == 21 {\n\t\treturn true\n\t}\n\treturn false\n}\n\nfunc getMfrId() {\n\treturn toHexString(incomingMsg[2:8])\n}\n\n\nfunc translate() {\n\tnow = time.Now().UTC()\n\tbattery = readIntFromBytes(incomingMsg[16:17])\n\tonExtPower = battery >= 128\n\tlevel = battery\n\tif onExtPower {\n\t\tlevel -= 128\n\t}\n\ttempUint32 = readUint32FromBytes(incomingMsg[17:21])\n\ttempFloat = math.Float32frombits(tempUint32)\n\t\tretMap = {\n\t\t\"device_id\": dataSourceId,\n\t\t\"device_datetime\": now.Format(\"2006-01-02T15:04:05.999Z07:00\"),\n\t\t\"payload\": {\n\t\t\t\"device_name\": getMfrId(),\n\t\t\t\"function_code\": readIntFromBytes(incomingMsg[0:2]),\n\t\t\t\"interval\": readIntFromBytes(incomingMsg[12:16]),\n\t\t\t\"external_power\": onExtPower,\n\t\t\t\"battery_level\": level,\n\t\t\t\"temperature\": tempFloat\n\t\t},\n\t\t\"raw_data\": toHexString(incomingMsg)\n\t}\n\n\tmarshaledBytes, err = json.Marshal(retMap)\n\treturn toString(marshaledBytes)\n}\n"
}
CSV Example
The next example shows a translator for a CSV message from a fictitious temperature sensor. The
message contains the following fields:
- MAC Address
- Timestamp
- Message type identifier
- Temperature value
- Temperature Unit (F or C)
- Newline char (all CSV records must end with a newline)
An example message:
cd53e1825a01,170113132307,TMP,041.27,C\n
Handler options are configured in the handler (see Ingestors example). Whereas the handler controls how CSV records are read, the options field in the JSON below specifies characteristics about the message type and individual fields. The options field is an array and can contain multiple different CSV message formats. This is useful for dealing with devices that emit multiple types of messages over the same connection.
The following table enumerates properties contained within an element of the options array. Note that in the following descriptions, "property" refers to a JSON property, and "field" refers to a value within the CSV message.
| Field | Required? | Description |
|---|---|---|
mfr_id_field_num | Y | This property indicates the position of the field value that uniquely identifies the device. This value is used to look up the device, so this value must match the device name or unique_id property. |
msg_id_field_num | N | This property is required when the options array contains more than one element, and indicates the position of the field that identifies the message type. A single device might emit multiple CSV message types, and this field is used to distinguish them. |
msg_id_field_val | N | This property is required when the options array contains more than one element, and indicates the expected contents of the msg_id_field_num field for this message type. |
timestamp_field_num | N | This property indicates the position of the field containing a message timestamp. If no field in the message contains a timestamp, a current timestamp will be generated during translation. |
timestamp_format | N | If timestamp_field_num is specified, this property specifies the format of the timestamp so it can be correctly parsed. This property must be specified according to the rules specified in the Golang time package. |
field_metadata | Y | This array is required. Each element in the array specifies how to handle the field within the message at the same position. |
This table lists the properties of each field_metadata element:
| Field | Required? | Description |
|---|---|---|
name | Y | The name to be given to the property within the JSON report. To omit the corresponding field from the report, specify "SKIPME" as the name. |
type | N | The type of data contained in the field value (defaults to "string" if not specified).. Valid property values are "string", "integer", "float", and "boolean". When "integer" is specified, the value will be parsed as a base 10 64-bit signed integer. A "float" will be parsed as a 64-bit floating point number. A "boolean" will use the default boolean parse function. |
Here is the complete JSON for this CSV translator example:
{
"name": "CSV Translator Example",
"type": "csv",
"cloud_translator": false,
"options": {
"mfr_id_field_num": 0,
"msg_id_field_num": 2,
"msg_id_field_val": "TMP",
"timestamp_field_num": 1,
"timestamp_format": "060102150405",
"field_metadata": [
{
"name": "device_name"
},
{
"name": "SKIPME"
},
{
"name": "report_type"
},
{
"name": "temperature",
"type": "float"
},
{
"name": "temperature_unit"
}
]
}
}
And for the example message above, the translated report would look like this:
{
"id": "587971121ab7161c37bbcd57",
"device_datetime": "2017-01-13T13:23:07Z",
"created_at": "2017-01-14T00:30:10Z",
"payload": {
"device_name": "cd53e1825a01",
"report_type": "TMP",
"temperature": 41.27,
"temperature_unit": "C"
},
"device_id": "587971121ab7161c37bbcd54",
"raw_data": "cd53e1825a01,170113132307,TMP,041.27,C",
"seq": 0
}