SIMx52:GRM

From Serious Documentation
Jump to: navigation, search

SIMx52 GUI Reference Manual

  • See all GUI Reference Manuals (GRMs) here

The Serious Human Interface™ Platform ("SHIP") is a complete rapid GUI development and deployment system. The SHIP Total IDE ("SHIPTide") is the PC-based GUI design tool which generates a complete GUI data file including fonts, images, layout, resources, events and scripts. This data file, called the "Cargo" is then downloaded into a SIM's storage (often serial FLASH). SHIPEngine is the runtime binary engine installed on the SIM that, when it boots, discovers the cargo binary and unpacks and renders the GUI.

When creating a GUI in SHIPTide, the developer often needs to interact in the GUI environment with the underlying hardware platform features, for example listen to the touch screen or dim the brightness on the LCD display.

Each major feature of the hardware platform is represented in the GUI environment as a port. For example, most SIMs have a glass port, a touch port, one or more uart ports, etc. Controlling and reading the features in each of these ports is done through special variables called port variables (specifically, portvars) that exist within their respective ports.

These GUI Reference Manuals (GRMs) are not meant to fully describe the functionality and typical usages of each port and portvar. Rather, this GRM is designed to outline what ports and portvars are available, appropriate value ranges, and any special usage notes. The broader description of ports and portvars, including example usages, is found elsewhere in applications notes and online training videos. Consult the SHIP Documentation Home Page for a complete list of references and training.

SIMx52 Family Overview

The SIMx52 is a group of cost effective HMI Module families with 3.5, 4.3, 5, and 7" TFT Graphic/Touch LCD options.

For more information on the SIMx52, including the latest list of features and family variants, visit the specific product page:

Platform Node

Within SHIPTide and the SHIPEngine environment every SIM has a platform section that contains its ports, portvars, and some basic information about the platform itself.

In all SHIP GUI environments, the platform node also has the fixed name of "platform". The name "platform" is reserved and unique, so it is a unique and specific reference to the SIM platform on which the current GUI is running. All its properties can be specified in "dot" notation with platform followed by ".property", for example platform.id.

The platform node has the following properties, all of which are Read Only:

Property Data Type Description
platform.id Integer A 32 bit hex value that consists of the Serious Integrated Inc. USB Vendor ID (0x25D8) followed by the platform specific USB Product ID for the USB device port on the SIM.
platform.vendor String Constant value of "Serious".
platform.model String Constant platform specific value holding the SIM's model name.
platform.sn String String representation of the unique 64 bit serial number every SIM has burned into its hardware at manufacturing time. Serial numbers have a specific format; for more information contact Serious.
platform.oemsn String String representation of a customer-specific 64 bit serial number some custom SIM variants have burned into their hardware at manufacturing time. For more information contact Serious.

Platform Specific Notes

platform.model platform.id LCD Size
SIM152 0x25D800152 3.5"
SIM252 0x25D800252 4.3"
SIM352 0x25D800352 5"
SIM552 0x25D800552 7"

Glass Port(s)

Glass ports are used to control the display of the SIM and are usually referred to in the format "platform.GLASS0", "platform.GLASS1", etc.

The various fields are populated at SHIPEngine launch with the defaults for the given platform.

Portvar Data Type Permissions Description
kick Boolean Read/Write Toggling the value of kick resets the backlight timer (if set). The actual value is irrelevant; it is the change event that resets the backlight timer. As such, kick should always be assigned to the opposite of its current value (i.e. GLASS0.kick = !GLASS0.kick).
timeout Integer Read/Write The number of seconds until the backlight shuts off automatically. If kick is changed, the timer is reset to the full timeout value. If set to 0, the backlight will never shut off automatically. This value is always 0 (disabled) at boot. If a default value other than 0 is desired, store the desired value in a persistent variable in your GUI and load it into timeout at boot time using the shiplaunch event.
width Dimension Read Only This is the width (x), in pixels, of the SIM's display. (Default: platform specific)
height Dimension Read Only This is the height (y), in pixels, of the SIM's display. (Default: platform specific)
mirrorx Boolean Read/Write When set, the entire display is mirrored in the x direction. Can be used in conjunction with flipxy. (Default false)
mirrory Boolean Read/Write When set, the entire display is mirrored in the y direction. Can be used in conjunction with flipxy. (Defaultfalse)
flipxy Boolean Read/Write When set, the entire display is flipped on the x-y axis (portrait mode). Can be used in conjunction with mirrorx and/or mirrory. (Default: false)
bpp Byte Read Only Number of bits per pixel on the glass. The total number of displayable colors is 2 to the power of this number (e.g. 2^16 = 65536 total colors). (Default: platform specific)
backlight Byte Read/Write The brightness of the backlight between 0 (off) and 100 (max). Regulating backlight intensity can decrease power, increase longevity of the backlight hardware, and improve viewing in different lighting conditions. Setting this to an out of range value sets the backlight to max. (Default: 100)

