SimpleHMI low level message codes

This section describes the low level serial command/message codes that flow between a SimpleHMI device and the host. Typically the SimpleHMI device is an Android phone, and the host is a SPLat controller. If you are programming a SPLat you will be using the HMI or HMI_Log hash commands and various hash functions, so all that follows is taken care of under the hood (no need to read on unless you are making SimpleHMI support for a host other than SPLat.).

See also: SimpleHMI tutorial, HMI hash command, HMI_Log hash command

General message format to SimpleHMI

All commands (a.k.a. messages, packets, datagrams) to the SimpleHMI consist of a header, a body and a terminator.

The header starts with a '01 character (this is the traditional SPLat notation for hex) followed by a command character. Command characters have been arbitrarily assigned from the visible (printing) characters, but could in future be any codes greater than '1F (invisible codes are reserved for other uses). Thus the header is always two characters.

The body consists of 0 or more arguments. Arguments are always ASCII (visible) characters, so for example the number 23 will be an ASCII 2 ('32) followed by ASCII 3 ('33). The arguments list is terminated in '03 . If there is more than 1 argument they are separated by '02 characters.

The following table summarises the complete repertoire of commands to the SimpleHMI. In this table the vertical bar (pipe) character | indicates a '02 argument separator. The '01 that starts every command, and the '03 that ends every command, are not shown.

Messages to SimpleHMI

Name	Cmd	Arguments (Body)	Description
`Text`	`@`	Text	Any following text up to the '03 terminator, is displayed at the current cursor position. No wrapping!
`LogWrite`	`A`	None
`Log`	`B`	Text	The text is added to the accumulating record for the currently selected log file.
`HHMMSS`	`C`	None	The current system time in the SimpleHMI device is added to the accumulating record for the currently selected log file.
`YYMMDD`	`D`	None	The current system time in the SimpleHMI device is added to the accumulating record for the currently selected log file.
`CursorRel`	`E`	�dRow \| �dCol	Move the text cursor relative to its current position. If an argument is empty it is unchanged. Row and column delta specifiers can be any of those defined under the `CursorRel` hash function.
`Cursor`	`F`	Row \| Col	Move the text cursor to a new absolute position. If an argument is empty it is unchanged. Row and column specifiers can be any of those defined under the `Cursor` hash function.
`PushColors`	`G`	None	Push foreground and background colours onto the colour stack.
`PopColors`	`H`	None	Pop the most recently pushed colours off the colour stack and set both foreground and background colours to the retrieved values..
`PopFGColor`	`I`	None	Pop the most recently pushed colours off the colour stack and set the foreground colours to the retrieved value. The background colour is not affected.
`PopBGColor`	`J`	None	Pop the most recently pushed colours off the colour stack and set the background colours to the retrieved value. The foreground colour is not affected.
`FGColorRGB`	`K`	R \| G \| B values, each 0-255	Foreground colour for future text and possibly other items
`BGColorRGB`	`L`	R \| G \| B values, each 0-255	Background colour for future text and possibly other items, and Cls
`ButtonSet`	`O`	Btn \| Row \| Col \| Height \| Width \| Text \| Mode \| ClickCode	Set button parameters. Coordinates in character pitch. `ClickCode` should not contain hex character codes less than `'0E`. Row and column specifiers, and Height and Width specifiers, can be any of those defined under the `ButtonEvent` hash function. Mode: In early versions this parameter was called Visible, and simply controlled visibility of the button. It now contains mode control in addition to visibility information. The coding is described in the `ButtonEvent` hash function. Note: There could be some confusion between the `ButtonEvent` hash function, the `ButtonParams` hash function and the `ButtonSet` low level message. The `ButtonEvent` hash function automatically assigns a ClickCode, emits a `ButtonSet` message, and generates the SPLat program code to intercept the click code and call the event handler subroutine. The `ButtonParams` hash function also emits a `ButtonSet` message, to change any subset of the button's parameters. It's intended purpose is for dynamically modifying the visual attributes of the button ... you should only change the click code if you are not relying on a SPLat hash function to capture the click event.
`HBar`	`Q`	Row \| Col \| Height \| Width \| Var	Draw a filled rectangle in the position and size given using `BGColor`. Then overlay it with a left-aligned filled rectangle at the same coordinates, with the same height, and width `Var * Width`. Requires `0 <= Var <= 1`. Row and column specifiers, and Height and Width specifiers, can be any of those defined under the `HBar` hash function.
`Cls`	`R`	None	Clear the text, set cursor to 1,1, colour screen with the current background colour.
`Reset`	`S`	None	Reset the HMI to initial conditions
`IntInput`	`T`	Prompt \| Min \| Max \| EventCode	Prompt user to input an integer number. Force min/max limits, return the resultant string preceded by `EventCode.` Return NULL if user hits Cancel. `EventCode` should not contain hex codes less than `'0E`.
`HideAllButtons`	`U`	None	Hides all the buttons and resets their parameters.
`ScreenWidthEvent`	V	Character_Widths \| EventCode	Sets the number of characters across the screen `EventCode` should not contain hex codes less than `'0E`.
`Rulers`	`W`	None	Displays horizontal and vertical character pitch rulers. Only shows positions that are fully accessible. For example, if the selected ScreenWidthEvent value results in a character size that would fit 23.9 times into the actual screen height, the vertical ruler will contain rows zero through 22.
`Enables`	`X`	8-bit mask as hex number	Bit 7 Enables the Terminal tab so the terminal function can be used.
`FileOpen`	Y	BaseName \| Mode
`NewFile`	`Z`	BaseName	Signals that a new file is to be created on the next `LogWrite` operation. The rules for new files depend on the Mode. Mode is described under `FileOpen` hash function.
`ColourWheel`	o	EventCode	(Android only) . Displays the colour wheel graphic. See below for what gets sent back to the host.
`SpeakText`	p	Text \| Language \| Country \| ClearQueue	Speaks aloud a given text, with language and country settings. For more details of parameters see `SpeakText` hash function. Not implemented in Windows, where a message box pops up instead.
`OldSpeakNumb`	`q`	Text	Speaks aloud a given text, with no other parameters. Intended for speaking numbers from SPLat. With other hosts may be used as a simplified `SpeakText`. Not implemented in Windows, where a message box pops up instead.
`Trace`	`!`	Text	Not used in Android. Any following text up to the '03 terminator, is appended to the trace window. It can optionally be written to a disk file. `'0D '0A` (carriage return/line feed) gives a new line.

