Skip to content

HMI Instruction Set Properties ​

HMI Enable : Enables or disables the entire instruction set communication function; it is disabled by default.

PC analog Port: A virtual serial port used for simulation debugging on the PC, which only takes effect when running in PC simulation mode.

User Port: The physical serial port number used during actual hardware operation. -1 indicates the default port; any other value specifies a custom port number.

Baud: The serial communication rate.

Byte Size The number of valid binary bits contained in each frame of data. The available options are BIT_8 and BIT_7.

Parity Flag: The check method. Available options: No parity, Odd parity, Even parity.

Stop Bit: The frame end flag bit, usually 1 bit.

Frame Header High Byte (Hex): The high 8 bits of the communication frame start flag, used for frame synchronization.

Frame Header Low Byte (Hex): The low 8 bits of the communication frame start flag, which together with the high byte form the complete frame header.

Buffer Length: The size of the transmit/receive data buffer (unit: bytes).

Timeout (ms): The maximum time to wait for a response from the lower computer. If the timeout is exceeded, the communication is deemed to have failed.

Write Command Return Report: When checked, the upper computer will wait for and verify the return result from the lower computer when issuing write commands, ensuring successful execution.

CRC Enable: When enabled, a CRC check code is appended to the communication frame to detect errors during data transmission and improve communication reliability.

Event Dispatch Mode: Used to configure the strategy for reporting control events to the lower computer.

  • 0 None:: No control events are reported; only basic communication is performed.

  • 1 All Controls: Events generated by all controls are reported to the lower computer. Click the "Configure Event Commands" button on the right to open the event configuration window, where you can precisely select the event types to be reported.

  • 2 Self Controls: Only event types configured via "Select Event Commands to Deliver" for individual controls are reported.

When "2 Self Controls" mode is selected,event reporting is no longer a global configuration, and precise settings must be made in the property interface of each individual control:

In the Special Config category of the control properties, find the Dispatch event commend selection option and click the Click Configure button.

  • Follow Triggerable Events: When this option is checked (default), the event types reported by the control to the lower computer will automatically be fully consistent with those selected in "Triggerable Events". If the selection in To Select Events is modified, the configuration of Dispatch event commend selection will be automatically updated synchronously.

After uncheckingFollow Triggerable Events, you can manually select the event types to be reported. For example, a control can respond to both "Control Pressed" and "Control Touch Lifted" events, but you can choose to report only "Control Touch Lifted" to reduce unnecessary communication traffic.

Giraffe HMI Instruction Set ​

Command Introduction ​

DefinitionHeaderData LengthR/WInstruction TypeDataCRC Checksum
Byte Count21/21N22
Data5A A5All data for this parameter11(R)/22(W)B0/B1/...Control Command + DataCRC16

Data Length: Command Type:

Data Length ​

If the highest bit of the first byte is 1, i.e. 0x80, it means that the parameter is 2 bytes, otherwise it is 1 byte (1-128).

Read/Write Instruction ​

The instruction reads and writes in the form of a parameter, 11(read)/22(write)

Read data:
TX: Frame Header + Data Length + 11 + Instruction Type + Control Command + (CRC16)

RX: Frame Header + Data Length + 11 + Instruction Type + Control Command + Data + (CRC16)

Write data:
TX: Frame Header + Data Length + 22 + Instruction Type + Control Command + Data + (CRC16)

RX: Frame Header + Data Length + 22 + Instruction Type + Control Command + 00/01 + (CRC16)

Notes:In received data, 00 indicates a successful write operation; non-zero values indicate failure.

Examples:

  1. Read Driver Version

    TX : 5A A5 04 11 B0 00 02
    RX (Success): 5A A5 0A 11 B0 00 02 31 2E 34 2E 35 00 // Version: 1.3.5
    RX (Failure): 5A A5 04 11 B0 00 02 // Returns original command with no data.

  2. Write Backlight Brightness

    TX: 5A A5 04 22 B0 02 32 // Set brightness to 50
    RX: 5A A5 04 22 B0 02 00 // 00 = success, non-zero = failure. Note: This response can be disabled.

CRC16 Sample Code ​

C
u16 crc16_ccitt(u8 * tmp, u32 num)
{
    u16 CrcTmp = 0x0;
    u32  i = 0, j = 0;
    u16 s = 0;
    u16 tmpcrc = 0;

    for (i = 0; i < num; i++)
    {
        tmpcrc  = tmp[i] << 8;
        tmpcrc  &= 0xff00;
        CrcTmp  ^= tmpcrc;

        for (j = 0; j < 8; j++)
        {
            s = CrcTmp & 0x8000;
            CrcTmp <<= 1;
            CrcTmp  &= ~(0x0001);

            if(s){
                CrcTmp ^= 0x1021;
            }
        }
    }

    return CrcTmp;
}

