Difference between revisions of "Protocol:Raw"

Revision as of 07:07, 1 October 2014

The Raw protocol is one of several Protocols supported by the Serious Human Interface(tm) Platform (SHIP), and enables the GUI designer to push a typed-object (Byte, Short, String, etc.) out a communications port or receive a typed-object from a communications port.

Advantages of the Raw Protocol

• very quick prototyping of control of your system
• simple to use on the GUI side; a simple assignment pushes a value out the port
• simple to handle on the other side of the wire in your embedded code
• lightweight, so the GUI, for example, can communicate over the UART to an 8-bit MCU

Disadvantages of the Raw Protocol

• No packetization; your comms can get mis-aligned or out of sync
• No error checking; data corruption in transit cannot be detected
• No automatic retries or guaranteed delivery
• Single data type out, single data type in
• No firmware updates over this connection or access to advanced SHIPBridge protocol features

These disadvantages are significant. While the Raw Protocol can be useful in demos and initial bring-up as well as very simple applications, it is strongly recommended the designer consider the Modbus protocol for more robust communications. Better still, the sophisticated SHIPBridge protocol should be considered for flexible and powerful data connectivity as well as over-the-wire firmware updates and more.

Typed Data Transfer FIFOs

The Raw protocol is implemented as a pair of FIFOs, one for input, one for output. The depth of these FIFOs is runtime and platform dependent based on the amount of RAM available in the specific system. Each FIFO has a specific data type of object it can carry.

For example, you may wish to send Byte data out to your embedded device. In this case, the output FIFO would have the datatype of Byte.

The data type for the input FIFO may be different from that of the output FIFO. For example, your output FIFO could have the datatype of Byte but your input FIFO could have the datatype of String. In this configuration your GUI could send Byte data to the other MCU on the other end of the UART connection and that MCU would send back String data objects -- a sequence of UTF-8 characters with a null terminator.

The data type must be specific and unchanging during the operation of any given GUI, since there are no packet headers or otherwise that could indicate a message-by-message change in the type of data being transmitted. The embedded MCU or whatever is on the "other end of the wire" must be able to assume a specific format for the data coming and going, as must the GUI.

Building a Raw Protocol Link in SHIPTide

As with all protocols protocol in SHIP, a link node in the resource are binds a protocol to a communications channel.

In SHIPTide, in the Resources area under links, right click and "add link", then configure the link to instantiate a link node with Raw protocol bound to the SIM's UART0 asynchronous serial communications port.

When you do this action, unlike other protocols, the structure underneath the link will automatically populate with a fixed set of nodes:

• a linkset named "raw"
• a set of linkvars for managing the input and output FIFOs

The structure looks like this:

The linkvars are as follows:

iData and oData

The iData and oData linkvars are the input FIFO and output FIFO respectively. You can only access the end of the FIFOs: reading from iData fetches the top item from the input FIFO, and writing to oData pushes a new item onto the back of the output FIFO.

Note that accesses to iData and oData are fairly unique in SHIP: reading from iData removes an item from the FIFO and writing to oData adds and item to the FIFO. Be very cognizant of this behavior: reading twice from iData, for example, will remove two items from the FIFO (assuming there are two available).

When you first instantiate the link you'll notice (as in the picture above) there is an error on iData and oData. That is because the datatype property has not yet been set for the input and output FIFOs. Your first order of business will be to set these data types. For example, if you wish have byte input and byte output, set the datatype of iData and oData to Byte.

iState, oState, and the State constants

In the structure, you'll also notice two other linkvar nodes named iState and oState. These are special linkvars that indicate the state of the input and output FIFOs iData and oData respectively.

When activity happens on a FIFO, the respective state linkvar generates an event that can be listened to by a listener and action taken by a script handler.

The iState and oState linkvars can, at any given time, have one of the following values:

• ADDED - an item was added to that FIFO
• REMOVED - an item was removed from that FIFO
• FULL - FIFO became full after an ADDED
• EMPTY - FIFO became empty after a REMOVED
• OVERRUN -- FIFO overran (was full) after an attempted add
• UNDERRUN - FIFO was empty and a remove was attempted (applies to iData only)

For example, when data is put on the output FIFO, via code such as this: myLink.raw.oData = 0x00; the oState variable will become the value ADDED. If the FIFO became full as a result of that action, it will then changed to FULL. If the FIFO was full when the byte was attempted to be added to the FIFO, the oState variable will not go through the ADDED state but rather go directly to the OVERRUN state.

An additional example shows how to wait for and process incoming objects. Create a listener on your iState linkvar and set a condition looking specifically for the "ADDED" state:

This listener will wake up every time a new state happens on the iState linkvar. In this case, the condition property is testing that event to ensure it is the ADDED event. If it is, any enclosed script will be run.

For example, if this listener is inside a text node, and you want the text to change automatically to reflect the incoming Byte, you can make the structure look like this:

Note carefully that this action of "fetching" from iData in the text assignment removes the item from the FIFO. If you need multiple places in your GUI to access this new data item, you must create a holding variable in your GUI for this incoming value and assign iData to that holding variable and all the "consumers" of that data should access that holding variable. This mechanism ensures only one retrieval per incoming item.

These state variables have the very unusual property in SHIP of generating events when updated, even if unchanged.