Difference between revisions of "Protocol:SHIPBridge"

Latest revision as of 23:17, 3 November 2016

What is the SHIPBridge Protocol?

SHIPBridge is a comprehensive proprietary communications protocol available in SHIP Version 5.

The SHIPBridge protocol enables over-the-wire access to files stored on the SIM/SCM, updates of firmware and GUI, as well as the exchange of typed data variables. SHIPBridge is intended to function over all available communication ports available on a module (i.e., USB, UART, SPI, TCP/IP, etc.), however USB and UART are currently the only validated interfaces on most modules. Future TCP/IP support will enable firmware updates, status and monitoring, and data exchange from cloud or server based entities to the modules.

SHIPBridge has the following high-level capabilities:

Robust bidirectional command-response architecture

Arbitrary physical layer support including UART, USB Device (future: SPI, Ethernet, WiFi, and Bluetooth)
Binary framed packet protocol with CRCs for message integrity
Multi-session: multiple controllers can simultaneously access a SIM over the same or a different physical interface

SIM system information and control

Reboots, status checks, firmware validation, and more

Comprehensive and powerful data movement

Shared variable philosophy to exchange status and control data
All simple data types (Boolean, Byte, Short, Integer, Long, Float, Double, String, Buffer)
Polled or Push data, on a per-variable basis
Able to prioritize run-time traffic for flexible bandwidth management
Fully bidirectional communication

Completely Upgradable

Over-the-wire updates for all firmware images (i.e., boot loaders, applications, GUI)

Planned Future Features

Flexible over-the-wire file system access

Read/write access to all removable and fixed storage media (USB Thumb drives, SDCards, on-board file systems)
Write firmware images to file system to allow background transfer of files and automatic upgrade on next boot

Persistent variable storage

Read/write access to persistent storage registry variable values

Extensive debugging capabilities

Breakpoint and step through GUI execution
Read/write access to GUI variables and node properties

SHIPBridge is currently used from SHIPTide over USB to update the firmware and GUI on SIMs.

SHIPBridge Release Status

SHIPBridge protocol core functionality has been in use since the release of v5. Features are continuously being refined and added throughout the v5 releases.

SHIPBridge API

The SHIPBridge API code has not yet been fully released, however it is available to registered SIM owners to use in conjunction with Serious products upon request. Customers are able to port the API to their own target environment for advanced communications and control of the SIM.

The SHIPBridge API code has been validated in the following environments:

Renesas e2studio, GCC embedded C projects for RX, SH, and ARM Cortex-A9 MCU architectures, running on Micrium OS-III
Eclipse IDE for C/C++, IAR embedded C project for ARM Cortex-M4 MCU architecture, running on FreeRTOS V7
QtCreator, GCC C++ project for x86, running on Windows 7 and greater

Currently, the SHIPBridge API code only supports being compiled for 32-bit output. SHIPBridge also requires OS features such as tasks and queues, Serious is investigating how best to provide a unified code base which supports OS-based implementations and "super loop" implementations. Contact Serious for more information on these developments.

SHIPBridge Documentation and More Information

