OVES eIoT Data Exchange Protocols¶

This repo collects all device-discovery related protocols, including messaging mechanism cross all devices, and specific device data formats.

MQTT (formerly known as MQ Telemetry Transport) was created in 1991 by Andy Stanford-Clark (IBM) and Arlen Nipper (Eurotech) in order to connect oil pipelines over unreliable, satellite networks. It is a machine-to-machine (M2M)/”Internet of Things” connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is mostly useful for establishing connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. The protocol is data-centric, unlike for example HTTP, which is document centric.

MQTT protocol is adopted as the basic protocol framework for all OVES devices. The objectives are

Consistency - a common set of agreements cross all OVES devices and services
Scalability - Can be extended vertically in terms of data depth, and horizontally cross different applications
Discoverability - Can allow clients of different intents to extract interested information.

Messaging Topic Tree¶

MQTT Telemetry Topic Uplink Syntax (上行格式-Uplink)¶

The following example and sections provide the MQTT topic structure for telemetry:

dt/<application>/<context>/<thing-name>/<dt-type>

application: Identifies the overall IoT application associated with the device.
context: Single or multiple levels of additional contextual data about the message a device is publishing. e.g. GPRSV2, or GPRSV2/FleetID
dt: Set prefix that refers to the type of message.
thing-name: Identifies which device is transmitting a telemetry message.
dt-type (optional): Associates a message with a particular sub-component of a device, or for edge gateways, any downstream devices.

MQTT Command Topic Downlink Syntax (下行格式-Downlink)¶

When you design MQTT topics for command requests, follow this structure:

cmd/<application>/<context>/<destination-id>/<req-type>

Since commands are two-way communication patterns, design a similar MQTT topic structure for responding to commands, such as the following:

cmd/<application>/<context>/<destination-id>/<res-type>

Because telemetry topic design is similar to command topic design, this section provides only the portions of the IoT topic for command requests and responses that differ. cmd: Prefix that refers to the type of message. Command topics use cmd, short for command. By prefixing all commands with cmd and all telemetry with dt, telemetry and commands are isolated on separate MQTT topics. req-type: Classifies the command.

Application¶

We will use the application designation field for these information:

Project designation. Use "ov01" for all Omnivoltaic applications protocol version 01
Client specific application, e,g, SW, or Angaza

Context¶

Device-Category
Technology platform: e.g. GRPS, LORA, Edge_Hub.
Management platform: e.g. FLEETID, CLIENT

Examples¶

For Omnivoltaic device discovery project, these general fields will be used:

<application> = ov01
<context> = GPRSV2/FLEETID/OEMID
<destination-id>=deviceID, e.g. 303AH1900000300

res-type can take the following levels of specificity

Complete MetaData Set¶

<res-type> = "metadata"

This requires the complete metadata set to be returned:

Downlink:

cmd/ov01/GPRS/OEM_FLID/ovPump1900000300/metadata

OEM_FLID is the default value of fleet, util it is updated by the cloud via factory MQTT.

Uplink:

dt/ov01/GPRSV2//ovPump1900000300/metadata/{
"att" : { 
    "opid" : "OEM Product ID",
    "ppid" : "PAYG Product ID",
    "flid" : "ID of fleet that this device belongs to",
    "frmv" : "Firmware Version Number"
},
"cmd":{...},
"sts":{...},
"sta":{...}
}

Complete Data Set¶

\<res-type\> = = "fulldata"

This requires the complete data set to be returned:

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/fulldata

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/
{
    "att" : 
        { 
        "opid" : "12AH20000001",
        "ppid" : "12AH20000001",
        "flid" : "60b032fa3711d64a5c6c22a7",
        "fmri" : "1.0"
        },
    "cmd":{...},
    "sts":{...},
    "sta":{...}
}

Note that for uplink we use a full JSON format for multi-layer messages.

Select Section Data Set¶

<res-type> = att|cmd|sts|sta.

If "att" is specified, the att section of data is returned:

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/att

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/
{
    "att":
        { 
        "opid" : "12AH20000001",
        "ppid" : "12AH20000001",
        "flid" : "60b032fa3711d64a5c6c22a7",
        "frmv" : "1.0"
        }
}

Select Single Data¶

<res-type> = att|cmd|sts|sta/<parameter-name>.

For example if "att/ppid" is specified, this specific field is returned: Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/att/ppid

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/
{
    "att":
        {
            "ppid": "12AH20000001"
        }
}

More examples for communication controls¶

修改APN的数据格式¶

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/cmd/napn/"China-Mobil"

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/
{  
    "cmd":
        {
            "napn": "China-Mobil"
        }
}

修改休眠周期的数据格式¶

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/cmd/gstw/480

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/
{  
    "cmd":
        {
            "gstw": 480
        }
}

修改GPRS最大联网时间【time-out】的数据格式；¶

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/cmd/gctw/10

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"cmd": { "gctw": 10 } }

充值指令的数据格式；¶

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/cmd/code/"*123 456 789 098 765 432 101#"

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"cmd": {"code": "*123 456 789 098 765 432 101#"} }

主动上报和查询式上报模式选择的数据格式¶

Downlink:

cmd/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/cmd/updt/3600

Uplink:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"cmd": {"updt": 36000} }

Best Practices for Using the AWS IoT Shadow¶

The AWS IoT Shadow is an excellent mechanism for command and control along with storing the reported state of a specific device. The following list provides best practices for maximizing the efficiency of commands through the shadow.

IoT devices should not share shadows.
Use the shadow for state or commands that have a medium to low transaction per second (TPS).
Use the shadow for storing status metrics of a device.
Use the device shadow to catalog the current firmware version.
Use the optional clientToken field with device shadow updates to track the sender of a shadow message.

