IMPORTANT: Message Formatting Standard

Introduction

In order for our systems to effectively communicate with one another, members of the IST411 class met up and determined a standard for messages. If you have any issues with the proposed standard, or need to add more functionality to them, please discuss in the comments section. Requests will be followed up on via email and changes will be made to the standard.

We designed this message format so that all systems could use it for their inter-system communication needs. We have also defined a message handling protocol in Python.

Message Format

Each message shall be sent as a JSON string. If originating in a Python environment, a dictionary object shall be created with the following UPPERCASE keys (followed by data type):

CID: car identification code (str)
OID: origin identification code (str)
DID: destination identification code (str)
HC: system health code (Long)
TS: message time stamp (str)
TTL: message time to live duration in milliseconds (int)
PLD: message payload (str)
UID: message unique identifier (str)
CKS: md5 payload checksum (str)

This is a graphical representation of how each message should look:

This is an actual message sent in JSON format:

{"CID": "car10393", "HC": 3, "UID":"3h3453d3426da463d743", "DID": "brs", "CKS": "8fcffdcd1c1dbd62c199aa2a13c9043a", "TTL": 100, "OID": "ccs", "PLD": "payload: This message format defined by subteams", "TS": "1235542453.24325"}

Abbreviations and IDs

The car ID will be the same throughout the car. This is used to ensure that the systems in this car do not attempt to communicate with systems from other nearby cars. The OID and DID correspond with the subsystems that are communicating.
Each subsystem has a 3 letter code (note, it should always be LOWERCASE):

• brs = braking system
• clc = climate control system
• ems = energy management system
• ccs = command and control system
• mls = monitoring and logging system
• cns = connectivity and notification system
• dts = drivetrain system
• lis = lighting system
• sac = safety and access control system

Health Code Formatting

The health code will be a number scale (to be determined) signifying the status of a system or the urgency of a message. This is needed for monitoring purposes - more info to come later.

Payload Formatting

The payload formatting will be up to the individual subteams to decide. It would be nice to have something standard like a code and then a parameter (ie: br70 = braking power 70%) but that's up to you guys at this point.

Time Stamp Formatting

To be derived using the time taken from system clock and signifies the time the message was sent. This uses the time module in python and called automatically when a new message is instantiated. (The call is time.time() and it returns the seconds passed since the Epoch in local time) There is also a method in the Message class that converts the timestamp and returns a human readable time format. In order for this and the time to live functions to work, all system times must be synced at the beginning of vehicle operation. At the moment, we are assuming that all RPis will be synced via internet when initially deployed and then use a real time clock module to keep accurate time. A method may still be developed to sync system times across subsystems, but that is still being decided on.

Sample Code

When used in a Python environment, each message should be stored in a Message object. It can be found in the github MonitoringAndLoggingSystem directory under the name "Message.py"

If you would like to test the class and its associated methods, we have put together a python script called TestMessage.py in the github MonitoringAndLoggingSystem directory. I have simulated the steps involved in sending and receiving a message.
When sending, the protocol is as follows:

1. Create Message object, populate with data you are sending (don't worry about checksum, it is autocalculated at instantiation)
2. Convert message to JSON string with message.ConvertToJSON() method
3. Send resulting string

When receiving, the protocol is as follows:

1. Store message as a string
2. Convert message to dictionary object 
3. Create Message object with data from dictionary object (in this case, checksum needs to be included in parameters)
4. You have a message object! Profit!

FYI, the code for the receiving algorithm is located in the ConvertFromJSON() method in the TestMessage.py script. It's a simple copy and paste job from there. IST440 members - Joe should be making it available to you in your git repo soon.