Platform Specific Notes

  • SIMx52 has a single display; referred to by the name platform.GLASS0

The specific LCD code of the module you are using indicates the resolution (width x height pixels) of the LCD; see the LCD Learning Center for a list of all the codes; the 7th of 8 digits is the resolution; so for example in the 7" part number "SIM552-A01-C45ALMDA" the LCD code is "C45ALMDA" and the 7th digit is "D". Looking this code up in the LCD code tables yields 800x480.

In this example,

  • For landscape mode, width and height are 800 and 480 respectively
  • For portrait mode, width and height are 480 and 800 respectively
  • bpp is 24 (for 24 bit color RGB888) for all SIMx52 products

Touch Port(s)

Touch ports are used to read and configure the touch interface of the SIM and are usually referred to in the format "platform.TOUCH0", "platform.TOUCH1", etc.

Portvar Data Type Permissions Description
event Touch Read Only A complex datatype with several properties. (see Touch Events)
width Dimension Read Only This is the width (x), in pixels, of the SIM's display. (Default: platform specific)
height Dimension Read Only This is the height (y), in pixels, of the SIM's display. (Default: platform specific)
mirrorx Boolean Read/Write When set, the values received from touch events are mirrored in the x direction. Can be used in conjunction with flipxy. (Default: false)
mirrory Boolean Read/Write When set, the values received from touch events are mirrored in the y direction. Can be used in conjunction with flipxy. (Default: false)
flipxy Boolean Read/Write When set, the values received from touch events are flipped on the x-y axis (portrait mode). Can be used in conjunction with mirrorx and/or mirrory. (Default: false)

Platform Specific Notes

There is a single touch interface; referred to by the name platform.TOUCH0

The resolution of the touch screen (if present) is the same as the LCD. Assuming the same "D" resolution code (i.e. 800x480) as the example above:

  • For landscape mode, are width and height 800 and 480 respectively
  • For portrait mode, are width and height 480 and 800 respectively

GPIO Port(s)

The GPIO ports on SIMx52 is named platform.GPIO and contains a variety of general purpose I/O portvars including:

Portvar Data Type Permissions Description
pcbTemp Temperature Read Only Value of the on-board temperature sensor if present.
tempPrecision Byte Read/Write Controls the number of bits of precision of the pcbTemperature (SHIPv4) or pcbTemp (SHIPv5) reading. A value between 0 and 8; default value is 0.
ambLight Byte Read Only Reflects the current ambient light intensity, from 0 to 100%. Can be combined with backlight to make the LCD backlight brightness track the ambient light conditions.
ioX Boolean Read/Write Reads the current physical value of the GPIO<X> pin, where "X" is 0,1,.. depending on the platform. Writes are ignored unless the pin is configured as an output (see platform.GPIO.IOMODE).
ioModeX Byte Read/Write Sets the output mode of the GPIO<X> pin, where "X" is 0,1,.. depending on the platform; See platform.GPIO.IOMODE constants for settings.

Platform Specific Notes

  • There are 4 GPIO io pins available, numbered 0, 1, 2,3.
  • The GPIO functionality is not yet implemented; Contact Serious for details.
  • If the on-board temperature sensor is not present on the platform, pcbTemp will read 23.00°C.

UART Port(s)

UART ports are used to configure the way a SIM communicates with some other device and are usually referred to in the format "platform.UART0", "platform.UART1", etc.

