Purdue University - LRVC Protocols v0...Updated on: 2/7/2012 LRVC Protocols 1.4 Common Definitions/Acronyms Term/Acronym Definition LRVC Project Long Range Vehicle Control Project

L R V C P r o t o c o l s P a g e | 1

Updated on: 2/7/2012 LRVC Protocols

LRVC Protocols v0.2 Revision History:

Date Version Author Changes

1/28/2012 v0.1 Matthew Wickesberg Initial draft.

2/9/2012 V0.2 Matthew Wickesberg Revised draft.



Contents 1. Introduction ......................................................................................................................... 4

1.1 The LRVC Protocol ........................................................................................................ 4

1.2 Intended Audience ....................................................................................................... 4

1.3 Background: LRVC Project Description ................................................................... 4

1.4 Common Definitions/Acronyms ................................................................................ 5

2. LRVC Protocol Overview .................................................................................................... 5

2.1 Extension of the Protocol ............................................................................................ 6

2.2 Protocol Phase Description ........................................................................................ 6

2.3 The LRVC Network ....................................................................................................... 7

3. LRVC Protocol Details....................................................................................................... 10

3.1 The Connection Phase - Overview ........................................................................... 10

3.2 The Connection Phase – The Details ....................................................................... 11

3.2.1 AccessDenied Message Structure: ..................................................................... 11

3.2.2 AccessGranted Message Structure: ................................................................... 12

3.2.3 GetKnownVehicles Message Structure: ............................................................ 12

3.2.4 NoKnownVehicle Message Structure: ............................................................... 12

3.2.5 KnownVehicle Message Structure: .................................................................... 12

3.2.6 LastKnownVehicle Message Structure: ............................................................ 12

3.2.7 VehiclesReceived Message Structure: ............................................................... 13

3.3 The Configuration Phase - Overview ...................................................................... 13

3.4 The Configuration Phase – The Details .................................................................. 14

3.4.1 GetObjects Message Structure: .......................................................................... 15

3.4.2 NoKnownObjects Message Structure: ............................................................... 15

3.4.3 KnownObject Message Structure: ..................................................................... 15

3.4.4 LastKnownObject Message Structure: .............................................................. 16

3.4.5 ControllerConfigured Message Structure: ....................................................... 17

3.5 The Control Phase – Overview ................................................................................. 18

3.6 The Control Phase – The Details .............................................................................. 19

3.6.1 Control Message Structure: ................................................................................ 19

3.6.2 Status Message Structure: .................................................................................. 19

3.6.3 VideoStreamDisabled Message Structure:....................................................... 20

3.6.4 VideoStreamEnabled Message Structure: ........................................................ 20



4. LRVC Server Design .......................................................................................................... 20

5. The LRV Embedded System Interface (Recommended) ................................................ 21

5.1 The LRV Command Message (Recommended) ..................................................... 22

5.2 The LRV Status Message (Recommended) ............................................................ 22



1. Introduction

1.1 The LRVC Protocol The LRVC Protocol is the communication protocol used to in the communication between LRVC Servers, Virtual Controllers, and LRVs. This document aims to give the reader a brief introduction into the LRVC project and serve as the standard for the LRVC Protocol. The LRVC Protocol can be described as a network technology, a software system, and a recommended LRV embedded interface. With that, the rest of the document is broken down into a few main sections

The LRVC Network Structure and Protocol (Sections 2 and 3) The LRVC Server Design (Section 4) A Recommended LRV Embedded System Interface (Section 5)

1.2 Intended Audience This document is intended for anyone who is interested in creating, extending, understanding, or designing the command and control system for LRVs, LRVC Servers, or Virtual Controllers.

1.3 Background: LRVC Project Description

The Long Range Vehicle Control (LRVC) project is a collaborative effort to design a system of communication and control of a wide variety of vehicles from anywhere in the world. It is being driven as a joint venture of Purdue University and Hong Kong University of Science and Technology (HKUST). Our aims are simple; to develop something that is easy to use, interesting in technical aspects, and demonstrates a level of knowledge that merits the issuance of a degree in ECE. The project is comprehensive in the sense that it contains the following components