@@ Line 1: / Line 1: @@
-== What is the {{Protocol|SHIPBridge|SHIPBridge Protocol}}? ==
+__NOTOC__
+== What is the SHIPBridge Protocol? ==
+SHIPBridge is a comprehensive proprietary communications protocol available in SHIP Version 5.
-SHIPBridge is a comprehensive proprietary communications protocol coming in SHIP Version 5 {{v5}} with the following high-level capabilities:
+The SHIPBridge protocol enables over-the-wire access to files stored on the SIM/SCM, updates of firmware and GUI, as well as the exchange of typed data variables. SHIPBridge is intended to function over all available communication ports available on a module (i.e., USB, UART, SPI, TCP/IP, etc.), however USB and UART are currently the only validated interfaces on most modules. Future TCP/IP support will enable firmware updates, status and monitoring, and data exchange from cloud or server based entities to the modules.
-* Robust bi-directional command-response architecture
-** Physical layer support including UART, USB Device, and, in the future, SPI, Ethernet, WiFi, and Bluetooth
-** Ever packet is CRC'd for accuracy
-* SIM system information and control
-** Reboots, status checks, and more
-* Complete and powerful data movement
-** All SHIP-supported data types (Boolean, Byte, Short, Integer, Float, String)
-** Prioritized poll or push-on-change per shared variable for flexible bandwidth management
-** Bidirectional (both SIM and Host can poll and push)
-* Flexible over-the-wire file system access
-** Over-the-wire updates for all files, including firmware, boot loaders, GUI files, and more
-** Abstracted remote file system access to all file systems on the SIM from an attached device
-** Access to removable and fixed media from the host (USB Thumb drives, SDCards, on-SIM flash file systems)
-The SHIPBridge protocol is currently used from [[SHIPTide]] over USB to update the firmware and GUI on your SIM, where the PC is acting as the Host.
+SHIPBridge has the following high-level capabilities:
+===Robust bidirectional command-response architecture===
+* Arbitrary physical layer support including UART, USB Device (future: SPI, Ethernet, WiFi, and Bluetooth)
+* Binary framed packet protocol with CRCs for message integrity
+* Multi-session: multiple controllers can simultaneously access a SIM over the same or a different physical interface
-== SHIPBridge Release Status ==
+===SIM system information and control===
+* Reboots, status checks, firmware validation, and more
+===Comprehensive and powerful data movement ===
+* Shared variable philosophy to exchange status and control data
+* All simple data types ({{DataType|Boolean}}, {{DataType|Byte}}, {{DataType|Short}}, {{DataType|Integer}}, {{DataType|Long}}, {{DataType|Float}}, {{DataType|Double}}, {{DataType|String}}, {{DataType|Buffer}})
+* Polled or Push data, on a per-variable basis
+* Able to prioritize run-time traffic for flexible bandwidth management
+* Fully bidirectional communication
+===Completely Upgradable===
+* Over-the-wire updates for all firmware images (i.e., boot loaders, applications, GUI)
+==Planned Future Features==
-The SHIPBridge protocol is currently in the late stages of development, and is pending release with v5.0.
+===Flexible over-the-wire file system access===
+* Read/write access to all removable and fixed storage media (USB Thumb drives, SDCards, on-board file systems)
+* Write firmware images to file system to allow background transfer of files and automatic upgrade on next boot
-== SHIPBridge Host Reference Code ==
+===Persistent variable storage===
-Reference code is in development, and will be supplied on mySerious.com for registered SIM owners to download and use in conjunction with Serious products. You will be able to use and port this code on your own microcontroller for communications and control with the SIM of your choice running SHIPBridge.
+* Read/write access to persistent storage registry variable values
-Reference code is currently planned for 2 initial development environments:
+===Extensive debugging capabilities===
-# a PC-based MS Visual Studio project for custom PC connectivity to SIMs over USB and UART
+* Breakpoint and step through GUI execution
-# a Renesas RX111 e2studio project using Serious "SHIPWare" base-level infrastructure on Micrium uC/OS-III and FreeRTOS, for use directly on the SCM117 and upcoming SCM118 and for simple porting to other MCU architectures
+* Read/write access to GUI variables and node properties
-Serious is investigating providing C reference code for older "super loop" type host software implementations. Contact Serious for more information.
+SHIPBridge is currently used from [[SHIPTide]] over USB to update the firmware and GUI on SIMs.
-== SHIPBridge Documentation and More Information ==
+== SHIPBridge Release Status ==
-Contact Serious for a copy of the SHIPBridge Architectural Specification under NDA. The specification will be non-NDA coincident with the v5.0 release.
+SHIPBridge protocol core functionality has been in use since the release of v5. Features are continuously being refined and added throughout the v5 releases.
-Other documentation:
+== SHIPBridge API ==
-[[SHIPBridge:Architectural Overview]]
+The SHIPBridge API code has not yet been fully released, however it is available to registered SIM owners to use in conjunction with Serious products upon request. Customers are able to port the API to their own target environment for advanced communications and control of the SIM.
+The SHIPBridge API code has been validated in the following environments:
+# Renesas e2studio, GCC embedded C projects for RX, SH, and ARM Cortex-A9 MCU architectures, running on Micrium OS-III
+# Eclipse IDE for C/C++, IAR embedded C project for ARM Cortex-M4 MCU architecture, running on FreeRTOS V7
+# QtCreator, GCC C++ project for x86, running on Windows 7 and greater
-== SHIPBridge Architectural Overview ==
+Currently, the SHIPBridge API code only supports being compiled for 32-bit output. SHIPBridge also requires OS features such as tasks and queues, Serious is investigating how best to provide a unified code base which supports OS-based implementations and "super loop" implementations. Contact Serious for more information on these developments.
-The SHIPBridge framework consists of a set of command and response messages, and their associated data payloads that provide the following capabilities.
-*Perform services or actions on the SHIPBridge hosted platform
-*Send or set data in conjunction with various applications executing on the SHIPBridge platform or a host platform
-The services could be either a single standalone action or could be a series of actions combined by the host to perform a higher level function.  For example, a host may completely upgrade the firmware and GUI on a SIM through a series of actions (via services) including:
-*reading the serial number of the unit
-*based on the serial number, downloading a new SHIPEngine image
-*downloading a new GUI cargo, and,
-*rebooting the unit.
-This overview is designed to provide a high-level understanding of the SHIPBridge framework between SHIPBridge and a host, and the services supported.
-=== Host, SIM ===
-The relationship of the host and SHIPBridge, and the component architecture that comprise both environments is shown here.
-***IMAGE***
-Note, as shown, command messages can originate from either the host or SHIPBridge.  Which domain originates the command message depends on the service class.  All command messages are followed with a response message.
+== SHIPBridge Documentation and More Information ==
-==== Class, Subclass ====
-Class and Subclass are the grouping of similar services implemented in SHIPBridge accessible to the host.
-The Executive Class is responsible for establishing the communications with a host Executive Session and must be implemented on all SHIPBridge implementations.
-==== Services ====
+* [[SHIPBridge:Architectural Overview|SHIPBridge Architectural Overview]]
-Services are the actions or functions that are performed by SHIPBridge on the SIM.
+* [[SHIPBridge:Architectural Specification|SHIPBridge Architectural Specification]]
-Services support 3 levels of access.  They are READ only, READ/WRITE (1 or more) or Exclusive.  Access levels are specific to each service.
-==== Sessions ====
+[[Category:Protocols]]
-Sessions are virtual communications “pipes” that applications on a host use to access a collection of services on the device to perform particular actions, functions or capabilities.  A session will only support a single class of services.
-For example, a host may be connected to a SIM via a USB connection. The host may be running a simple monitor application showing the serial number, model, and health status of the connected SIM.  In this case, the host application would establish a “session” over the connection with SHIPBridge.  A different host application, perhaps an uploader for new GUIs, might establish a completely different session over the same USB connection.  The different sessions allow both the host and device to direct the communications traffic to the correct handlers.
-The Executive Session which manages these sessions (creation, usage, deletion) is implemented on all hosts.
-=== Message Structure ===
-Each service is accessed via a command message from the initiator and accompanied by a response message from the target.  Command and response messages consist of a standard fixed-size header plus an optional variable length payload.  Whether the command or response message for a given service contains a payload depends on the particular service.
-The maximum message size can be negotiated individually for each host Executive session.  All sessions spawned by a host Executive session will have the same initial maximum message size.  The message size always starts at 64 bytes per message, and can (upon mutual agreement between host and device) be expanded to any power of two from 64 bytes and beyond.  This size includes both header and any payload.  Large payloads that exceed the size of the message are packetized across multiple messages.
-At the message level, there is a CRC integrity checking across the entire length of the message, including the header and any applicable payload.  The sequence number field allows the host to match command messages with response messages.  It is assumed that any encapsulation protocol based on the physical layer handles these issues, and the message format is independent of underlying protocols and hardware.
-The message structure is shown here:
-Each command message from the initiator will have an associated response message from the target.
-==== Header ====
-The header is a fixed sized and standard for all messages.  The header is located at the beginning of each message and contains the minimum set of information to identify the target (class) and originator (session), and process the message (length, version, CRC).
-==== Payload ====
-The payload immediately follows the message header and is a variable size.  The length of the payload, if any, depends on the command or response message and maximum message size.
-=== Bus, Communication Interfaces ===
-The SHIPBridge protocol is implemented independent of any specific bus or communication interface.  In doing so, the SHIPBridge can be supported on SIMs regardless of the available bus or communications capabilities.
-Anticipated interfaces to be supported are listed below as examples.
-*USB
-*Serial/UART
-*Other future interfaces may include TCP/IP over Ethernet or wireless, SPI, I2C, and more