Learn About Adding Grammars

Connectors and interpreters use grammar to parse the content of device data. Typically, the device data is in JSON and connectors use a standard grammar to parse it. However, when device data is obtained from a bandwidth constrained network such as a LoRa network, the data is in a binary form, then the user has to provide the grammar that the connector and the interpreter use to parse the device data.

In a generic connector and an interpreter, you add a grammar that helps parse the device data. The connector uses the parsed data to create a device record and a device message for device on-boarding in Oracle Internet of Things Cloud Service.

Envelope Grammar and Payload Grammar

The image displays the usage of grammar in connectors and interpreters.

Description of grammar.eps follows
Description of the illustration grammar.eps

Device data has two parts: an envelope and a payload. Envelope data has the same structure for all types of device data. It has an identifier, an event time, and a device type. Connectors read the device data, use grammar to parse it, and then interpret the envelope data. When you configure a connector, you also need to map a few standard metadata fields with the interpreted envelope data. The connector uses the mapped data to generate a device record that is used for registering or on-boarding the device in Oracle Internet of Things Cloud Service.

Payload data can be of different types. For every type of payload, you create an interpreter. When you configure an interpreter, you provide its selection criteria. The connector selects the interpreter based on this selection criteria. The selected interpreter then uses grammar to parse and interpret the payload data. You also need to map the fields of the device model with the interpreted payload data. The interpreter uses the mapped data to generate a device message for the registered device.

When you configure a connector, on the Grammar page, you provide the device data in JSON in the Sample Data text area and then click Validate to display the interpreted values. You don't have to enter grammar for parsing data in JSON because JSON grammar is standardized. If the data is in binary, then you enter the grammar to parse the binary data. You use the Map list box to map a standard set of built-in device metadata such as Hardware ID, name, time-stamp, etc. with the interpreted values. You can also create customized metadata. When the connector registers the device in Oracle Internet of Things Cloud Service, the mapped fields and the interpreted values form the device record.

The image displays the Add Grammar page.

Description of grammar_dialog.png follows
Description of the illustration grammar_dialog.png

When you configure an interpreter, on the Grammar page, you paste the payload data in the Sample Data text area. If the data is in binary then you need to enter the grammar to parse the Base64-encoded binary data. On validation, the interpreted values are displayed. You use the Map list box to map the attributes of the device model with the interpreted values. The mapped fields and interpreted values form the device message that the connector saves in Oracle Internet of Things Cloud Service for the registered device.

On the Grammar page of the Connector screen, in the Sample Data text area, you provide the complete device data in JSON and then click Validate.
{
    "companyName": "TestDemo",
    "Name": "Temperature and humidity",
    "Version": "1",
    "Type": "Temperature and humidity",
    "vendor": "XEE",
    "latitude": "",
    "longitude": "",
    "description": "",
    "locationFriendlyName1": "Brazil test towers",
    "locationFriendlyName2": "",
    "containerFriendlyName": "Temperature",....
     .....
     "payload": "0902000029067a"}
On the Grammar page of the Interpreter screen, in the Sample Data text area, you provide the payload data in binary.
 AWDiAikEAcCxXyYDCAcNYg==
On the Grammar page of the Interpreter screen, in the Grammar text area, you provide the grammar in binary and then click Validate.
grammar xyz; urn:lora:xxxxx:lpp; root payload; payload: data*; 
data: channel 0x00{8b} digitalInput | channel 0x01{8b} digitalOutput 
| channel 0x02{8b} analogInput | channel 0x03{8b} analogOutput | 
channel 0x65{8b} illuminance | channel 0x66{8b} presence | channel 0x67{8b} 
temperature | channel 0x68{8b} humidity | channel 0x71{8b} accelerometer | 
channel 0x73{8b} barometer | channel 0x86{8b}............

Support for Compound Payloads

When configuring connectors, you can map the Envelope variable to support JSON data that contains multiple payloads in an array. For example, the following JSON has a field payloads which is an array containing objects, each of which represent a stand-alone measurement.

{ 
 "payloads": [ 
   {      
     "hwid": "id1",      
     "temp": 62       
    },    
    {      
      "hwid": "id2", 
      "temp": 65    
     }  
   ]
}
In the example, when the Envelope field is configured to point to the array ( payloads[*] ), the connector framework will treat each object in the payload's array as a separate payload. Fields within the contained objects may be referenced and mapped through similar array notation (e.g. payloads[*].temp ).

Map Envelope with an array

Support for Value-Named Fields

There are some circumstances where the attributes names of the measurement data are themselves contained within the JSON string values. Consider the following example, where measurements are sent as an array of objects and the field names are contained in the attrname field:

{  
  "hwid": "id1",  
  "payload": [  
    {   
      "attrname": "temp",
      "attrval": 62    
    },    
    {      
      "attrname": "humidity",
      "attrval": 72
    }
  ]
}
This payload contains a temp measurement with a value of 62, and a humidity measurement with a value of 72. This can be handled by the mapping the Attribute Name and Attribute Value fields. The connector framework will convert the above payload into two measurements ( temp = 62, humidity = 72 ) with the configuration as shown in the image.

Map Attribute Name and Attribute Value