LRVC Server software creation – The LRVC Server is a Java based server that mediates the communication of multiple Virtual Controllers and vehicles. The server will communicate via the LRVC Protocol with Virtual Controllers and custom communication protocols with vehicles. This part is created once for the project.

Virtual Controller creation – This is an Android application that configures itself to communicate for a specific vehicle. The application communicates solely via the LRVC Protocol. This part is created once for the project.

Long Range Vehicle (LRV) hardware platform development – This will consist of creating a remote controlled special utility vehicle that can communicate and be controlled by an LRVC Server. This includes design and creation of a PCB integrating various sensory equipment, PandaBoard setup, Wireless communication setup, and USB camera integration. This part is created in a per team basis.

Long Range Vehicle (LRV) embedded system creation - This is the embedded software that allows a vehicle to communicate and be controlled by the LRVC Server. Additionally, most teams will create embedded software to integrate sensory information and add special functionality to a vehicle. This part is created in a per team basis.

The LRVC project’s fledgling vehicles will be the following; A tank platform, called Super Tank, being developed by the Purdue team and a ?? platform being developed by HKUST.



1.4 Common Definitions/Acronyms

Term/Acronym Definition

LRVC Project Long Range Vehicle Control Project - The focus of the Purdue and HKUST team’s Senior Design projects.

LRV Long Range Vehicle – The vehicle that is controlled by a Virtual Controller via the LRVC Protocol.

LRVC Protocol Long Range Vehicle Control Protocol – The method/specification of communication between a Virtual Controller and an LRV.

LRVC Server Long Range Vehicle Control Server – The intermediary that understands both the LRVC Protocol and an LRV’s embedded interface. Additionally, it facilitates the communication between multiple Virtual Controllers and LRVs concurrently.

Virtual Controller An android app that allows a User to control an LRV. Its termed ‘virtual’ because the controller is implemented in software rather than hardware.

User The person that is controlling an LRV via a Virtual Controller.

HKUST Hong Kong University of Science and Technology.

Super Tank The LRV platform that is being developed by the Purdue team.

MAC Address Media Access Control Address – A unique identifier for a communication systems network interface hardware.

Authentication Port A port on the LRVC Server that facilitates Virtual Controller connection and authentication. This is always TCP Port 9999 on the LRVC Server.

Control Port A port on the LRVC Server that facilitates non-video command and control between a Virtual Controller and an LRV. This is always an even port and is TCP Port 10000+ on the LRVC Server.

Video Port A port on the LRVC Server that facilitates video feedback from an LRV to a Virtual Controller. This is always an odd UDP port and is 1 greater than the Virtual Controller’s TCP control port on the LRVC Server.

2. LRVC Protocol Overview The LRVC Protocol provides a framework for communications between a Virtual Controller and an LRV. The LRVC Protocol has been designed to be flexible enough to accommodate a diverse set of functionalities in an LRV yet structured enough to yield a fair amount of code re-use between LRV implementations. Specifically, it has been designed and constructed to achieve the following properties;

Property Reason/Implementation

Android Compatible The protocol exposes a set of services that are its public interface. This service set interface can then be interfaced with an Android application.

Extendable The protocol allows for extension of communication through plug-and-play construction of GUI components with specific data bindings on an Android App. More on this explained following this chart.

Robust UI Support The protocol provides an interface that supports robust interactive GUI components for the Virtual Controller.

Streams Video Efficiently

The protocol is designed to use RTP (Real Time Protocol). RTP is a commercial quality, relatively simple protocol used in many audio visual applications for streaming data.

Handles Multiple Controllers Concurrently

The Connection Phase allocates the Control port for a Visual Controller connection. This allocation is decided at runtime and can be dynamically allocated.

Secure The Connection Phase relays all connections through a known Authentication Port. This port runs a service that actively checks the MAC address of a device and compares it with a known



Property Reason/Implementation

set of trusted MAC addresses.

2.1 Extension of the Protocol

The basic idea is that the protocol allows extension and custom implementation through creating custom GUI objects (Java objects that contain a known “CustomLRVCObjects” interface), serializing them through the standard Java library, and interfacing them through the controllers GUI. Thus, the custom implementation is achieved not by modifying the LRVC Protocol but by adjusting the bindings of these GUI components. A team that would like to create their own “implementation” of the protocol to run their own LRV would execute the following steps:

