SHIP:Project Properties

From Serious Documentation
Jump to: navigation, search

Aside from the contents of the GUI itself contained primarily in the cargo, each project has certain project properties that can affect run time behavior.

Profile Support

Starting in SHIPTide v5.0.200, all project properties can be managed on a per-Profile basis. This means you can have one project with different "profiles" (i.e build configurations) with different project properties if you like.

Project Information

The informational properties of the project are found, in SHIPTide v5.0.200+, under the Project->Properties menu item which brings up the following dialog box. These properties are stored inside each cargo file.


Splash Images

Starting with SHIP v5.0.200 is the capability of having your own custom splash screens for various system states. If any of these images are present on the SIM, they will be displayed in the associated system state instead of some verbose text.

For example, when the SIM first boots (the "booting" state), if the booting image is present on the SIM that image will be displayed. If the image is not present on the SIM, a banner indicating that the boot loader is running and its build version information, as well as other message about the status of the boot process.

In the project properties dialog box, you can manage the various splash images:


There are several different machine states where the splash images option applies. Installing or removing the images on the SIM can be accomplished over-the-wire using the SHIPBridge protocol, including from SHIPTide which uses the protocol typically over the USB device connection to the SIM. The project upload panel starting in SHIPTide v5.0.200 looks something like this:


You can manually remove or install these splash images here. As well, during the project (cargo) export/upload process you can choose (in the automatic tab) to upload these images as well.

Image Formats and Sizes

SHIPTide can accept any standard image file, but will automatically stretch/resize the image to match the current project's platform LCD. For example if you specify a 100x300 pixel image for a project targeting the SIM231, that image will be stretched to 480x272. This probably is not what you want unless the image is a pure gradient or color. It is recommended you pre-size the images before referencing in SHIPTide to the size of your target platform's LCD.

When SHIPTide processes the image specified, it puts the files in the project folder under a "splash" subfolder. The file types are ".shi", which are proprietary Serious image compression format files quickly and easily displayed by all SIMs.

These images can be 8 or 24/32 bit color; images with 8 bit color palettes will typically require significantly less space on the SIM's file system storage but have less ability for gradients and other complex color images. For simple solid colors and many corporate logos, 8 bit color images are perfectly acceptable, and creating a .GIF file or 8-bit PNG file will ensure SHIPTide sees the smaller color space files appropriately.

Images and System States

The following machine states have corresponding splash images options:

  • booting
  • updating
  • loading
  • error

Booting State

This state occurs when the SIM is reset (with or without power removed). The first stage 1 bootloader (SHIPPaddle) has no ability to bring up graphics or significant I/O, but merely loads and launches the more complete stage 2 SHIPTug bootloader. Tug normally displays a text banner with the version of Tug as well as connection information.

If the booting image is available, these messages will be suppressed and that image will be displayed as soon as possible during the booting process.

Updating State

Updates to firmware and GUI cargo files can be made from the SHIPTug or SHIPEngine environment. Not all files can be uploaded from all environments on all platforms, for example the engine on the SIM231 cannot be upgrade from within engine, but the system must be restarted back to the Tug bootloader. In all cases, for example, the cargo can be updated from engine but the engine must be taken off-line (aka "docked"). Some files, for example the splash images and Tug bootloader can be updated in the background while the engine is running. This mode is called "online" updates.

During online updates, the engine continues to operate normally showing the current GUI. No indication is made visually that firmware or file operations are happening in the background.

During offline updates in Tug or Engine, typically the LCD is cleared and an application banner is displayed along with various text messages showing the status of the upload(s). If the updating image is present, it will be displayed whenever the system is in an offline update mode.

For example, in SHIPTug, a booting image will be initially displayed if present. If the connected host (for example, SHIPTide on the PC) starts an upload, this image will be replaced with the uploading image (if present) and a blue progress bar will be used to indicate ongoing upload progress. The blue bar will turn green if the upload succeeds, red if it fails. This bar is not user configurable.

Loading State

When SHIPEngine starts (launched from the SHIPTug bootloader), it attempts to load the currently installed GUI. If the loading image is present, it will be displayed during the cargo load process with a blue progress bar. If the image is not present on the SIM, various loading text information will be displayed.

Error State

In the rare state where the system crashes due to an internally detected hardware or software catastrophic error, the system will attempt to display the error image, if present. Otherwise, it will display a non-end-user-friendly but programmer-informative log dump indicating the likely source of the issue.