Documentation Conventions ​

Parameter Type Definitions ​

DefinitionIdentifierByte CountData RangeDescription
StringstringNVariable byte length, string terminated by 00
Signed Bytes81-128 ~ 127Specific range depends on parameter description
Unsigned Byteu810 ~ 255Specific range depends on parameter description
Signed 2-bytes162-32,768 ~ 32,767Specific range depends on parameter description
Unsigned 2-byteu1620~65,535Specific range depends on parameter description
Signed 4-bytes324-$2^{31}$ ~ $2^{31}$-1Specific range depends on parameter description
Unsigned 4-byteu3240 ~ $2^{32}$Specific range depends on parameter description

Parameter Description Rules ​

  1. A single instruction may include multiple parameters, described as param1, param2, etc.
  2. The parameter type is specified in the first parenthesis after param. For example, param1(string) indicates that parameter 1 is of type string, conforming to the byte count and data range defined in the parameter type table.
  3. The data range is determined by the parameter type. However, some parameters may have a smaller range than the type allows. This is specified in the second parenthesis. For example, param1(u8)(0-100) indicates that parameter 1 is of type u8 with a range of 0-100. If no second parenthesis is provided, the range defaults to the type's full range.
  4. After describing the type and range, the parameter's functionality is explained after a colon.
  5. Commands are sent and received in the order of parameters' numbering.

Instruction Types ​

DefinitionInstruction Type
System InstructionsB0
view Function ControlB1
ctrl Function ControlB2

Instruction Set ​

System Instructions (0xB0) ​

The instruction data for system instructions = function command + input parameters + read/write parameters.

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Get VersionR00param1(u8)(00-02): Version type 00-APP version; 01-UI version; 02-Driver versionparam1(string): Version numberUser-designed code version
Reset ReportR01Noneparam1(u16)(fixed AA BB): Reset identifierActive report. When the device powers on or restarts unexpectedly, the screen sends AA BB to notify the host of a restart. The host can detect this and restart accordingly.
Reset DeviceW01Noneparam1(u16)(fixed CC DD): Reset identifierSending CC DD will reset the screen. If the host restarts unexpectedly, this command can be used to synchronize the screen restart.
Backlight BrightnessR/W02Noneparam1(u8)(0-100): Brightness value
Tone (Buzzer)R/W03Noneparam1(u8): Number of beeps
param2(u16): Interval between beeps (ms)
param3(u16): Duration of each beep (ms)
param3: Applies to the buzzer. This setting also affects touch feedback tones. Default is 100ms if not set.
Touch ConfigurationR/W04 00Noneparam1(u8): Configuration parameter
bit0: 1-Disable touch, 0-Enable touch
bit1: 1-Beep on touch, 0-No beep on touch
bit2: 1-Beep in valid touch area, 0-Beep in entire touch area
bit3: 1-Beep on release, 0-Beep on press
bit4: 1-Upload coordinates on press, 0-Do not upload on press
bit5: 1-Upload coordinates on release, 0-Do not upload on release
bit6: 1-Upload coordinates every 100ms while holding, 0-Do not upload
bit7: 1-Enter touch calibration if a specific area is tapped 20 times within 5 seconds, 0-Disable this feature
Touch CoordinatesR04 01Noneparam1(u8)(0-1): Touch event 0-Release, 1-Press
param2(u16)(0-4096): X coordinate
param3(u16)(0-4096): Y coordinate
Active report of touch coordinates
RTCR/W05Noneparam1(u16): Screen saver page (0 = no screen saver)
param2(u16): Standby time (0 = no standby)
param3(u8): Standby brightness
param4(u16): Screen-off time (0 = screen stays on)
param5(u8): Screen-off brightness
param6(u8): Activation brightness
param7(u16): Activation page (0 = use pre-standby interface)
Standby StatusR/W06 01param1(u8): Standby status 1 - Enter standby 0 - Exit standby

View Instructions (0xB1) ​

The instruction data for view control instructions = function command + input parameters + read/write parameters.

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Display ViewW00Noneparam1(u16): View IDDisplays the specified view (user-designed code version)
Get Current View IDR01param1(u8)(0-2) :Layer
0 - UI Layer;1 - Status Layer;2 - Top Layer
param1(u16): View IDRetrieves the ID of the currently displayed view for the specified layer

Ctrl Instructions (0xB2) ​

The instruction data for control instructions = control type command + function command + page ID + control ID + input parameters + read/write parameters.