Design a Virtual Controller with the desired functionality that extends the base Virtual Controller layout as depicted in Figure XX.

Designate unique opcodes that all of your non-standard GUI components will output on your Virtual Controller when they are activated.

Designate an input interface to provide feedback for every one of your on-standard GUI components.

Wrap your above design into a set of unique Java classes that implement the CustomLRVCObject interface and extend JPanel.

Compile these objects and upload them into the LRVC Server’s GUI Object Repository. Write a set of KnownObject messages that will serve to download your non-standard GUI

objects onto a Virtual Controller. Upload this into the LRVC Server’s Controller Layouts Repository.

Add the vehicle’s MAC address to the knownMACs.txt list on the LRVC Server. Add your android device’s MAC address to the knownMACs.txt list on the LRVC Server. Create your LRV’s embedded system to handle the buffered opcode stream being sent to

your LRV or create a thin translator class that converts the buffered opcode stream to a communication of your choice.

Create a new unique Vehicle UID and add it to the LRVC Server’s VehicleToUIDMapping class.

Upload a picture and description of your LRV and upload it to the LRVC Server’s Vehicle Description Repository. The picture must be a bitmap format (.bmp) and be named ###.bmp where ### is your Vehicle’s UID. The description is ###.txt where ### is your Vehicle’s UID.

2.2 Protocol Phase Description The LRVC Protocol operates in three distinct phases for a given Virtual Controller. Each of the phases are mutually exclusive with each other and utilize 1 or more TCP/IP connections for command and control of the LRV.

The first phase is the Connection Phase - This phase is responsible for the security and resource allocation of the LRVC Server along with providing services for the Virtual Controller to provide a User with a selection screen of LRV options.

The second is the Configuration Phase – This phase is responsible for the configuration of a Virtual Controller. It populates the Virtual Controller with a standard interface of



Standard Objects and a unique set of custom objects called Non-Standard Objects. These objects all have a known interface. Their input is a generic byte[] which is operable by the object and their output is a 8 bit opcode. These inputs and outputs create a set of data bindings that allow the protocol to by dynamic and facilitate communication to numerous unique LRVs.

The third is the Control Phase – This phase is responsible for synchronously distributing opcodes (aka commands) to an LRV at the rate of 10Hz. Additionally, it wraps and transports the LRV’s feedback as Status Messages back to the Virtual Controller at a rate of 10Hz. Lastly, it facilitates a video feed from the LRV back to the Virtual Controller at a target rate of 20Hz.

2.3 The LRVC Network

The LRVC Network is created by the following layout of Virtual Controllers, LRVC Server, and LRVs. In this topology, the LRVC Server is simply a central communication hub between controllers and vehicles.

Figure 1 - An LRVC Network



Specifically, the LRVC Network has a connection topology of the following.

Figure 2 - LRVC Network Port Mappings

The diagram pictorially represents the ranges of mutually exclusive TCP and UDP ports that can

be used in an LRVC network. The sequence for a normal communication session of a Virtual

Controller with the LRVC Server is the following.

The first connection that takes place is a controller attempting to gain access to command

and control services of the LRVC service. This is done by a controller initiated

connection with the LRVC Server’s Authentication Port. The Authentication Port is

outlined in blue and is always TCP 9999.

Once the controller has been deemed trusted the LRVC Server then responds with the

location of an allocated Control Port that the Virtual Controller may use. After it has

been signaled that the message has been received the LRVC Server severs the

Authentication Port connection leaving room for a new Virtual Controller to connect and

get authenticated.



The Virtual Controller then proceeds to connect to its assigned Control Port (outlined in

green). A series of communications occur that present the user with a selection guide of

vehicles to choose from.

Once the user has chosen a vehicle the LRVC Server attempts to establish a connection

with the LRV. The LRVC does these connections through the TCP ports outlined in

orange. Commands are now able to be communicated from the controller to the vehicle

and feedback is able to be relayed back to the controller.

After this the LRVC Server tells the user if a video stream may be obtained. If it can the

Controller connects to the LRVC Server’s UDP Video Port (outlined in orange) and the