Messages from SimpleHMI back to the host

In the ButtonParams command, the last argument is called ClickCode. This defines the code that will be sent back to the host when an Enduser clicks the button. The ClickCode can be any sequence of character codes greater than '1F ('1F and below are reserved). When a button is pressed its ClickCode will be sent to the host followed by a '04.
In the IntInput command, the last argument is called EventCode. When the enduser completes entering the requested data, a message is sent back to the host in the following form:
EventCode, '05, User_Response, '04

The EventCode can be any sequence of character codes greater than '1F ('1F and below are reserved). The '05 is provided by SimpleHMI, and terminates the header. User_Response is whatever ASCII input the user provided. The '04 is the message terminator. If User_Response is empty (the '04 follows immediately after the '05), it means the user cancelled the operation without entering any data.
The ColourWheel command generates a stream of messages as the Enduser moves a finger across the graphic. Each message consists of:
EventCode, '05, RedVal, GreenVal, BlueVal, '04

There are spaces after RedVal and GreenVal.to separate the colour values. Colour values are in the range 0 to 255.
Other commands can result in an EventCode being sent back to the host. The EventCode can be any sequence of character codes greater than '1F ('1F and below are reserved) and will be returned by the SimpleHMI in the form:
EventCode, '05, '04
When the SimpleHMI app in an Android device successfully makes a Bluetooth connection, it sends out a ConnectedEvent message. This consists of the character pair '06 '04.

These formats have been designed to work with SPLat instructions ComRx_FindXInBuf and ComRx_StrFind. ComRx_FindXInBuf will tell you if there is a '04 message terminator in the buffer. If every ClickCode and EventCode has been made unique, it is a simple matter to use ComRx_StrFind with suitable tables in NVEM0 to identify the actual event.

On other host platforms, for example a C-programmed controller, the event codes could be used to index a table of callback addresses.

Default button codes

Normally the host will tell the SimpleHMI client what click codes to send back when buttons are clicked. There are however defaults for the buttons that display as F1 through F8 on the default screen. These codes are ASCII "1" through ASCII "8" (the same as hex '31 through '38). When a button is click the code will be send followed by the '04 terminator. These codes have been designed to work with even the most simplistic of hobby grade hosts that achieve serial input by bit-banging, and block all other activity while doing so.

SimpleHMI low level message codes

SimpleHMI low level message codes

General message format to SimpleHMI

Messages to SimpleHMI

Mode:

Messages from SimpleHMI back to the host

Default button codes