Control Type Command: u8 (single-byte), including:

  • Common Instructions (0xF0)

  • Label Control Instructions (0x00)

  • Button Control Instructions (0x01)

  • And other control type instructions.

Page ID / Control ID: u16 (double-byte).

Common Instructions (0xF0) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Control VisibilityW00Noneparam1(u8)(0-1):Visibility
1 - Hide control ;
0 - Show control
Sets whether the control is hidden or visible.
Get Control WidthR01Noneparam1(u16):Control width valueRetrieves the width of the control.
Get Control HeightR02Noneparam1(u16):Control height valueRetrieves the height of the control.
Set Control PositionW03Noneparam1(s16):X-axis coordinate
param2(s16):Y-axis coordinate
Sets the display position of the control.
Set Control SizeW04Noneparam1(u16):Control width
param2(s16):Control height
Sets the display size of the control.
Set Control TransparencyW05Noneparam1(u8):Control transparencySets the transparency of the control.
Set Control Z-OrderW06Noneparam1(u8)(0-1):Z-order
1 - Bring to front; 0 - Send to back
Sets whether the control is brought to the front or sent to the back.
Set Control Click ModeW07Noneparam1(u8)(0-1):Click mode
1 - Clickable; 0 - Disable touch
Receive Click EventR87 00NoneAuto Send
param1(u8):Click event enumeration
For details,Event Enumeration Values
Expand Touch AreaW08Noneparam1(u16):Expansion valueExpands the touchable area of the control.
Set Relative PositionW09param1(u16):Reference control IDparam1(u8)(1-15): Alignment direction
1 - Top-left inside
2 - Top-center inside
3 - Top-right inside
4 - Bottom-left inside
5 - Bottom-center inside
6 - Bottom-right inside
7 - Left-center inside
8 - Right-center inside
9 - Center alignment
A - Top-left outside
B - Top-center outside
C - Top-right outside
D - Bottom-left outside
E - Bottom-center outside
F - Bottom-right outside
10 - Left-top outside
11 - Left-center outside
12 - Left-bottom outside
13 - Right-top outside
14 - Right-center outside
15 - Right-bottom outside
param2(s16):X-axis offset (0 for direct alignment, <0 for left shift, >0 for right shift)
param1(s16):Y-axis offset
Sets the relative position of the control based on a reference control.
Get Child Control CountR0ANoneparam1(u16):Number of child controls
Get Control CoordinatesR0BNoneparam1(s16):X-axis coordinate param1(s16):Y-axis coordinate
Set Control Scroll Amount (with Animation)W0CNoneparam1(u8)(0-1):Enable animation 0 - No; 1 - Yes param2(s16):X-axis scroll amount param3(s16):Y-axis scroll amount
Get Control Scroll AmountR0DNoneparam1(s16):X-axis coordinate param2(s16):Y-axis coordinate

Label Control Instructions (0x00) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Text ContentR/W00Noneparam1(string):Text contentReads or writes the text displayed in the label.
Set Text ColorW01Noneparam1(u32):Text colore.g., RGB888 format: 0xRRGGBB
Set Text SizeW02Noneparam1(u16):Font size
Set Long Text Display ModeW03Noneparam1(u8)(0-4):Display mode
0 - Fixed width, wrap text and adjust height
1 - Fixed size, show ellipsis (...) for overflow
2 - Fixed size, auto-scroll text forward/backward
3 - Fixed size, auto-scroll text circularly
4 - Fixed size, clip overflow text
Configures how long text is displayed when exceeding the control area.
Set Long Text Scroll SpeedW04Noneparam1(u16):Scroll speed
Set Text AlignmentW05Noneparam1(u8):Alignment mode(1-3,10,20,30,or combined values)
Horizontal:
1 - Left-aligned
2 - Center-aligned
3 - Right-aligned
Vertical:
10 - Top-aligned
20 - Middle-aligned
30 - Bottom-aligned
Combined:
e.g., 22 = Horizontal center (2) + Vertical middle (20)
Sets text alignment within the label. Combine horizontal and vertical modes by adding values (e.g., 22 = center-aligned).

Button Control Instructions (0x01) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Button Text ContentW00Noneparam1(string):Text content
Button State Text ColorW01Noneparam1(u8):Button state
0 - Normal/Released
1 - Toggled/Selected
2 - Clicked
4 - Focused
8 - Edited
20 - Pressed
40 - Scrolling
80 - Disabled
param2(u32):Text color
Button Text SizeW02Noneparam1(u16):Font size
Button Display ModeW03Noneparam1(u8)(0-1):Display mode
0 - Button mode
1 - Toggle mode
Button StateR/W04Noneparam1(u8):Button state
0 - Normal/Released
1 - Toggled/Selected
2 - Clicked
4 - Focused
8 - Edited
20 - Pressed
40 - Scrolling
80 - Disabled