LRVC Server connects with the vehicle’s Video Port. After valid connections the video

is streamed from the vehicle to the Virtual Controller via RTP or pixel dump screen

captures.



3. LRVC Protocol Details

3.1 The Connection Phase - Overview Here’s a look at a typical connection communication:

Figure 3 - Authenticating, Connecting, and Obtaining Known Vehicles From the LRVC Server

Explanation: The connection phase will be facilitated by an initial controller request to the LRVC Server. The very first action will be an attempt to connect on the “Authentication” port of 9999. This Authentication port will serve as a security gateway to get into the LRVC Server. There a few responses that can happen after an authentication connection attempt. First, the port may not be open as it may be in use by another controller that is trying to authenticate. This will result in a connection error by the TCP/IP stack. If the authentication port is available a connection of the controller to TCP 9999 will occur. Once the connection occurs, the LRVC Server will compare the controller’s MAC address to a list of trusted MACs. If the controller is secure and its MAC is trucsted the Server will respond with an AccessGranted message that contains information as to which port the controller should connect to next. If the controller is not trusted (i.e. MAC is not in the trusted MAC list) the LRVC Server will respond with an AccessDenied message and sever the connection.



Once the LRVC Server deems it is dealing with a trusted device it will map the trusted device to a unique “Control” port that the device may use. This control port is the port that the controller was supplied with in the AccessGranted message. The Server will then wait for the controller to connect to its Control port while serving other controllers concurrently. Once the controller establishes a connection with its Control Port the controller will issue a GetKnownVehicles message to the Server. The Server will then check to see how many vehicles it has registered to it and will It will respond with the appropriate NoKnownVehicle, KnownVehicle, and LastKnownVehicle response messages. This will serve to populate the controller with a list of vehicles that it can select to control. Upon a LastKnownVehicle response the controller will configure its Android application to show the user a list of selectable vehicles. After that has been successfully completed the controller issues a VehiclesReceived response message.

3.2 The Connection Phase – The Details First, heres a complete reference to the possible messages used during the Connection Phase.

Message Dir.

Description

AccessDenied S->C Response message that tells the Controller that it has been denied access. After this message

the communication is terminated.

AccessGranted

S->C Response message that tells the Controller that it is trusted and it can proceed. In this response message there is a Control Port field that tells the Controller which TCP port has been allocated as its Control Port.

GetKnownVehicles

C->S A request by the Controller that can only be facilitated on the Controller’s own Control port. It initiates a sequence of responses that tell the Controller which vehicles are active and controllable.

NoKnownVehicle S->C

A response to a GetKnownVehicles request that tells the Controller that there are no controllable vehicles at this time.

KnownVehicle

S->C A response that contains information about a vehicle that is controllable. The response contains a small bitmap picture of the vehicle and a description of its functions that can be displayed to the User. Also, the response implicitly implies that there are additional vehicles that are controllable and additional KnownVehicle and LastKnownVehicle responses are coming.

LastKnownVehicle

S->C A response that contains information about a vehicle that is controllable. The response contains a small bitmap picture of the vehicle and a description of its functions that can be displayed to the User. Also, the response implicitly implies that this is the last vehicle that is controllable.

VehiclesReceived C->S A response from the Controller to the Server dictating that all of the KnownVehicle and

LastKnownVehicle requests have been received properly.

3.2.1 AccessDenied Message Structure:

Field Length Location

Value/Description

LRVC Header ID 1 [0:0]

x”00”

LRVC Message ID 1 [1:1]

x"00”

Denial Message N [2:End] A sequence of ASCII characters that give some information as to why access has

been denied.



3.2.2 AccessGranted Message Structure:


Value/Description


x”00”


x"01”

Acceptance Message

N [2:End] A sequence of ASCII characters that give some information as to why access has been granted.

3.2.3 GetKnownVehicles Message Structure:


Value/Description


x”00”


x"02”

3.2.4 NoKnownVehicle Message Structure:


Value/Description


x”00”


x"03”

3.2.5 KnownVehicle Message Structure:


Value/Description


x”00”


x"04”

Vehicle UID 4 [2:5] An unsigned integer that uniquely maps to a vehicle. This mapping is