If you attempt to set an invalid value for any of these portvars, the value of the portvar will not be changed. (see UART_FLAGS)

Portvar Data Type Permissions Description
rate Integer Read/Write The baud rate.
bits UART_FLAG Read/Write The number of bits per character set.
stop UART_FLAG Read/Write The number of stop bits sent after each character set.
parity UART_FLAG Read/Write The parity bit sent after each character set.
txControl UART_FLAG Read/Write Sets how the hardware tx control line functions for full/half duplex transceiver control (default UART_FLAGS.TXC_UNUSED).

Platform Specific Notes

  • SIMx52 has two UARTs referred to by the names platform.UART0 and platform.UART1 respectively.

platform.UART0 is the UART attached to the RS485 transceiver (if present) and exposed through the 6-pin 3.5mm industrial networking connector. platform.UART1 is the UART available on the board-to-board and JST16 connectors.

Within the two 'platform.UARTx nodes are the following sub-variables:

USBF CDC Port(s)

USBF (i.e. USB Device) Communications Class Device (CDC) port variables are used to configure the way a SIM communicates with some other device and are referred to in the format "platform.USBF_CDC0", "platform.USBF_CDC1", etc.

Multiple USB Device protocols (aka "classes") can be active on the same port simultaneously. For example, on USB device port 0 on a platform, you can have:

  • USBF_CDC0, implementing the Communications Device Class (aka "serial port over USB"), and,
  • USBF_VENDOR0, the Vendor (or "Raw") class bound to a SHIPBridge Protocol link exchanging data with another board

both operating simultaneously.

USBF_CDC devices act just like UARTs, and have a subset of the UART portvars. If you attempt to set an invalid value for any of these portvars, the value of the portvar will not be changed. (see UART_FLAGS)

Portvar Data Type Permissions Description
rate Integer Read/Write The baud rate.
bits UART_FLAG Read/Write The number of bits per character set.
stop UART_FLAG Read/Write The number of stop bits sent after each character set.
parity UART_FLAG Read/Write The parity bit sent after each character set.

Platform Specific Notes

  • SIMx52 has one USB device (aka "Function") port with a Communications Device Class (CDC aka "serial port over USB") called USBF_CDC0.

USBF_CDC0 is exposed via the USB Micro B connector as well as on the daughtercard board-to-board connector. Since you cannot have two hosts connected to the same USB Device port, this port is auto-arbitrated by SHIPEngine as described in the SIMx52 Technical Reference Manual.

Within the two platform.USBF_CDCx nodes are the following sub-variables:

USBF Vendor Class Port(s)

The platform.USBF_VENDORx ports have no configuration parameters; this node is designed for binding primarily to the SHIPBridge Protocol for exchanging data between GUIs and external systems.

Multiple USB Device protocols (aka "classes") can be active on the same port simultaneously. For example, on USB device port 0 on a platform, you can have:

  • USBF_CDC0, implementing the Communications Device Class (aka "serial port over USB"), and,
  • USBF_VENDOR0, the Vendor (or "Raw") class bound to a SHIPBridge Protocol link exchanging data with another board

both operating simultaneously.

Platform Specific Notes

  • SIMx52 has one USB device (aka "Function") port with a "vendor" (aka "raw") class driver, USBF_VENDOR0.

USBF_VENDOR0 is exposed via the USB Micro B connector as well as on the daughtercard board-to-board connector. Since you cannot have two hosts connected to the same USB Device port, this port is auto-arbitrated by SHIPEngine as described in the SIMx52 Technical Reference Manual.

Storage Device Port(s)

DRIVE is actually a group of ports that name the various storage "drives" available on a given platform. Nodes within the "platform.DRIVE" group, for example "platform.DRIVE.BULK0" can be referenced by file handles and storage device type operations, for example querying the size of the storage device.

BULK Storage Devices

DRIVE.BULKx ports refer to file systems on bulk storage devices, such as e.MMC, NAND, or NOR Flash devices, built into the specific module and are referred to in the format "platform.DRIVE.BULK0", "platform.DRIVE.BULK1", etc. Think of DRIVE.DRIVE.BULK0 as your traditional "C drive" on a PC -- the built-in main storage device.