Image Control Instructions (0x02) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Display/Get ImageW/R00Noneparam1(string):Image name and pathSets or retrieves the image displayed in the control.
Rotate ImageW01Noneparam1(u16):Rotation angle
Set Rotation/Scale CenterW02Noneparam1(s16):X-axis coordinate
param2(s16):Y-axis coordinate
Set Image ScaleW03Noneparam1(u16): Scale factor
128 - Half size
256 - Original size
512 - Double size

Image Button Control Instructions (0x03) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Image Button TextW00Noneparam1(string):Text content
Set Image Button Text ColorW01Noneparam1(u8)(0-5):Button state
0 - Normal/Released
1 - Normal/Pressed
2 - Normal/Disabled
3 - Toggle/Released
4 - Toggle/Pressed
5 - Toggle/Disabled
param2(u32):Text color (e.g., 0xRRGGBB)
Set Image Button Text SizeW02Noneparam1(U16):Font size
Set Image Button StateW03Noneparam1(u8)(0-5):Button state
0 - Normal/Released
1 - Normal/Pressed
2 - Normal/Disabled
3 - Toggle/Released
4 - Toggle/Pressed
5 - Toggle/Disabled
Set Image Button State ImageW03Noneparam1(u8)(0-5):Button state
0 - Normal/Released
1 - Normal/Pressed
2 - Normal/Disabled
3 - Toggle/Released
4 - Toggle/Pressed
5 - Toggle/Disabled param2(string):Image name

Line Control Instructions (0x04) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Line StyleW00Noneparam1(u32):Line color (e.g., 0xRRGGBB)
param2(u16):Line width
param3(u8):Transparency
param4(u8):Corner radius

Arc Control Instructions (0x05) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Arc Display StyleW00param1(u8)(0-1):Style part
0-Background,1-Foreground
param1(u32):Line color
param2(u16):Line width
param3(u8):Transparency
param4(u8):Corner radius
Set Slider ColorW01Noneparam1(u32):Color
Set Value RangeW02Noneparam1(s16):Minimum value param2(s16):Maximum value
Current ValueW/R03Noneparam1(s16):Current Value
Set Rotation AngleW04Noneparam1(u16):Rotation angle
Set Start and End AnglesW05Noneparam1(u16):Start angle param2(u16):End angle

Bar Control Instructions (0x06) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Bar ColorW00Noneparam1(u32):Color
Progress ValueW/R01Noneparam1(s16):Current value
Set Value RangeW02Noneparam1(s16):Minimum value param2(s16):Maximum value

Slider Control Instructions (0x07) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Slider ColorW00Noneparam1(u32):Color
Progress ValueW/R01Noneparam1(s16):Current value
Set Value RangeW02Noneparam1(s16):Minimum value param2(s16):Maximum value

SwControl Instructions (0x08) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Switch StateW/R00Noneparam1(u8)(0-1):0 - Off; 1 - On

Checkbox Control Instructions (0x09) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Display TextW00Noneparam1(string):Display text
Checked StateW/R01Noneparam1(u8)(0-1):
0 - Unchecked;
1 - Checked
Disable ControlW/R02Noneparam1(u8)(0-1):
0 - Enabled;
1 - Disabled

Mbox Control Instructions (0x0A) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Title ContentW00Noneparam1(string):Text content
Set Message ContentW01Noneparam1(string):Text content
Set Auto-Close DelayW02Noneparam1(u16):Delay time (ms)
MessageBox ControlW03Noneparam1(u8)(0-1):
0 - Close message box
1 - Open message box

Tileview Control Instructions (0x0B) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Manually Switch Tile by IDW00Noneparam1(u8)(0-1):Enable animation 0 - Disable 1 - Enable
param2(u16):Row ID
param3(u16):Column ID

Txtbox Control Instructions (0x0C) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Add StringW00Noneparam1(str):String
Add Single CharacterW01Noneparam1(u32):Character
Delete Single CharacterW02Noneparam1(u8)(0-1):Delete direction
0 - Left of cursor
1 - Right of cursor
Text ContentW/R03Noneparam1(str):String
Toggle Password ModeW04Noneparam1(u8)(0-1): 0 - Disable
1 - Enable
Move Cursor One StepW05Noneparam1(u8)(0-3):Direction
0 - Move right
1 - Move left
2 - Move down (only works for multi-line text)
3 - Move up (only works for multi-line text)