maintained in the LRVC Server.

Image Size 4 [6:9]

An unsigned integer that has the size of the bitmap file (.bmp) that follows.

Vehicle Picture N [10:9+N]

The picture of the vehicle. Bitmap format (bmp).

Vehicle Description

M [10+N:End] A string of ASCII characters that give a brief description of the vehicle.

3.2.6 LastKnownVehicle Message Structure:


Value/Description


x”00”


x"05”




Value/Description

Vehicle UID 4 [2:5] An unsigned integer that uniquely maps to a vehicle. This mapping is

maintained in the LRVC Server.

Image Size 4 [6:9]

An unsigned integer that has the size of the bitmap file (.bmp) that follows.

Vehicle Picture N [10:9+N]

The picture of the vehicle. Bitmap format (bmp).

Vehicle Description

M [10+N:End] A string of ASCII characters that give a brief description of the vehicle.

3.2.7 VehiclesReceived Message Structure:


Value/Description


x”00”


x"06”

3.3 The Configuration Phase - Overview

Once a Controller has finished the Connection Phase and the User has selected a vehicle the Configuration Phase begins. This phase is responsible for setting up the “Virtual” Controller correctly and has a system for creating proper controller bindings. Below is a typical Configuration Phase.

Figure 4 - Typical Configuration Phase Communications

Explanation: We are now operating exclusively on the Control Port that has been ascribed for the controller. At the beginning of this phase the Controller now displays a scrollable list of vehicle selections that the



user can choose to control. Once the user selects a vehicle the Controller issues a GetObjects request to get the controller objects that are associated with the selected vehicle. The Server then goes on to send a sequence of KnownObject and LastKnownObject messages that contains all of the information that is required to configure the Controller’s GUI and its objects bindings. One of the first things to note is that every Controller GUI can be broken up into 2 different distinct categories; (1) Standard Objects, objects that every controller explicitly contains. These include a directional pad, fire button, a status message area, and a video display amoungst others. (2) Non-Standard Objects, objects that are specific to a particular vehicle. These include special functions and feature GUI elements such as, turret movement, radar display, etc… Each of the KnownObject and LastKnownObject messages correspond to a Non-Standard Object that can be placed on the Virtual Controller’s GUI. The messages contain information regarding the layout, the type, the characteristics, and the interface into the object. The interface can be broken down into 2 parts. (1) Outputs – This is the opcode that is sent out by the controller when the particular object is activated. (2) Inputs – These are status messages that are represented as byte arrays. These input byte arrays allow custom objects to display fairly interesting behavior such as a radar that can display blips where obstacles have been found. Finally, once all these objects have been received the Controller finishes the Configuration Phase by sending a ControllerConfigured message to the LRVC Server.

3.4 The Configuration Phase – The Details First, heres a complete reference to the possible messages used during the Configuration Phase.

Message Dir.

Description

GetObjects C->S This message is issued by the Controller after a user has selected a vehicle to control. It

requests any non-standard objects that need to be placed on the “Virtual” Controller.

NoKnownObjects S->C

A response to a GetObjects request that tells the Controller that there are no non-standard objects that need to be added to the virtual controller.

KnownObject

S->C A response that contains information about a non-standard component that will be on the Virtual Controller. The response contains various details as to how the object will be placed on the controller and how the object will be interfaced to (a.k.a. its bindings). The bindings include what opcodes that the object can issue and what bytes can be received by the object. Also, the response implicitly implies that there are additional non-standard objects that are going to be placed and additional KnownObject and LastKnownObject responses are coming.

LastKnownObject

S->C A response that contains information about a non-standard component that will be on the Virtual Controller. The response contains various details as to how the object will be placed on the controller and how the object will be interfaced to (a.k.a. its bindings). The bindings include what opcodes that the object can issue and what bytes can be received by the object. Also, the response implicitly implies that there are additional non-standard objects that are going to be placed and additional KnownObject and LastKnownObject responses are coming. Also, the response implicitly implies that this is the last non-standard object to be placed.

ControllerConfigured C->S A response from the Controller to the Server dictating that all of the NoKnownObject,

KnownObject and LastKnownObject requests have been received properly. It signals that the “Virtual” Controller has finished being configured.