DRIVE.BULKx ports can be referenced in various file related actions as the device on which a file is opened/closed/read/written for example. Also theseports have various attributes to determine/control their state:

Portvar Data Type Permissions Description
autoUpdate Boolean Read/Write A reboot-persistent setting, this enables/disables (if true/false) the auto-update process if firmware update files are present on the drive.

USB Host Storage Devices

DRIVE.USBHx ports refer to file systems on removable USB media, for example a USB Thumb Drive, plugged into a modules USB Host A connector (if present), and are referred to in the format "platform.DRIVE.USBH0", "platform.DRIVE.USBH1", etc.

DRIVE.USBHx ports can be referenced in various file related actions as the device on which a file is opened/closed/read/written for example. Also these ports have various attributes to determine/control their state:

Portvar Data Type Permissions Description
autoUpdate Boolean Read/Write A reboot-persistent setting, this enables/disables (if true/false) the auto-update process if firmware update files are present on the drive.
mounted Boolean Read When true, says the removable media is inserted and mounted with a valid format and file system.

SD Card Storage Devices

DRIVE.SDx ports refer to file systems on removable USB media, for example a USB Thumb Drive, plugged into a modules' SD or Micro SD card connector (if present), and are referred to in the format "platform.DRIVE.SD0", "platform.DRIVE.SD1", etc.

DRIVE.SDx ports can be referenced in various file related actions as the device on which a file is opened/closed/read/written for example. Also these ports have various attributes to determine/control their state:

Portvar Data Type Permissions Description
autoUpdate Boolean Read/Write A reboot-persistent setting, this enables/disables (if true/false) the auto-update process if firmware update files are present on the drive.
mounted Boolean Read When true, says the removable media is inserted and mounted with a valid format and file system.

Platform Specific Notes

  • SIMx52 has three DRIVE ports, one for each of the available storage devices:
    • platform.DRIVE.BULK0 which references the on-board e.MMC bulk file system
    • platform.DRIVE.USBH0 which references the file system on a thumb-drive type device plugged in the the USB Host A connector
    • platform.DRIVE.SD0 which references the file system on an Micro SD card if plugged into the SIM.

Media Port(s)

MEDIAx ports refer to output of audio and video on the module, and are referred to in the format "platform.MEDIA0", "platform.MEDIA1", etc.

MEDIAx ports have various attributes to determine/control their state:

Portvar Data Type Permissions Description
error Byte Read The error condition of the media clip.
height Dimension Read The height, in pixels, of the current media clip playing if it has video content (else it will be 0).
layer Byte Read/Write The current layer the video is being played in (default 1 is overlay, 0 is behind the GUI).
length Integer Read The total length of the mediaclip being played, in miliseconds.
location Node Read/Write The source DRIVE (e.g. platform.DRIVE.BULK0) of the source audio or video file.
play Boolean Read/Write Plays (if true) or pauses (if false) the media clip. This automatically turns false at the end of playing a clip.
position Integer Read/Write The current position being played in this media clip, in miliseconds.
source String Read/Write The filename of the source audio or video file.
state Byte Read The state of the media clip.
volume Byte Read/Write The volume of the current media clip playing from 0 to 100%.
width Dimension Read The width, in pixels, of the current media clip playing if it has video content (else it will be 0).

In general, media files are "containers" that contain audio and/or video. For example, an mp3 audio clip on your PC is actually an MPEG-ES container encapsulating audio content encoded with the mp3 codec. MPEG movies, often in .mp4 files, are actually containers encapsulating video and audio tracks encoded in various different ways.

The distinction between the container type and the encoding of the content is important, since for SHIPEngine on the platform to be able to play the media, both the container as well as the content must be recognizable and playable.

Platform Specific Notes

SIMx52 has a single Media port; referred to by the name platform.MEDIA0.

SHIPTide may support import of numerous containers and audio/video codecs. Exports with embedded audio/video content in the cargo file will be converted by SHIPTide into the best suitable native format.

The SIMx52 does not support video. All multimedia content from SHIPTide imported media will be stripped of its video track(s).

Natively, the SIMx52 supports the following audio formats:

The following are planned for future release, Contact Serious for details.

  • .mp3 audio files