List Control Instructions (0x0D) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Delete a ButtonW00Noneparam1(u16):Button ID
Delete All ButtonsW01NoneNone
Button TextW/R02param1(u16):Button IDparam1(string):Text content

Droplist Control Instructions (0x0E) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Add an ItemW00param1(u16):Button IDparam1(string):Text content
Modify Item TextW01param1(u16):Button IDparam1(string):Text content
Delete an ItemW02Noneparam1(u16):Button ID
Control DropdownW03Noneparam1(u8):Expand/Collaps 0 - Collapse; 1 - Expand

Rollist Control Instructions (0x0F) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Add or Insert an OptionW00param1(u16):Button IDparam1(string):Text content
Modify Option TextW01param1(u16):Button IDparam1(string):Text content
Delete an OptionW02Noneparam1(u16):Button ID

GIF Control Instructions (0x10) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Control GIFW00Noneparam1(u8):Control option 0 - Reset GIF (restart playback)
1 - Pause GIF playback
2 - Resume GIF playback
Set Playback CountW01Noneparam1(u16):Playback count
Set GIF ImageW02Noneparam1(str):Path/Name of the GIF file

QR Code Control Instructions (0x11) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Update QR Code DataW00Noneparam1(str):QR code information

Video Control Instructions (0x12) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Video ResourceW00Noneparam1(str):Path/Name of the video file
Playback StateW/R01Noneparam1(u8)(0-3):Playback state
0 - Start playback
1 - Stop playback
2 - Pause playback
3 - Resume playback
Set VolumeW02Noneparam1(u8):Volume level
Set Video Position and SizeW03Noneparam1(u16):X-axis coordinate param2(u16):Y-axis coordinate param3(u16):Width param4(u16):Height
Set Video LoopW04Noneparam1(u8)(0-1):Loop mode
0 - No loop
1 - Loop

Keyboard Control Instructions (0x13) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Get Active Button IDR00Noneparam1(u32):Button ID
Get Button String by IDR01param1(u16):Button IDparam1(str):Button stringRetrieves the string associated with a specific keyboard button by its ID.

Spinbox Control Instructions (0x14) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Current ValueW/R00Noneparam1(s32):Value
Move CursorW01Noneparam1(u8)(0-1):Direction
0 - Move left; 1 - Move right
Cursor Position Data ControlW02Noneparam1(u8)(0-1):Data control
0 - Decrease by one unit; 1 - Increase by one unit

Table Control Instructions (0x15) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Set Cell ContentW00Noneparam1(u16):Row number param2(u16):Column number param3(str):Text content
Set Column WidthW01Noneparam1(u16):Column number param2(u16):Width
Merge Right CellsW02Noneparam1(u16):Row number param2(u16):Column number
Set Table StyleW03Noneparam1(u32):Line color param2(u8):Line width param3(u8):Transparency param4(u8):Inner fill transparency param5(u32):Fill color

Button Matrix Control Instructions (0x16) ​

DefinitionR/WFunction CommandInput ParametersRead/Write ParametersDescription
Get Button String by IDR00param1(u16):Button IDparam1(str):Button string
Set Button Options by IDW01Noneparam1(u8)(0-1):Set/Clear
0 - Clear options
1 - Set options
param2(u16):Button ID param3(u16):Control options 10 - Hide button
20 - Disable repeat on long press
40 - Disable button
80 - Set button to toggle mode
100 - Set button to toggled state
200 - Enable: Send LV_EVENT_VALUE_CHANGE on click; Disable: Send LV_EVENT_VALUE_CHANGE on press
400 - Show button label in popup when pressed
Set All Buttons OptionsW02Noneparam1(u8)(0-1):Set/Clear
0 - Clear options
1 - Set options
param3(u16):Control options 10 - Hide button
20 - Disable repeat on long press
40 - Disable button
80 - Set button to toggle mode
100 - Set button to toggled state
200 - Enable: Send LV_EVENT_VALUE_CHANGE on click; Disable: Send LV_EVENT_VALUE_CHANGE on press
400 - Show button label in popup when pressed
Check Button OptionR03param1(u16):Button ID
param2(u16):Control option 10 - Hide button
20 - Disable repeat on long press
40 - Disable button
80 - Set button to toggle mode
100 - Set button to toggled state
200 - Enable: Send LV_EVENT_VALUE_CHANGE on click; Disable: Send LV_EVENT_VALUE_CHANGE
400 - Show button label in popup when pressed
param1(u8)(0-1):
0 - Option not set;
1 - Option set
Set Button WidthW04Noneparam1(u8):Width param2(u16):Button ID
Enable Button UniquenessW/R05Noneparam1(u8)(0-1): 0 - Disable; 1 - Enable