3.4.1 GetObjects Message Structure:


Value/Description


x”00”


x”07”

Requested Vehicle UID

4 [2:5] The vehicle UID that appeared in the Controller’s received KnownVehicle and LastKnownVehicle messages. This is the UID of the vehicle that the User selected to control.

3.4.2 NoKnownObjects Message Structure:


Value/Description


x”00”


x"08”

3.4.3 KnownObject Message Structure:


Value/Description


x”00”


x"09”

Object Props

1 [2:2] Bit 0 – (0) = Is a Java Object, (1) = Is an Custom Object (Implements the “CustomLRVCObject” interface) Bit 1 – (0) = Java Object is a Rectangle, (1) = The Java Object is a Circle Bit 2 – (0) = Java Object does not have a label, (1) = It does have label. Bit 3 – (0) = Java Object is not colored, (1) = Java Object is colored. Bit 4 – (0) = Java Object is a not a TextBox, (1) = It is a TextBox Bit 5 – (0) = Not Implemented Yet Bit 6 – (0) = Not Implemented Yet Bit 7 – (0) = Not Implemented Yet

Object Label Size

1 [3:3] Number of ASCII characters that comprise the label. Only exists if the object satisfies the following requirements:

- It is a Java Object (ObjectProps[0] = ‘0’) - It is an object with a label (ObjectProps[2] = ‘1’)

Object Label

N [4:3+N] The label that will be written on the object. This is encoded in single byte ASCII. Only exists if the object satisfies the following requirements:


Object Background Color

4 Varies The background color of the object represented as a 4 byte alpha RGB value. Only exists if the object satisfies the following requirements:

- It is a Java Object (ObjectProps[0] = ‘0’) - It is a colored object (ObjectProps[3] = ‘1’)

Object Text Color

4 Varies The text color of the object represented as a 4 byte alpha RGB value. Only exists if the object satisfies the following requirements:


Object UID 4 Varies An unsigned integer that uniquely maps to an object on a controller. This

mapping is maintained in the LRVC Server for each controller. NOTE: Can’t be a standard object, hence can’t start with a ‘0’ bit.




Value/Description

CustomLRVCObject Size

4 [3:6] An unsigned integer that has the size of the serialized class that will follow in the message. Only exists if the object satisfies the following requirements:

- It is a Custom Object (ObjectProps[0] = ‘1’)

CustomLRVCObject M [7:6+M] A serialized compiled object file that will be layed out onto the Virtual

Controller. Only exists if the object satisfies the following requirements: - It is a Custom Object (ObjectProps[0] = ‘1’)

Panel Selection 1 Varies Which panel should the object be placed into (1 or 2). Values may be x”01” or

x”02”.

Row Number 1 Varies Which Row of the selected panel should the object be placed in. Possible

values are 1 – 4.

Column Number 1 Varies Which Column of the selected panel should the object be placed in. Possible

Values are 1-4.

Opcode 1 Varies Opcode that has been mapped to the object. This is the unique byte that is

communicated every time this object is “Activated” or “Active.” NOTE: This may not be a known Opcode that is one of the standard opcodes.

3.4.4 LastKnownObject Message Structure:


Value/Description


x”00”


x"09”

Object Props

1 [2:2] Bit 0 – (0) = Is a Java Object, (1) = Is an Custom Object (Implements the “CustomLRVCObject” interface) Bit 1 – (0) = Java Object is a Rectangle, (1) = The Java Object is a Circle Bit 2 – (0) = Java Object does not have a label, (1) = It does have label. Bit 3 – (0) = Java Object is not colored, (1) = Java Object is colored. Bit 4 – (0) = Java Object is a not a TextBox, (1) = It is a TextBox Bit 5 – (0) = Not Implemented Yet Bit 6 – (0) = Not Implemented Yet Bit 7 – (0) = Not Implemented Yet

Object Label Size

1 [3:3] Number of ASCII characters that comprise the label. Only exists if the object satisfies the following requirements:


Object Label

N [4:3+N] The label that will be written on the object. This is encoded in single byte ASCII. Only exists if the object satisfies the following requirements:


Object Background Color

4 Varies The background color of the object represented as a 4 byte alpha RGB value. Only exists if the object satisfies the following requirements:


