Protocol:Raw

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 and, 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 or, better still, the sophisticated SHIPBridge protocol 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).