OVES Device Avatars¶

Similar to the AWS device shadow concept, OVES device will use a 1-to-1 cloud representation to capture all information that the device may want to communicate to the world. In addition, OVES avatar will in future also capture a device signature mechanism that will lay the foundation of making assertions of device provenance.

OVES messaging topic tree format¶

MQTT offers a lot og flexibility in how messages are organized into a tree structured hierarchy. OVES imposes a topic tree format to allow more efficient transmission and identification of messages.

All OVES devices will use this standard messaging topic format, designed to make it easy to identify the the type of devices and messages to and from these IoT items. The messaging protocol is designed to follow the MQTT topic tree format.Topics tell the recipient what the messages are about. For OVES, the following attributes are rpesent on every message:

Platform: this is generally OVES, denoted by _OVES
Protocol Version, denoted by Vx.y
Item Type. OVES device types are 4-12 letters long, e.g. DCTV, BH12,IV6K
Item ID. This is the specific physical device ID: 3H3020000000.
Parameter ID: This is the specific parameter an item might communicate, e.g. Cell_1_Volt. Current
Parameter

Example 1: telemetry data For a device that communicates to the clout these telemetry data:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/303AH1900000300/{"sta": {"cv_1": 1000} }
dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/303AH1900000300/{"sta": {"cv_1": 1000} }

dt: this is a data message
ov01: version 1 of Omnivoltaic global IoT protocol
dh/12345: data sent via data-hub 12345
303AH1900000300: name device
cv_1: cell voltage is the data type
1000: this is the actual message value

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"sta": {"mSpd": 5000} }

dt: this is a data message
ov/01: version 1 of Omnivoltaic global IoT protocol
no data-hub used. Device communicated directly to internet
ovPump1900000300: name of device
mSpd: motor speed
5000: this is the actual message value

Example 1:

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{
    "att" : { 
        "opid" : "12AH20000001",
        "ppid" : "12AH20000001",
        "flid" : "60b032fa3711d64a5c6c22a7",
        "frmv" : "1.0"
    },
    "cmd" : { 
        "pubk" : "*042 195 826 493 279 052 222#",
        "gstw" : 480,
        "gctw" : 10 ,
        "napn": "t-mobile"
    },
    "sts" : { 
        "rcrd" : 1,
        "trhd":1,
        "tpgd" : 1,
        "pgst" : "PAYG",
        "ocst" : "ENABLED",
        "sstc" : 1,
        "rsoc" : 50,
        "rcap" : 90,
        "acyc" : 13,
        "rcrd" : 34,
        "tpgd" : 48
    },
    "sta" : { 
        "batp" : 10,
        "inpp" : 50,
        "outp" : 40,
        "aeng" : 3177,
        "cv01" : 3189,
        "cv02" : 3189,
        "cv03" : 3189,
        "cv04" : 3189,
        "pckv" : 13000,
        "pckc" : 10,
        "pckt" : 25,
        "plat" : 37.177,
        "plon" : -121.7549,
        "time" : 202100010001,
        "gpss" : 4,
        "gpfc" : 100 
    }
}

Example 2

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"att": {
    "ppid":"ovPump1900000300", 
    "opid":"ovPump1900000300",
    "frmv":"1.0" 
    }
}

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"sts":{
    "rcrd" : 1,
    "trhd":1,
    "tpgd" : 1,
    "pgst" : "PAYG",
    "ocst" : "ENABLED",
    "sstc" : 1,
    "rsoc" : 50,
    "rcap" : 90,
    "acyc" : 13,
    "rcrd" : 34,
    "tpgd" : 48
    }
}

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"sta": {
    "batp" : 10,
    "inpp" : 50,
    "outp" : 40,
    "aeng" : 3177,
    "cv01" : 3189,
    "cv02" : 3189,
    "cv03" : 3189,
    "cv04" : 3189,
    "pckv" : 13000,
    "pckc" : 10,
    "pckt" : 25,
    "plat" : 37.177,
    "plon" : -121.7549,
    "time" : 202100010001,
    "gpss" : 4,
    "gpfc" : 100 
    }
}

Example 3

dt/ov01/GPRSV2/"60b032fa3711d64a5c6c22a7"/ovPump1900000300/{"sta": {"mfrq": 5000} }

dt: this is a data message
ov01: version 1 of Omnivoltaic global IoT protocol
no data-hub used. Device communicated directly to internet
ovPump1900000300: name of device
att: attribute JSON object
sts: State JSON object
sta: Status JSON object

Device General Attributes, States and Status (GASS)¶

This shows this is a pump control device, and the pump OEM_ID is ovPump1900000300, the parameter is "mSpd", and value is 5000

If no parameter_ID is specified, then the entire parameter set is in the payload:

OVES eIoT Data Exchange Protocols¶

Messaging Topic Tree¶

MQTT Telemetry Topic Uplink Syntax (上行格式-Uplink)¶

MQTT Command Topic Downlink Syntax (下行格式-Downlink)¶

Application¶

Context¶

Examples¶

Complete MetaData Set¶

Complete Data Set¶

Select Section Data Set¶

Select Single Data¶

More examples for communication controls¶

修改APN的数据格式¶

修改休眠周期的数据格式¶

修改GPRS最大联网时间【time-out】的数据格式；¶

充值指令的数据格式；¶

主动上报和查询式上报模式选择的数据格式¶

Best Practices for Using the AWS IoT Shadow¶

OVES Device Avatars¶

OVES messaging topic tree format¶

Device General Attributes, States and Status (GASS)¶

Device Discovery¶

Common structure of Payload¶

Payload for specific device classes¶

ovCamp¶

Pump Controller¶