Object Text Color

4 Varies The text color of the object represented as a 4 byte alpha RGB value. Only exists if the object satisfies the following requirements:


Object UID 4 Varies An unsigned integer that uniquely maps to an object on a controller. This

mapping is maintained in the LRVC Server for each controller. NOTE: Can’t be a standard object, hence can’t start with a ‘0’ bit.

CustomLRVCObject Size

4 [3:6] An unsigned integer that has the size of the serialized class that will follow in the message. Only exists if the object satisfies the following requirements:

- It is a Custom Object (ObjectProps[0] = ‘1’)




Value/Description

CustomLRVCObject M [7:6+M] A serialized compiled object file that will be layed out onto the Virtual

Controller. Only exists if the object satisfies the following requirements: - It is a Custom Object (ObjectProps[0] = ‘1’)

Panel Selection 1 Varies Which panel should the object be placed into (1 or 2). Values may be x”01” or

x”02”.

Row Number 1 Varies Which Row of the selected panel should the object be placed in. Possible values

are 1 – 4.

Column Number 1 Varies Which Column of the selected panel should the object be placed in. Possible

Values are 1-4.

Opcode 1 Varies Opcode that has been mapped to the object. This is the unique byte that is

communicated every time this object is “Activated” or “Active.” NOTE: This may not be a known Opcode that is one of the standard opcodes.

3.4.5 ControllerConfigured Message Structure:


Value/Description


x”00”


x"0B”



3.5 The Control Phase – Overview Once a Controller has finished the Configuration Phase and the User is now in control of the vehicle. This is called the Control Phase. Below is a typical Control Phase.

Figure 5 - Controlling Communications

Explanation: The Control Phase is comprised of 2 concurrent processes, 1 that is required, and 1 that is optional. The required process is the Control Process (Process #1). This process synchronously sends control information from the Controller to the LRVC Server in the form of Control Messages through the main Control Port at 10 Hz. These Control Messages contain a buffered list of activated GUI component opcodes. Each Control Message is responded to, in kind, by Status Messages. These Status Messages contain a list of statuses and byte stream responses for various GUI components on the Controller. The optional process is the Video Stream Process (Process #2). This process will stream video via the Real Time Protocol (RTP) on a UDP port. The port number for this UDP port is always 1 more



than the Control Port number, we’ll call this the Video Port. This stream can be initiated by a connection attempt by the Controller on the Video Port. The Server then analyzes if its possible to stream video to the controller and responds with an appropriate VideoStreamDisabled or VideoStreamEnabled message. If the video is enabled then the RTP Video Snippets stream to the Controller at 20Hz.

3.6 The Control Phase – The Details First, heres a complete reference to the possible messages used during the Control Phase.

Message Dir.

Description

Control C->S This message is issued by the Controller every 10Hz indicating all of the opcodes that were

“active” in the last 100 ms.

Status

S->C A response to every Control message that has been received. This message also buffers various events and feedback as Status instances and includes them as a list. The Status Instance contains a target GUI Component on the controller and a byte-stream that will be processed by the GUI component. NOTE: Only CustomLRVCObjects may or certain special Standard Objects may process these byte streams.

VideoStreamDisabled S->C A simple response message indicating that a video stream can not be sent to the Controller.

This allows the Controller to disable all Video Streaming software gracefully.

VideoStreamEnabled

S->C A simple response message indicating that a video stream is ready to send to the Controller. This allows the Controller to enable all Video Streaming software and handle RTP Video Snippets at a 20 Hz rate.

RTP Video Snippets S->C A section of video that uses UDP wrapped implementation of the Real Time Protocol, RTP.

3.6.1 Control Message Structure:


Value/Description


x”00”


x"0C”

Num Of Opcodes 2 [2:3] An unsigned short that contains the numbe of following Opcodes that will be

set interpreted as “Active” by the LRVC Server.

List Of Opcodes N [4:3+N]

The active opcodes.

3.6.2 Status Message Structure:


Value/Description


x”00”


x"0D”

Num Of Statuses 2 [2:3] An unsigned short that contains the numbe of following Status/Feedback

events that will be communicated back to the Controller.

List of Status Events

N [4:3+N] The structure of every status/feedback event to be communicated is the following: 4 Byte ObjectUID – The UID of the Controller’s GUI Object that will receive the status update/feedback. 1 Byte Event Type – x”00” Simple Event with no byte stream response




Value/Description

X"01” Event with a byte stream response 1 Byte Simple Response – x”FF” – Successful response to Control request. x”00” – Unsuccessful response to Control request (Exists if the Event is of not simple and is of type x”01”) 4 Byte Response Length – An unsigned integer M Bytes – The byte stream response that will be sent to the object indicated by the ObjectUID field.

3.6.3 VideoStreamDisabled Message Structure:


Value/Description


x”00”


x"0E”

Denial Message N [2:End] A sequence of ASCII characters that give some information as to why the Video

Stream has been denied.

3.6.4 VideoStreamEnabled Message Structure:


Value/Description


x”00”


x"0F”

Acceptance Message

N [2:End] A sequence of ASCII characters that give some information as to why access has been granted.

4. LRVC Server Design

The LRVC Server will be designed in such a way to easily facilitate a synchronous stream of

opcodes to the vehicle. These opcodes will serve as the vehicles unique commands. It will be

structured in such a way that it will contain and operate on the following files;

A repository of compiled java classes (.class files) – This will serve as the repository of

unique non-standard objects that may be placed on a Virtual Controller.

A repository of Virtual Controller “Layout” files – These will dictate the order of sending

the non-standard GUI objects to a controller and their placement. The LRVC Server will

operate on these and wrap the objects in KnownMessage responses to send to the Virtual

Controller. Each vehicle will have a Virtual Controller Layout file. These layout files

will also contain the Vehicle UIDs.

A repository of known vehicle images (bmp files) and descriptions (txt files)

A trusted MAC list.

Possibly some adapter classes to tailor the LRVC to vehicle communication scheme to

better fit a vehicle’s embedded system. (This is Not recommended)



5. The LRV Embedded System Interface (Recommended)

The easiest way to connect your vehicle to the LRVC Server is through a buffered serial stream

of characters as such;

Figure 6- LRV's Embedded System - Communication Sub-System Design

As you can see, the embedded system’s communication sub-system is quite simple in its design.

It consists of a Wifi receiver continuously receiving command requests and sending status

responses. Since communicating these messages through the internet through TCP breaks the

guarantee of synchronousity of the stream we have to have an additional mechanism for

synching the status responses back to the Virtual Controller. This is done through a buffer in

SRAM that handles asynchronous requests through a USART port. Then, the embedded system

launches synchronously timed flushes of the command buffer, executing everything inside of it.

This guarantees that a single, all inclusive, status response is communicated back to the LRVC

Server every 100 ms.

One major thing to note is that the structure of these command and status messages are not that

of the ones communicated to and from the Virtual Controller. These messages are specific to

communicating with your LRV and are simpler to handle.

For instance, the command messages are simply a sequence of bytes with each byte containing

an opcode that was generated by the Virtual Controllers gui. These bytes are then interpreted by

the command and control system on the LRV accordingly. This property of all commands being

fixed length makes making the command and control system much easier to design.



Lastly, the status messages are structured as a sequence of component feedbacks. The complete

structure is documented in the table below.

5.1 The LRV Command Message (Recommended)


Value/Description

Opcodes

N [0:N-1] A sequence of 8 bit opcodes. Each opcode specifies a specific command (some of which may be nop) for the LRV to execute. Additionally, the LRVC Server structures these messages in such a way that no opcodes repeat, hence all are unique.

5.2 The LRV Status Message (Recommended)


Value/Description

# Feedback Frames

4 [0:3] An integer containing the number of feedback frames that will follow.

Feedback Frame

- - Each Feedback Frame contains the following;

Opcode to feedback to. – 1 Byte Length of feedback stream in bytes – 4 Bytes The feedback stream to send to the Virtual Controller’s component.

Specified by the opcode. – N Bytes

Documents

Purdue University - LRVC Protocols v0...Updated on: 2/7/2012 LRVC Protocols 1.4 Common Definitions/Acronyms Term/Acronym Definition LRVC Project Long Range Vehicle Control Project