BunHMI Developer Manual

1. Overview

1.1. BunHMI Display

A BunHMI display is shown in Figure 1. It is based on LVGL and uses BunTalk to interact with GUI widgets. It provides an easy way to create GUI applications—quick, simple, and versatile, just like delicious buns.

Figure 1. BunHMI Device

1.2. The Host Device

BunHMI communicates with the host via UART, requiring only two signals (Tx, Rx). Any host with a UART interface can communicate with BunHMI.

Warning

The voltage level of BunHMI UART is 3.3V. It is compatible with 5V TTL interface devices but not with 5V CMOS devices.

Warning

Do not connect BunHMI to an RS-232 interface. This will cause irreversible damage to the BunHMI display.

The host device can be an Arduino board (Figure 2), an MCU, or even a PC via USB-UART (TTL), which can easily interact with BunHMI.

Figure 2. Arduino Board Connection with BunHMI via UART Interface

You must cross the Tx and Rx signals between the host and the BunHMI display:

Host UART Tx → BunHMI Rx
Host UART Rx ← BunHMI Tx

The default UART baud rate for BunHMI is 115200/8n1. You can change the UART baud rate in the Project Config section of BunMaker.

2. BunMaker

BunMaker (Figure 3) is a GUI design application built on the LVGL library. BunMaker facilitates the creation of LVGL layouts.

Figure 3. BunMaker: A GUI Designer Based on LVGL

2.1. Widget Naming Rules

BunTalk scripts use widget names to interact with widgets. The Widget Settings Panel (Figure 4) on the right side of BunMaker allows you to set widget names.

Similar to most programming conventions, widget names must follow specific rules. A valid widget name must:

Start with a character: _, a-z, or A-Z.
Contain only the following characters: _, a-z, A-Z, or 0-9.

Figure 4. Widget Settings Panel

For example, you can set a button’s property using a BunTalk script as follows:

btn1.width(100); // Set the width of btn1 to 100px

2.2. Name Scope

In BunTalk, the system object "sys" is a global object that is always accessible. Other objects, such as screens and widgets created in BunMaker, can be accessed by their names.

Screens: Screens are always accessible and can be referenced by their names at any time.
Widget Names: Widget names are only valid when their corresponding screen is loaded.

You can create multiple screens in a single project. For example:

Table 1. Screen Layout Example
Screen Name	Widget Names
Screen1	btn1 btn2 lab1
Screen2	btn1 btn2 img1 arc2

You can load a screen using the sys.scr() method:

sys.scr(Screen1);  // Load Screen1
// or
sys.scr(Screen2, 1, 200); // Load Screen2 with animation type 1 and duration of 200ms

When Screen1 is loaded, you can access the following widgets by their names:

btn1
btn2
lab1

For example:

btn1.x(100); // Set the x position of btn1
lab1.text("Hello"); // Set the text of lab1 to "Hello"

When Screen2 is loaded, you can access the following widgets by their names:

btn1
btn2
img1
arc2

Note that btn1 in Screen1 and Screen2 refers to different objects, depending on which screen is loaded. Additionally, you cannot access img1 when Screen2 is not loaded. Ensure the correct screen is loaded before accessing its widgets.

A valid widget name must be unique within the same screen.

Tip	You can use an invalid widget name, such as "~background", if you do not intend to interact with that widget. Invalid names do not need to be unique within the same screen.

2.3. Widget Events

When interacting with the GUI, events are often of interest to trigger responses. BunHMI is based on the LVGL library, and you can write BunTalk scripts to handle LVGL events.

Here are the LVGL events:

EVENT_CLICKED - Triggered when an object is pressed briefly and then released. Not called if scrolled.
EVENT_PRESSED - Triggered when an object is pressed.
EVENT_LONG_PRESSED - Triggered when an object is pressed for an extended period.
EVENT_LONG_PRESSED_REPEAT - Triggered repeatedly after a long press, at intervals defined by long_press_repeat_time. Not called if scrolled.
EVENT_FOCUSED - Triggered when an object gains focus.
EVENT_DEFOCUSED - Triggered when an object loses focus.
EVENT_VALUE_CHANGED - Triggered when the value of an object changes.
EVENT_READY - Triggered when a process is completed.
EVENT_CANCEL - Triggered when a process is canceled.
EVENT_SCREEN_LOADED - Triggered when a screen is fully loaded, after all animations are completed.
EVENT_SCREEN_UNLOADED - Triggered when a screen is fully unloaded, after all animations are completed.
EVENT_SCREEN_LOAD_START - Triggered when a screen load starts, after the screen change delay expires.
EVENT_SCREEN_UNLOAD_START - Triggered when a screen unload starts, immediately after the event is fired.

In the Widget Settings Panel of BunMaker, you can select the Events page to view events relevant to a widget, as shown in the following figure:

Figure 5. Events Settings in BunTalk

For example, if a widget named "arc" has a value of 33, and a button is clicked, BunHMI will execute the BunTalk script to:

Print the string ARC:33 to UART.
Concatenate the string V=33 and assign it to the text of a widget named "label."

You can also write BunTalk scripts to execute when a screen is loaded, as shown below:

Figure 6. Screen Load Event

This script sends "LOADED" to UART when the screen is loaded.

Although BunHMI is based on LVGL, not all LVGL events are supported in the BunHMI display. Refer to the Widget Events Panel in BunMaker for a list of supported events.

For detailed event descriptions, refer to the LVGL Events documentation.

2.4. Widget Flags

Widgets have flags that affect their UI behavior. Flag settings are listed in the Widget Settings Panel of BunMaker, as shown in the following image:

Below is a list of flags and their descriptions. Note that not all flags apply to every widget:

FLAG_HIDDEN - Hides the object (as if it does not exist).
FLAG_CLICKABLE - Makes the object clickable by input devices.
FLAG_CHECKABLE - Toggles the checked state when the object is clicked.
FLAG_CLICK_FOCUSABLE - Adds a focused state to the object when clicked.
FLAG_SCROLLABLE - Makes the object scrollable.
FLAG_SCROLL_ELASTIC - Allows slower scrolling within the object.
FLAG_SCROLL_MOMENTUM - Enables the object to scroll further when "thrown."
FLAG_SCROLL_ONE - Allows scrolling only one snappable child.
FLAG_SCROLL_CHAIN_HOR - Propagates horizontal scrolling to a parent.
FLAG_SCROLL_CHAIN_VER - Propagates vertical scrolling to a parent.
FLAG_SCROLL_CHAIN - Combines FLAG_SCROLL_CHAIN_HOR and FLAG_SCROLL_CHAIN_VER.
FLAG_SCROLL_ON_FOCUS - Automatically scrolls the object into view when focused.
FLAG_SCROLL_WITH_ARROW - Allows scrolling the focused object with arrow keys.
FLAG_SNAPPABLE - Enables snapping to this object if scroll snap is enabled on the parent.
FLAG_EVENT_BUBBLE - Sends all events to the object’s parent. If the parent also has FLAG_EVENT_BUBBLE enabled, the event propagates further up the hierarchy.
FLAG_PRESS_LOCK - Keeps the object pressed even if the press slides off the object.
FLAG_GESTURE_BUBBLE - Propagates gestures to the parent.
FLAG_ADV_HITTEST - Allows more accurate hit (click) testing, e.g., considering rounded corners.
FLAG_IGNORE_LAYOUT - Makes the object positionable by layouts.
FLAG_FLOATING - Prevents the object from scrolling with the parent and ignores layout.
FLAG_OVERFLOW_VISIBLE - Prevents clipping of child content to the parent’s boundary.

2.5. Style Selector

Widget styles can be customized by selecting parts and states.

The style selector is composed of a state and a part combined using the | operator. The default style selector is (LV_STATE_DEFAULT | LV_PART_MAIN).

Here is a list of states and their corresponding code numbers:

LV_STATE_DEFAULT = 0x0000
LV_STATE_CHECKED = 0x0001
LV_STATE_FOCUSED = 0x0002
LV_STATE_FOCUS_KEY = 0x0004
LV_STATE_EDITED = 0x0008
LV_STATE_HOVERED = 0x0010
LV_STATE_PRESSED = 0x0020
LV_STATE_SCROLLED = 0x0040
LV_STATE_DISABLED = 0x0080

Here is a list of parts and their corresponding code numbers:

LV_PART_MAIN = 0x000000 /**< A background-like rectangle */
LV_PART_SCROLLBAR = 0x010000 /**< The scrollbar(s) */
LV_PART_INDICATOR = 0x020000 /**< Indicator, e.g., for sliders, bars, switches, or checkbox tick boxes */
LV_PART_KNOB = 0x030000 /**< A handle to adjust values */
LV_PART_SELECTED = 0x040000 /**< Indicates the currently selected option or section */
LV_PART_ITEMS = 0x050000 /**< Used for widgets with multiple similar elements (e.g., table cells) */
LV_PART_TICKS = 0x060000 /**< Ticks on a scale, e.g., for a chart or meter */
LV_PART_CURSOR = 0x070000 /**< Marks a specific place, e.g., a text area’s cursor or a chart marker */

The following code demonstrates how to use the style selector:

// Set the background color of the main part of a widget to blue in the default state
// Style selector = (LV_STATE_DEFAULT | LV_PART_MAIN)
widget.bg_color(rgb16(0,0,255));

// Set the background color of the indicator part of a widget to red when focused
// Style selector = (LV_STATE_FOCUSED | LV_PART_INDICATOR)
widget.bg_color(rgb16(255,0,0), 0x0002|0x20000);

3. BunTalk Script

3.1. BunTalk Syntax

BunTalk is a simple scripting language. Each statement must end with a semicolon (";"). For example:

ptr("hello world"); // Prints "hello world" to UART
label.text("Welcome");  // Sets the label text to "Welcome"

3.2. Keywords

BunTalk includes the following keywords:

if, else, and, or

These keywords cannot be used as object (widget/screen) names.

3.3. Arithmetic and Bitwise Operations

BunTalk supports basic arithmetic operations [ + , - , * , / , % ] and parentheses () for grouping.

It also supports bitwise operations [ &, |, ^ ].

Operation Examples

ptr(5 + 6); // Prints 11 to UART
ptr((5 + 9) % 10); // Prints 4 to UART
ptr(7 & 3); // Prints 3 to UART
ptr(5 | 2); // Prints 7 to UART
ptr(5 ^ 1); // Prints 4 to UART
ptr(0x10 | 0x100); // Hex numbers start with 0x. This prints 272 to UART.
label.text(bar.val() * 2);  // Sets the label text to the value of bar multiplied by 2
label2.text((bar.val() + bar2.val()) / 2); // Sets label2 text to the average of bar.val() and bar2.val()

3.4. Flow Control and Logical Operations

BunTalk supports flow control and logical operations.

Table 2. Logical Operations
Syntax	Operation
!	Logical NOT
==	Equal
!=	Not Equal
>	Greater Than
>=	Greater Than or Equal To
<	Less Than
⇐	Less Than or Equal To
and	Logical AND
or	Logical OR

Flow Control Example

// If statement
if (sw.checked()) {
  ptr("checked");
}

// For String type, the if statement checks if the string length > 0
if (label.text()) {
  // Label text length > 0
} else {
  // Label text is an empty string
}

// If-else statement
if (bar.val() > 50) {
  label.hidden(0);  // Show label
  label.text(bar.val()); // Set label text
} else {
  label.hidden(1);  // Hide label
}

// Logical AND and greater-than operation
if (sw.checked() and (slider.val() > 50)) {
  ptr("slider=", slider.val());
}

// Logical OR operation
if (sw.checked() or sw2.checked()) {
  led.color(rgb16(255, 0, 0)); // Set LED color to red
} else {
  led.color(rgb16(0, 255, 0)); // Set LED color to green
}

3.5. BunTalk Datatype

There 3 major data type

Number: Integer number. Number start with 0x is hex number. (ie: 0x10 = 16)
String: String is surround by double quote " " and is encoded with UTF-8 format.
Object: Most objects are widget object, except sys and screen object. Objects are created in BunMaker.

3.6. BunTalk by UART

You can send BunTalk by UART to interact with BunHMI. When host transmit BunTalk by UART, you must add <EOT>(04h) at the end of command string. (<EOT> stand for END OF Transmitssion). And the max BunTalk script length on BunHMI UART buffer is 256 bytes.

When using arduino, you can use Serial.print to send BunTalk to BunHMI. Here is an arduino example

// Method 1:
#define EOT 0x04
char buff[256];
snprintf(buff, sizeof(buff), "ptr(\"Hello\"); bar.val(%d);", val);
Serial1.print(buff);
Serial1.print("lab.text(\"Some Text\");"); // Send more script
Serial1.write(EOT); // Then send EOT at the end.

// Method 2:
snprintf(buff, sizeof(buff), "widget.text(\"CNT:%d\");\x04", test_cnt++); // add \x04 at the end of script
Serial.print(buff);

You can choose either Method 1 or Method 2 which is appropriate.

The BunTalk script widget.text() is to invoke widget’s method, We will talk about widgets and methods at Section 7 later.

When you want receive data from BunHMI, here is the example code of arduino

#define EOT 0x04

// the setup routine runs once when you press reset:
void setup() {
  // initialize serial communication at 115200 bits per second:
  Serial1.begin(115200);
  // Set UART Rx Time out to 10ms
  Serial1.setTimeout(10);
}

// Check and receive data from BunHMI
int rxBunHmiData(char* buff, int buff_len) {
  static char hmiBuff[256];
  static uint8_t hmiBuffLen = 0;

  if (!Serial1.available()) {
    return 0;
  }
  int rxlen = Serial1.readBytes(hmiBuff + hmiBuffLen, sizeof(hmiBuff) - hmiBuffLen);
  int i;
  hmiBuffLen += rxlen;
  // Search EOT token from the end of hmiBuff
  for (i = hmiBuffLen - 1; i >= 0; i--) {
    if (hmiBuff[i] == EOT) {
      // Got EOT Byte
      hmiBuff[i] = 0;  // Replace EOT to NULL (string terminate)
      i++;
      int cmd_len = (i < buff_len) ? i : buff_len;
      // Copy hmiBuff to buff
      memcpy(buff, hmiBuff, cmd_len);
      // Move remain data to the head of hmiBuff
      int remain_len = hmiBuffLen - cmd_len;
      if(remain_len > 0){
        memmove(hmiBuff, hmiBuff+cmd_len, remain_len);
      }
      hmiBuffLen = remain_len;
      return cmd_len;
    }
  }
  return 0;
}

// the loop routine runs over and over again forever:
void loop() {
  char rxbuff[256];
  int rxlen;

  // Check Data from HMI
  rxlen = rxBunHmiData(rxbuff, sizeof(rxbuff));
  if (rxlen) {
    // Handle data from HMI
    // TODO: add handleHmiData(rxbuff);
  }
}

For easy understanding, the following document won’t show <EOT> explicitly.

3.7. BunTalk in BunMaker

You can use BunTalk script in BunMaker too. When use BunTalk in BunMaker, there is no need <EOT> at the end of BunTalk script command.

In BunMaker, there is an Events Panel (Figure 7) in widget settings. You can write BunTalk script in events panel.

Figure 7. BunTalk in BunMaker event settings

Above settings will print b1_clicked to UART to notify host that Button is clicked.

You can add comments in Events Panel as well. Comments are start with "//" to the end of line, like following figure.

Figure 8. BunTalk Comment

3.8. Error message

When BunTalk script arise some error, It will spit out error message with prefix: !!.

For example, if you send wrong BunTalk message to BunHMI, it will send error message:

Run BunTalk: ptr("hello"
Get Response: !!Error at end: Expect ')' after arguments.

Also, if BunTalk script in BunMaker arise runtime error, it will spit out error message to UART.

3.9. Event message

When running animation, we can set event trigger when animation is done. BunHMI will send event message with prefix: !^.

For example

!^EVT_ANIM_X_END:widget_name
!^EVT_ANIM_VAL_END:widget_name
!^WAV_PLAY_END

3.10. Color format

BunHMI use RGB565 16bit color format. That is use a 16bit binary code to represent RGB color channel.

Red: 5bits, bit[15..11]
Green: 6bits, bit[10..5]
Blue: 5bits, bit[4..0]

A number will be translated as a 16 bit binary code to represent a RGB565 color code.

4. Global Functions

The following table show globol funtion in BunTalk

Table 3. Global Functions
Function	arguments & return	Desc.
atoi(str)	args: str:<String>, atoi() convert str to integer return: number	atoi() is similar to atoi() function of standard C function. ex: `ptr(atoi(label.text())+10); // this will convert label text to integer and +10, then print the result value.`
ptr(…)	args: <Number\|String>, ptr() accept variable arguments you can pass 10 args at most. Argument can be number or string. return: none	ptr() is used to send string to BunHMI UART Tx let host make response by the message. ex: print widget width ptr("W=", widget.width(),"px"); If width of widget is 100px, this will output W=100px to BunHMI UART. NOTE: ptr() will add EOT(04h) at the end of string.
strcat(…)	args: <Number\|String>, strcat() accept variable arguments you can pass 10 args at most. Argument can be number or string. return: String ex: Set widget text widget.text(strcat("Temp:", bar.val())); If value of bar is 30, this will set widget’s text to display Temp:30 Note: widget.text() & bar.val() are widget methods that described in Section 7.	strcat() is used to concatenate args to string. It is used to set widget text mostly.
rgb16(r,g,b)	args: r: <Number>, Red channel 0~255 g: <Number>, Green channel 0~255 b: <Number>, Blue channel 0~255 ex: Set widget color to red widget.color(rgb16(255,0,0)); return: Number: Represent RGB565 color format	This function is used to convert red,green,blue color channel to RGB565 color format

5. System Methods

The sys object is a global object that can be accessed by its name, sys. For example:

sys.beep(2000, 100); // Triggers the BunHMI onboard beeper.
sys.bright(60); // Sets the LCD backlight to 60%.
sys.scr(scr2); // Changes the screen to scr2.

5.1. Variables

The sys object includes 16 variables (indexed 0~15) for storing temporary data. These variables can hold numbers, strings, or objects. The values are stored in RAM and will reset after a power cycle.

// Writing to a variable
sys.var(0, 11.2); // Assigns a number to variable 0, var[0] = 11.2.
sys.var(1, "test"); // Assigns a string to variable 1, var[1] = "test".
sys.var(2, label); // Assigns an object to variable 2, var[2] = widget.

// Reading from a variable
ptr(sys.var(0));  // Prints 11.2.
ptr(sys.var(1));  // Prints "test".
sys.var(2).text("Hello");  // Sets the label text to "Hello".

5.2. `load_str()` and `save_str()`

The load_str() and save_str() methods allow you to save and load string data in non-volatile flash memory. Each slot has a maximum length of 256 bytes. These methods are useful for storing product information or other non-volatile data.

sys.save_str(10, "SN:SKU123465"); // Saves a string at offset 10 bytes in flash memory.
ptr(sys.load_str(10, 12)); // Prints a string from flash memory with an offset of 10 bytes and a length of 12 bytes.

5.3. Message Box

To display a message box, use the sys.mb_show() method as shown below:

sys.mb_show("Test", "This is a test message", "OK", "Cancel"); // Displays a message box.

This will display a message box like the following:

When the user clicks the OK button, the string "OK" is sent to the UART. Similarly, clicking the Cancel button sends the string "Cancel" to the UART.

5.4. Gesture Events

You can detect gesture directions by invoking the sys.gesture() method in the EVENT_GESTURE event.

Figure 9. Printing gestures in EVENT_GESTURE

Most widgets have the default flag FLAG_GESTURE_BUBBLE enabled, which passes gesture events to their parent and prevents them from receiving EVENT_GESTURE.

Figure 10. FLAG_GESTURE_BUBBLE enabled by default (passes gestures to the parent)

To capture gestures on a widget, disable the FLAG_GESTURE_BUBBLE flag for that widget. If all widgets pass gesture events to their parent, the Screen will eventually receive the gesture event.

5.5. System Tick

The system tick feature allows you to run scripts periodically. You can configure the system tick settings in the Project Settings of the Toolbox.

Figure 11. System Tick

System tick interval: Defines the tick interval in milliseconds (ms). The system tick script will run at every tick interval.

Caution: When using system ticks, ensure that the widget name exists on the current display screen. For example, if a widget named "lab1" exists only on Screen1 and is used in a system tick script, switching to Screen2 will cause an error because "lab1" is no longer accessible.

We recommend using Section 6.1 if you need to control widgets for each screen.

5.6. Timer

Timers function similarly to system ticks, allowing you to run scripts periodically. You can dynamically change the script at runtime using the sys.timer() method.

sys.timer(0, 0, 500, 1, "if(sw.checked()){label.text(sys.rtc_str(0));}");

This sets a timer to run the following code every 500ms:

if(sw.checked()){label.text(sys.rtc_str(0));}
// Updates the label text to the RTC time every 500ms if the `sw` widget is checked.

To cancel or stop a timer, pass the timer ID without any additional arguments:

sys.timer(0); // Stops timer 0.
sys.timer(2); // Stops timer 2.

5.7. Method List

The following table lists some of the system methods. Additional methods, such as those for SD card and WAV file playback, are described in separate sections.

Table 4. Sys Methods
Method	Arguments & Return	Description
`beep(hz, ms)`	Arguments: `hz`: <Number>, Beeper frequency `ms`: <Number>, Duration in milliseconds Return: None	Triggers the BunHMI onboard beeper to generate a frequency for the specified duration.
`bright(val)`	Arguments: `val`: <Number>, LCD backlight brightness (0~100) Return: None	Sets the LCD backlight brightness.
`bright()`	Arguments: None Return: <Number>, Current LCD backlight brightness	Gets the current LCD backlight brightness.
`cursor(show)`	Arguments: `show`: <Number>, 0 to hide the cursor, 1 to show the cursor Return: None	Sets the cursor display. This method works only on HMI models that support mouse devices.
`gesture()`	Arguments: None Return: <Number>, Gesture direction bitmap - `DIR_NONE` = 0x00 - `DIR_LEFT` = (1 << 0) - `DIR_RIGHT` = (1 << 1) - `DIR_TOP` = (1 << 2) - `DIR_BOTTOM` = (1 << 3)	Detects gesture directions. This is often called in `EVENT_GESTURE`. image::Event_Gesture.png[Event Gesture]

6. Screen

The Screen object can be obtained using sys.scr(), which returns the currently displayed screen object.

Below are examples of how to use the Screen object:

ptr(sys.scr().name()); // Prints the current screen name
sys.scr().bg_img(1); // Sets the screen background to image ID 1
sys.scr().bg_color(rgb16(255,0,0)); // Sets the screen background to red

6.1. Screen Tick

The screen tick feature allows you to run BunTalk scripts periodically. The script will only execute when the screen is displayed. You can configure the screen tick settings in the Screen Settings panel.

Screen Tick Interval: This value defines the tick interval in milliseconds (ms). The screen tick script will execute at every tick interval.

6.2. Accessing Widgets on Unloaded Screens

For widgets on the currently displayed screen, you can directly access them using their widget names.

However, if the screen is not currently displayed, you must access the widget through the screen property, as shown below:

label1.text("Hello"); // For the currently displayed screen, you can access the widget directly by its name.
Screen1.label1.text("Hello"); // Access the widget via the screen property, regardless of whether the screen is displayed or not.

When you call sys.scr(); to load a new screen, widgets not present on the new screen can only be accessed via the screen property.

This is particularly useful in screen unload events. If you need to access a widget when the screen is unloaded, you can use the screen property to access the widget.

For example, if you have a Screen1 with a label1 widget, you can use label1.text() during EVENT_SCREEN_LOADED because Screen1 is loaded. However, you must use Screen1.label1.text() during EVENT_SCREEN_UNLOADED to access label1, as Screen1 is no longer loaded. Refer to Figure 12 for more details.

Figure 12. Screen Unloaded Event

6.3. Screen Methods

Method

Arguments & Return

Description

name()

Arguments: none
Return: <String>, Screen name

Retrieves the name of the screen.

bg_img(var)

Arguments:
var: <Number>, Image ID.
var: <String>, Filename in SDCard.
Return: none

Sets the screen background image. If var is a number, the image source is set by the image ID, which is assigned in the BunMaker editor. If var is a string, the image source is set by the filename in the SDCard. Supported formats include jpg, png, and bmp.

bg_color(var)

Arguments:
var: <Number>, RGB565 color code.
Return: none

Sets the background color of the screen.

font(name)

Arguments:
name: <String>, Embedded font name.
Return: none

Sets the embedded font for the screen.

The embedded fonts include all built-in fonts:

lv_font_montserrat_12
lv_font_montserrat_14
lv_font_montserrat_16
lv_font_montserrat_20
lv_font_montserrat_24

Additionally, all user-added embedded fonts are supported.

Example: Set the embedded font for the screen

sys.scr().font("lv_font_montserrat_12");

7. Widgets

Widgets are the core components of BunHMI. Each widget has its own methods and properties, which can be controlled using BunTalk scripts. The following sections describe the available widgets and their respective methods.

7.1. Widget Base

Widgets are created using BunMaker. You can call widget methods by referencing the widget name assigned in BunMaker.

For example, btn1.width(): here, btn1 is the widget name, and the width() method returns the width of the widget.

Table 5. Widget Methods
Method	Arguments & Return	Description
bg_color(color, [part=0])	Arguments: - `color`: <Number>, RGB565 color code. - `part`: <Number>, Style selector (optional). [Refer to Style Selector for details.] Return: none.	Sets the background color of the widget. Example `widget.bg_color(rgb16(255,0,0)); widget.bg_color(rgb16(255,0,0), 0x0002 \| 0x20000);`
bg_grad_color(color)	Arguments: - `color`: <Number>, RGB565 color code. Return: none.	Sets the background gradient color of the widget.
bg_grad_stop(main, grad)	Arguments: - `main`: <Number>, Main color stop (0–100). - `grad`: <Number>, Gradient color start (0–100). Return: none.	Sets the stop position of the main color and the start position of the gradient color in percentage (%).
bg_grad_dir(dir)	Arguments: - `dir`: <Number>, Gradient direction: - `0`: No gradient. - `1`: Vertical gradient. - `2`: Horizontal gradient. Return: none.	Sets the direction of the gradient color.
bg_opa(val)	Arguments: - `val`: <Number>, Opacity value (0–255). Return: none.	Sets the background opacity of the widget.
clickable(val)	Arguments: - `val`: <Number>, `0` to disable, `1` to enable. Return: none.	Enables or disables the widget’s clickable property.
clickable()	Arguments: none. Return: <Number>, The clickable status (`0` or `1`).	Retrieves the clickable status of the widget.
co_x()	Arguments: none. Return: <Number>, The X position relative to the screen.	Retrieves the X position of the widget relative to the screen.
co_y()	Arguments: none. Return: <Number>, The Y position relative to the screen.	Retrieves the Y position of the widget relative to the screen.
disabled(val)	Arguments: - `val`: <Number>, `0` to enable, `1` to disable. Return: none.	Enables or disables the widget.
disabled()	Arguments: none. Return: <Number>, The disabled status (`0` or `1`).	Retrieves the disabled status of the widget.
focused(val)	Arguments: - `val`: <Number>, `0` to focus, `1` to unfocus. Return: none.	Sets the focus state of the widget.
focused()	Arguments: none. Return: <Number>, The focused status (`0` or `1`).	Retrieves the focus state of the widget.
font(name)	Arguments: - `name`: <String>, Embedded font name. Return: none.	Sets the embedded font of the widget. Available fonts include built-in fonts: `lv_font_montserrat_12` `lv_font_montserrat_14` `lv_font_montserrat_16` `lv_font_montserrat_20` `lv_font_montserrat_24` Additionally, user-added embedded fonts are supported. Example: Set embedded font `widget.font("lv_font_montserrat_12");`
height()	Arguments: none. Return: <Number>, The height of the widget.	Retrieves the height of the widget.
height(val)	Arguments: - `val`: <Number>, The height of the widget. Return: none.	Sets the height of the widget.
hidden(val)	Arguments: - `val`: <Number>, `0` to hide, `1` to show. Return: none.	Shows or hides the widget.
hidden()	Arguments: none. Return: <Number>, The hidden status (`0` or `1`).	Retrieves the hidden status of the widget.
opa(val)	Arguments: - `val`: <Number>, Opacity value (0–255). Return: none.	Sets the opacity of the widget.
opa()	Arguments: none. Return: <Number>, The opacity value.	Retrieves the opacity value of the widget.
pos(x, y)	Arguments: - `x`: <Number>, X position. - `y`: <Number>, Y position. Return: none.	Sets the position of the widget.
size(w, h)	Arguments: - `w`: <Number>, Width. - `h`: <Number>, Height. Return: none.	Sets the size of the widget.
text_color(val)	Arguments: - `val`: <Number>, RGB565 color code. Return: none.	Sets the text color of the widget and its children.
text_opa(val)	Arguments: - `val`: <Number>, Opacity value (0–255). Return: none.	Sets the text opacity of the widget and its children.
width()	Arguments: none. Return: <Number>, The width of the widget.	Retrieves the width of the widget.
width(val)	Arguments: - `val`: <Number>, The width of the widget. Return: none.	Sets the width of the widget.
x(val)	Arguments: - `val`: <Number>, X position. Return: none.	Sets the X position of the widget.
x()	Arguments: none. Return: <Number>, The X position relative to the parent widget.	Retrieves the X position of the widget relative to its parent.
y(val)	Arguments: - `val`: <Number>, Y position. Return: none.	Sets the Y position of the widget.
y()	Arguments: none. Return: <Number>, The Y position relative to the parent widget.	Retrieves the Y position of the widget relative to its parent.

7.1.1. Animation Methods

Animation methods allow dynamic changes to widget properties. The following table demonstrates animations for the x property. Other properties follow a similar approach.

Table 6. Animation Methods
Method	Arguments & Return	Description
anim_x(end, duration[ms], delay[ms], path, [finish_evt=0])	Arguments: - `end`: <Number>, End value of the animation. - `duration`: <Number>, Duration in milliseconds. - `delay`: <Number>, Delay in milliseconds. - `path`: <Number>, Animation path: - `lv_anim_path_linear` - `lv_anim_path_ease_in` - `lv_anim_path_ease_out` - `lv_anim_path_ease_in_out` - `lv_anim_path_bounce` - `lv_anim_path_step` - `finish_evt`: <Number>, Optional. `0` (default): No event, `1`: Send event when animation completes. Return: none.	Animates the X property of the widget. Example `/* Animate X property with path lv_anim_path_ease_in / widget.anim_x(150, 500, 0, 1); / Or with finish event */ widget.anim_x(150, 500, 0, 1, 1);`
anim_x()	Arguments: none. Return: none.	Stops the animation immediately.
anim_play_x(start, end, duration[ms], delay[ms], path, playback_time, playback_delay, repeat_count, repeat_delay, [send_finish_evt=0])	Arguments: - `start`: <Number>, Start value. - `end`: <Number>, End value. - `duration`: <Number>, Duration in milliseconds. - `delay`: <Number>, Delay in milliseconds. - `path`: <Number>, Animation path (same as `anim_x`). - `playback_time`: <Number>, Playback duration in milliseconds. - `playback_delay`: <Number>, Playback delay in milliseconds. - `repeat_count`: <Number>, Number of repetitions. - `repeat_delay`: <Number>, Delay between repetitions. - `send_finish_evt`: <Number>, Optional. `0` (default): No event, `1`: Send event when animation completes. Return: none.	Plays the animation forward and backward. Example `/* Play X property animation with path lv_anim_path_ease_in / widget.anim_play_x(-150, 150, 300, 0, 1, 100, 200, 3, 500); / Or with finish event */ widget.anim_play_x(-150, 150, 300, 0, 1, 100, 200, 3, 500, 1);`
anim_y anim_play_y	Refer to: anim_x anim_play_x	Animates the Y property.
anim_w anim_play_w	Refer to: anim_x anim_play_x	Animates the width property.
anim_h anim_play_h	Refer to: anim_x anim_play_x	Animates the height property.
anim_opa anim_play_opa	Refer to: anim_x anim_play_x	Animates the opacity property.

To stop all animations, use:

sys.stop_anim();

This stops all animations. When a new screen is loaded, all animations on the previous screen are automatically stopped.

7.2. Arc

The Arc widget inherits all methods from Table 5 and includes the following additional methods:

Table 7. Arc Methods
Method	Arguments & Return	Description
val(val)	Arguments: `val`: <Number>, the value to set Return: none	Sets the value of the arc.
val()	Arguments: none Return: <Number>, the current value of the arc	Retrieves the current value of the arc.
angle(start, end)	Arguments: `start`: <Number>, the start angle (0–360) `end`: <Number>, the end angle (0–360) Return: none	Sets the arc’s angle. Zero degrees corresponds to the middle-right position (3 o’clock) of the object, and angles increase in the clockwise direction.
angle()	Arguments: none Return: <String>, the start and end angles in the format `start,end`	Retrieves the arc’s angle. For example, if the start angle is 120 and the end angle is 60, this method will return the string 120,60.
bg_angle(start, end)	Arguments: `start`: <Number>, the start angle (0–360) `end`: <Number>, the end angle (0–360) Return: none	Sets the background angle of the arc. This method behaves similarly to `angle(start, end)`.
rotation(val)	Arguments: `val`: <Number>, the rotation angle (0–360) Return: none	Sets the rotation angle of the arc.
range(min, max)	Arguments: `min`: <Number>, the minimum range value `max`: <Number>, the maximum range value Return: none	Sets the value range for the arc.
range()	Arguments: none Return: <String>, the minimum and maximum range values in the format `min,max`	Retrieves the value range of the arc. For example, if the minimum range is 0 and the maximum range is 100, this method will return the string 0,100.
anim_val anim_play_val	Reference: [anim_x] [anim_play_x]	Animates the widget’s properties.

7.3. Bar

The Bar widget inherits all methods from Table 5 and includes the following additional methods:

Table 8. Slider Methods
Method	Arguments & Return	Description
val(val, [anim=0])	Arguments: `val`: <Number>, the value to set `anim`: <Number>, 0 for no animation, 1 for animation Return: none	Sets the value of the bar. Optionally, animation can be applied.
val()	Arguments: none Return: <Number>, the current bar value	Retrieves the current value of the bar.
start_val(val)	Arguments: `val`: <Number>, the value to set as the start value Return: none	Sets the start value of the bar.
start_val()	Arguments: none Return: <Number>, the current start value	Retrieves the start value of the bar.
range(min, max)	Arguments: `min`: <Number>, the minimum range value `max`: <Number>, the maximum range value Return: none	Sets the range of values for the bar.
range()	Arguments: none Return: <String>, the range in the format `min,max` For example, if the range is 0 to 100, this method returns the string `0,100`.	Retrieves the range of values for the bar as a string.
anim_val anim_play_val	Reference: See [anim_x] and [anim_play_x] for details.	Represents the animation-related properties of the widget.

7.4. Button

The Button widget inherits all methods from the Table 5 class.

7.5. Calendar

The Calendar widget inherits all methods from the Table 5 class, in addition to its own calendar-specific methods.

7.5.1. Get User-Selected Date

You can retrieve the date selected by the user by adding a BunTalk script to the EVENT_VALUE_CHANGED event, as shown below:

When the user selects a date on the calendar, BunHMI will print the selected date as a string, for example: 2020,12,1.

Table 9. Calendar Methods
Method	Arguments & Return Value	Description
today_date(year, month, day)	Arguments: `year`: <Number>, Year `month`: <Number>, Month `day`: <Number>, Day Return Value: None	Sets the current date to the specified year, month, and day.
today_date()	Arguments: None Return Value: <String>, The current date.	Retrieves the current date. For example, if today is `2020/1/1`, this method will return `2020,1,1`.
showed_date(year, month)	Arguments: `year`: <Number>, Year `month`: <Number>, Month Return Value: None	Sets the displayed date to the specified year and month.
showed_date()	Arguments: None Return Value: <String>, The displayed year and month.	Retrieves the year and month currently displayed on the calendar. For example, if the displayed date is `2020/1`, this method will return `2020,1`.
pressed_date()	Arguments: None Return Value: <String>, The user-selected date.	Retrieves the date selected by the user. For example, if the selected date is `2020/1/1`, this method will return `2020,1,1`.

7.6. Chart

The Chart widget inherits all methods from Table 5 and includes additional chart-specific methods.

7.6.1. Chart Types

The chart supports the following types:

Figure 13. Line Chart

Figure 14. Bar Chart

Figure 15. Scatter Chart

7.6.2. Custom X-Axis Labels

For line and bar charts, the default X-axis labels are sequential numbers starting from 0. You can customize the X-axis labels in the chart options.

Edit the custom X-axis labels (one label per line) in the X-axis settings.

7.6.3. Line Chart Styles

The default line chart appears as shown below:

Figure 16. Line Chart with Dots

To hide the dots, set the Paint size of PART_INDICATOR to 0.

Figure 17. Chart Style Settings

Figure 18. Line Chart without Dots

7.6.4. Modifying Chart Data

Chart data is represented by series, with the first series ID starting at 0. You can modify the data in several ways:

Adding Data Points

Add the next data point to a series and refresh the chart:

chart.next(0, 100); // Add 100 to series 0
chart.mnext(30, 20);  // Add 30 to series 0 and 20 to series 1
chart.next2(0, 10, 20); // For scatter charts, add (x, y) = (10, 20) to series 0

Setting Data Values

Set specific data values by ID or update all data in a series:

chart.set_value(0, 10, 33); // Set series 0, index 10 to 33
chart.set_all(0, 100);  // Set all data in series 0 to 100

Updating Multiple Data Points

For faster updates, set multiple data points and refresh the chart afterward:

chart.ser_i(0, 10); // Select series 0, set update index to 10
chart.ser(10, 11, 12, 13, 14, 15, 16, 17, 18, 19); // Update values (max 10 at a time)
chart.ser(20, 21, 22, 23, 24, 25); // Update additional values
chart.refresh();  // Refresh the chart

This method is useful for displaying a complete chart during screen load.

Resetting Chart Data

To clear or reset a series, use the special value 32767, which represents a "non-point." The chart will skip this value and not render it:

chart.set_all(0, 32767);  // Clear data in series 0

7.6.5. Chart Methods

The following table lists the available chart methods:

Method Arguments & Return Values Description

Method	Arguments & Return Values	Description
div_line(hdiv, vdiv)	Arguments: hdiv: <Number>, number of horizontal division lines vdiv: <Number>, number of vertical division lines Return: none	Sets the number of division lines on the chart.
get_point_pos(ser, id)	Arguments: ser: <Number>, series ID id: <Number>, data ID Return: String	Retrieves the position of a data point. For example, if the point is at x:10, y:30, this method returns 10,30.
mnext(…)	Arguments: <Number>, multiple arguments Return: none	Sets the next value for multiple series. Example: `widget.mnext(10, 22, 15)` sets the next values for series[0]: 10, series[1]: 22, and series[2]: 15.
next(ser, val)	Arguments: ser: <Number>, series ID val: <Number>, value Return: none	Adds the next value to a series.
next2(ser, x_val, y_val)	Arguments: ser: <Number>, series ID x_val: <Number>, x-value y_val: <Number>, y-value Return: none	Adds the next (x, y) values to a series. This method is only applicable to scatter charts.
point_count(val)	Arguments: val: <Number>, point count Return: none	Sets the point count for the chart.
point_count()	Arguments: none Return: <Number>, point count	Retrieves the point count of the chart.
refresh()	Arguments: none Return: none	Forces the chart to refresh. Call this method after using `chart.ser()` to update the chart.
ser(val1, val2, …)	Arguments: val: <Number>, values to set for series data (max 10 values) Return: none	Adds values to a series starting at the index set by `ser_i()`. Example: `chart.ser_i(0, 10); // Select series 0, set update index to 10 chart.ser(10, 11, 12, 13, 14, 15, 16, 17, 18, 19); // Update values chart.refresh(); // Refresh the chart` The data index automatically increments and wraps back to 0 after reaching the end of the data.
ser_color(ser, color)	Arguments: ser: <Number>, series ID color: <Number>, RGB565 color code Return: none	Sets the color of a series.
ser_hide(ser, hide)	Arguments: ser: <Number>, series ID hide: <Number>, 0: Show series, 1: Hide series Return: none	Shows or hides a series.
ser_i(ser, idx)	Arguments: ser: <Number>, series ID idx: <Number>, data index Return: none	Sets the data update index for a series. This affects the `chart.ser()` method.
ser2(x1, y1, x2, y2, …)	Arguments: x, y: <Number>, x and y values for series data (max 10 pairs) Return: none	Adds (x, y) values to a series. This method is only for scatter charts. Example: `chart.ser_i(0, 0); // Select series 0, set update index to 0 chart.ser2(10, 11, 12, 13, 14, 15, 16, 17, 18, 19); // Add 5 data points chart.refresh(); // Refresh the chart` The data index automatically increments and wraps back to 0 after reaching the end of the data.
set_all(ser, val)	Arguments: ser: <Number>, series ID val: <Number>, value Return: none	Sets all data points in a series to the specified value.
set_value(ser, id, val)	Arguments: ser: <Number>, series ID id: <Number>, data index val: <Number>, value Return: none	Sets a specific data point in a series.
set_value2(ser, id, x_val, y_val)	Arguments: ser: <Number>, series ID id: <Number>, data index x_val: <Number>, x-value y_val: <Number>, y-value Return: none	Sets a specific (x, y) data point in a series. This method is only for scatter charts.
set_range(axis, min, max)	Arguments: axis: <Number>, Y-axis (0: PRIMARY_Y, 1: SECONDARY_Y) min: <Number>, minimum value max: <Number>, maximum value Return: none	Sets the range of the Y-axis.
type(type)	Arguments: type: <Number> 0: None 1: Line Chart 2: Bar Chart 3: Scatter Chart Return: none	Sets the chart type.
update_mode(mode)	Arguments: mode: <Number>, 0: Shift mode, 1: Circular mode Return: none	Sets the update mode for the chart.
x_start(ser, point)	Arguments: ser: <Number>, series ID point: <Number>, point index Return: none	Sets the starting point for the X-axis of a series.
x_start(ser)	Arguments: ser: <Number>, series ID Return: <Number>	Retrieves the starting point for the X-axis of a series.
zoom_x(val)	Arguments: val: <Number>, zoom factor (e.g., 128=50%, 256=100%, 512=200%) Return: none	Sets the zoom factor for the X-axis.
zoom_x()	Arguments: none Return: <Number>, zoom factor	Retrieves the zoom factor for the X-axis.
zoom_y(val)	Arguments: val: <Number>, zoom factor (e.g., 128=50%, 256=100%, 512=200%) Return: none	Sets the zoom factor for the Y-axis.
zoom_y()	Arguments: none Return: <Number>, zoom factor	Retrieves the zoom factor for the Y-axis.

div_line(hdiv, vdiv)

Arguments:
hdiv: <Number>, number of horizontal division lines
vdiv: <Number>, number of vertical division lines

Return: none

Sets the number of division lines on the chart.

get_point_pos(ser, id)

Arguments:
ser: <Number>, series ID
id: <Number>, data ID

Return: String

Retrieves the position of a data point. For example, if the point is at x:10, y:30, this method returns 10,30.

mnext(…)

Arguments: <Number>, multiple arguments

Return: none

Sets the next value for multiple series.

Example: widget.mnext(10, 22, 15) sets the next values for series[0]: 10, series[1]: 22, and series[2]: 15.

next(ser, val)

Arguments:
ser: <Number>, series ID
val: <Number>, value

Return: none

Adds the next value to a series.

next2(ser, x_val, y_val)

Arguments:
ser: <Number>, series ID
x_val: <Number>, x-value
y_val: <Number>, y-value

Return: none

Adds the next (x, y) values to a series. This method is only applicable to scatter charts.

point_count(val)

Arguments:
val: <Number>, point count

Return: none

Sets the point count for the chart.

point_count()

Arguments: none

Return: <Number>, point count

Retrieves the point count of the chart.

refresh()

Arguments: none

Return: none

Forces the chart to refresh. Call this method after using chart.ser() to update the chart.

ser(val1, val2, …)

Arguments:
val: <Number>, values to set for series data (max 10 values)

Return: none

Adds values to a series starting at the index set by ser_i().

Example:

chart.ser_i(0, 10); // Select series 0, set update index to 10
chart.ser(10, 11, 12, 13, 14, 15, 16, 17, 18, 19); // Update values
chart.refresh();  // Refresh the chart

The data index automatically increments and wraps back to 0 after reaching the end of the data.

ser_color(ser, color)

Arguments:
ser: <Number>, series ID
color: <Number>, RGB565 color code

Return: none

Sets the color of a series.

ser_hide(ser, hide)

Arguments:
ser: <Number>, series ID
hide: <Number>, 0: Show series, 1: Hide series

Return: none

Shows or hides a series.

ser_i(ser, idx)

Arguments:
ser: <Number>, series ID
idx: <Number>, data index

Return: none

Sets the data update index for a series. This affects the chart.ser() method.

ser2(x1, y1, x2, y2, …)

Arguments:
x, y: <Number>, x and y values for series data (max 10 pairs)

Return: none

Adds (x, y) values to a series. This method is only for scatter charts.

Example:

chart.ser_i(0, 0); // Select series 0, set update index to 0
chart.ser2(10, 11, 12, 13, 14, 15, 16, 17, 18, 19); // Add 5 data points
chart.refresh();  // Refresh the chart

The data index automatically increments and wraps back to 0 after reaching the end of the data.

set_all(ser, val)

Arguments:
ser: <Number>, series ID
val: <Number>, value

Return: none

Sets all data points in a series to the specified value.

set_value(ser, id, val)

Arguments:
ser: <Number>, series ID
id: <Number>, data index
val: <Number>, value

Return: none

Sets a specific data point in a series.

set_value2(ser, id, x_val, y_val)

Arguments:
ser: <Number>, series ID
id: <Number>, data index
x_val: <Number>, x-value
y_val: <Number>, y-value

Return: none

Sets a specific (x, y) data point in a series. This method is only for scatter charts.

set_range(axis, min, max)

Arguments:
axis: <Number>, Y-axis (0: PRIMARY_Y, 1: SECONDARY_Y)
min: <Number>, minimum value
max: <Number>, maximum value

Return: none

Sets the range of the Y-axis.

type(type)

Arguments:
type: <Number>
0: None
1: Line Chart
2: Bar Chart
3: Scatter Chart

Return: none

Sets the chart type.

update_mode(mode)

Arguments:
mode: <Number>, 0: Shift mode, 1: Circular mode

Return: none

Sets the update mode for the chart.

x_start(ser, point)

Arguments:
ser: <Number>, series ID
point: <Number>, point index

Return: none

Sets the starting point for the X-axis of a series.

x_start(ser)

Arguments:
ser: <Number>, series ID

Return: <Number>

Retrieves the starting point for the X-axis of a series.

zoom_x(val)

Arguments:
val: <Number>, zoom factor (e.g., 128=50%, 256=100%, 512=200%)

Return: none

Sets the zoom factor for the X-axis.

zoom_x()

Arguments: none

Return: <Number>, zoom factor

Retrieves the zoom factor for the X-axis.

zoom_y(val)

Arguments:
val: <Number>, zoom factor (e.g., 128=50%, 256=100%, 512=200%)

Return: none

Sets the zoom factor for the Y-axis.

zoom_y()

Arguments: none

Return: <Number>, zoom factor

Retrieves the zoom factor for the Y-axis.

7.7. Checkbox

The Checkbox widget inherits all methods from Table 5 and provides the following additional methods:

Table 10. Checkbox Methods
Method	Arguments & Return Value	Description
text(val)	Arguments: `val`: <String\|Number> Returns: none	Sets the display text of the checkbox.
text()	Arguments: none Returns: <String>, the current display text.	Retrieves the display text of the checkbox.
checked(val)	Arguments: `val`: <Number>, where `0` represents checked and `1` represents unchecked. Returns: none	Sets the checkbox’s checked status.
checked()	Arguments: none Returns: <Number>, where `0` represents checked and `1` represents unchecked.	Retrieves the checkbox’s checked status.

7.8. Drop-down

The drop-down menu is a commonly used UI element.

In this example, we name a drop-down menu as dd and set its options to "9600\n19200\n57600\n115200". This allows the user to select one of these options.

In the event settings panel of the drop-down widget, the following BunTalk script is written for the EVENT_VALUE_CHANGED event:

ptr("You selected:", dd.selected_str()); // Print the selected item string
dd.text(dd.selected_str()); // Set the drop-down to display the selected item

The drop-down widget inherits all methods from Table 5 and includes the following additional methods:

Table 11. Drop-down Methods
Method	Arguments & Return	Description
options(str)	Arguments: `str`: <String>, options separated by '\n' Return: None	Sets the drop-down menu options. `widget.options("Apple\nBanana\nStrawberry");`
options()	Arguments: None Return: <String>, options string	Retrieves the drop-down menu options as a string.
add_option(str, pos)	Arguments: `str`: <String>, option string `pos`: <Number>, position to add the option Return: None	Adds an option to the drop-down menu at the specified position.
clear_options()	Arguments: None Return: None	Clears all options from the drop-down menu.
selected(pos)	Arguments: `pos`: <Number>, position to select Return: None	Sets the selected position in the drop-down menu.
selected()	Arguments: None Return: <Number>, selected position	Gets the selected position in the drop-down menu.
selected_str()	Arguments: None Return: <String>, selected item string	Gets the string of the selected item in the drop-down menu.
text(val)	Arguments: `val`: <String\|Number>, text or number to display Return: None	Sets the display text of the drop-down menu.
text()	Arguments: None Return: <String>, display text	Gets the display text of the drop-down menu.
dir(val)	Arguments: `val`: <Number> `0`: Left `1`: Right `2`: Top `3`: Bottom Return: None	Sets the direction in which the drop-down menu pops up.
dir()	Arguments: None Return: <Number>, display direction (refer to `dir(val)` method)	Gets the direction in which the drop-down menu pops up.
highlight(val)	Arguments: `val`: <Number>, `0` to disable highlight, `1` to enable highlight Return: None	Enables or disables the highlight status of the drop-down menu.
highlight()	Arguments: None Return: <Number>, `0` if highlight is disabled, `1` if highlight is enabled	Gets the highlight status of the drop-down menu.
open()	Arguments: None Return: None	Opens the drop-down menu.
close()	Arguments: None Return: None	Closes the drop-down menu.
is_open()	Arguments: None Return: <Number>, `0` if the menu is closed, `1` if the menu is open	Gets the open status of the drop-down menu.
option_cnt()	Arguments: None Return: <Number>, number of options	Gets the number of options in the drop-down menu.

7.9. Image

The Image widget inherits all methods from Table 5 and provides additional image-specific methods.

7.9.1. Rotation

The image can be rotated using the angle() method. Before rotating, ensure that the appropriate pivot point is set using the pivot() method. The following example demonstrates image rotation with different pivot points:

7.9.2. Recolor

A color can be blended with every pixel of an image using a specified intensity. This feature is useful for representing different states (e.g., checked, inactive, pressed) of an image without requiring multiple versions of the same image.

The recolor() method sets the color, and the recolor_opa() method adjusts the intensity of the recolor effect. The intensity ranges from 0 (no recolor) to 255 (full recolor). By default, this feature is disabled with a value of 0.

For example, consider the following image:

You can change the image color using the following code:

image.recolor(rgb16(200, 0, 0));
image.recolor_opa(200);

This results in the following:

Table 12. Image Methods
Method	Arguments & Return	Description
angle(val)	Arguments: `val`: <Number>, Angle value in 0.1 degrees (0–3600) Return: None	Sets the rotation angle of the image.
angle()	Arguments: None Return: <Number>, Rotation angle	Gets the current rotation angle of the image.
zoom(val)	Arguments: `val`: <Number>, Zoom factor (e.g., 128 = 50%, 256 = 100%, 512 = 200%) Return: None	Sets the zoom factor for the image.
zoom()	Arguments: None Return: <Number>, Zoom factor	Gets the current zoom factor of the image.
src(var)	Arguments: `var`: <Number>, Image ID assigned in the BunMaker editor `var`: <String>, Filename in the SDCard (formats: jpg, png, bmp) Return: None	Sets the image source. If `var` is a number, the image source is set by its ID. If `var` is a string, the image source is set by the filename in the SDCard. Note: If the selected image source in BunMaker is not a GIF, do not use src() to assign a GIF image, as it will not display.
offset_x(val)	Arguments: `val`: <Number>, Horizontal offset value Return: None	Sets the horizontal offset for the image display.
offset_x()	Arguments: None Return: <Number>, Horizontal offset value	Gets the horizontal offset of the image display.
offset_y(val)	Arguments: `val`: <Number>, Vertical offset value Return: None	Sets the vertical offset for the image display.
offset_y()	Arguments: None Return: <Number>, Vertical offset value	Gets the vertical offset of the image display.
pivot(x, y)	Arguments: `x`: <Number>, Pivot X coordinate `y`: <Number>, Pivot Y coordinate Return: None	Sets the pivot point for image rotation.
pivot()	Arguments: None Return: <String>, Pivot coordinates in the format "x,y"	Gets the current pivot point for image rotation.
recolor(color)	Arguments: `color`: <Number>, RGB565 color code Return: None	Sets the recolor value for the image.
recolor_opa(val)	Arguments: `val`: <Number>, Recolor opacity (0–255) Return: None	Sets the recolor opacity. A value of 0 disables recoloring, while 255 applies full recoloring.
anim_angle, anim_play_angle, anim_zoom, anim_play_zoom	Arguments: Refer to [anim_x] and [anim_play_x] Return: None	Animates widget properties such as angle and zoom.

7.10. ImgBtn

The ImgBtn widget inherits all methods from the Table 5 class.

7.11. Keyboard

The Keyboard widget is used to edit text areas. It allows you to type alphabets and digits, and it includes two special keys: CANCEL and READY, which trigger corresponding events.

You can write BunTalk scripts in the event handler for these keys when they are pressed.

7.11.1. Keyboard Hint

The keyboard hint is a text message used to indicate which text area is being edited. It is particularly useful in the EVENT_READY event.

For example, consider a screen with two text area widgets named taID1 and taID2, and one keyboard widget named kbd.

The following script is executed when the taID1 widget triggers the EVENT_CLICKED event:

// On taID1 EVENT_CLICKED
kbd.hidden(0); // Display the keyboard
kbd.ta(taID1); // Set the keyboard target to taID1
kbd.hint("ID1:"); // Set the hint message to "ID1:"

Similarly, the following script is executed when the taID2 widget triggers the EVENT_CLICKED event:

// On taID2 EVENT_CLICKED
kbd.hidden(0); // Display the keyboard
kbd.ta(taID2); // Set the keyboard target to taID2
kbd.hint("ID2:"); // Set the hint message to "ID2:"

When taID1 is clicked, the keyboard hint is set to "ID1:". The same logic applies to taID2.

The following script is executed when the kbd widget triggers the EVENT_READY event:

// On kbd EVENT_READY
ptr(kbd.hint(), kbd.ta().text()); // Print the hint message and the text of the target text area
kbd.hint("");   // Clear the hint message
kbd.hidden(1);  // Hide the keyboard

For example, when editing taID1 is complete and the READY button is pressed, the HMI will print:

ID1:<text of taID1>

Similarly, for taID2, the HMI will print:

ID2:<text of taID2>

By using the hint() method, you can retrieve the text value and identify which text area was edited when the user presses the READY button.

Remember to clear the hint message by calling kbd.hint(""); if it is no longer needed.

The Keyboard widget inherits all methods from Table 5 and provides the following additional methods:

Table 13. Keyboard Methods
Method	Arguments & Return	Description
hint(str)	Arguments: `str`: <String> Return: None	Sets the hint message. The maximum length is 16 bytes.
hint()	Arguments: None Return: <String>, the current hint message.	Retrieves the current hint message of the keyboard.
mode(val)	Arguments: `val`: <Number> - `0`: Lowercase text mode - `1`: Uppercase text mode - `2`: Special character mode - `3`: Numeric mode - `4`: Digital pad mode Return: None	Sets the keyboard mode.
mode()	Arguments: None Return: <Number>, the current keyboard mode. Refer to the `val` list in the `mode(val)` method.	Retrieves the current keyboard mode.
popover(val)	Arguments: `val`: <Number> - `0`: Disable popover - `1`: Enable popover Return: None	Enables or disables the display of button titles in a popover when pressed.
popover()	Arguments: None Return: <Number>, the current popover status.	Retrieves the current popover status.
textarea() ta()	Arguments: None Return: <Object>, the target text area object of the keyboard.	Retrieves the target text area object of the keyboard. You can print the target text using: [source,js] ---- ptr(keyboard.ta().text()); // Print the text of the target text area ----
textarea(obj) ta(obj)	Arguments: `obj`: <Object>, the name of the text area object Return: None	Sets the target text area object of the keyboard.
ptrkey(prefix, [ctrl_only=0])	Arguments: `prefix`: <String>, the prefix for the printed message `ctrl_only`: <Number>, optional. `0` to print all key characters, `1` to print control keys only. Default is `0`. Return: None	Prints the last key pressed on the keyboard. This is typically used in the EVENT_PRESSED event of the keyboard widget. Normal keys include `0-9`, `A-Z`, etc., while control keys include backspace, left, right, etc. Control keys are listed below. The printed character may contain more than one character: `1#`: Switch to numeric mode `ABC`: Switch to uppercase mode `abc`: Switch to lowercase mode `NL`: New Line key `OK`: OK key `CL`: Close key `BK`: Backspace key `LT`: Left arrow key `RT`: Right arrow key `KB`: Keyboard key When `ctrl_only=1` is set, only control keys are printed. For example: `widget.ptrkey("KB:"); // Prints "KB:a" if the key 'a' is pressed. widget.ptrkey("KB:", 1); // Prints control keys only, e.g., "KB:BK" when 'Backspace' is pressed. Normal keys like 'a' are not printed.`

7.12. Label

The Label widget inherits all methods from Table 5 and provides the following additional methods:

Table 14. Label Methods
Method	Arguments & Return	Description
text(val)	Arguments: `val`: `<String\|Number>` Returns: `void`	Sets the label’s display text or number.
text()	Arguments: none Returns: `<String>` The current label text.	Retrieves the label’s display text.

7.13. LED

The LED widget inherits all methods from Table 5 and provides the following additional methods:

Table 15. LED Methods
Method	Arguments & Return	Description
on(val)	Arguments: `val`: `<Number>` (0: LED off, 1: LED on) Returns: `void`	Turns the LED on or off.
toggle()	Arguments: none Returns: `void`	Toggles the LED state between on and off.
bright(val)	Arguments: `val`: `<Number>` (brightness level, 0–255) Returns: `void`	Sets the LED brightness.
bright()	Arguments: none Returns: `<Number>` (brightness level, 0–255)	Retrieves the current LED brightness level.
color(color)	Arguments: `color`: `<Number>` (RGB565 color code) Returns: `void`	Sets the LED color.
anim_bright, anim_play_bright	Arguments: none Returns: none	Refer to: [anim_x] [anim_play_x] Controls the LED brightness animation.

7.14. Line

The Line widget inherits all methods from Table 5 and provides the following additional methods:

Table 16. Line Methods
Method	Arguments & Return	Description
color(color)	Arguments: `color`: <Number>, RGB565 color code. Return: None	Sets the color of the line.
mov_p(idx, x, y)	Arguments: `idx`: <Number>, the index of the line point (0-based). `x`: <Number>, the x-coordinate. `y`: <Number>, the y-coordinate. Return: None	Moves the specified point to a new coordinate and updates the line drawing. `line.mov_p(0, 10, 20); // Move point[0] to coordinate (10, 20) line.mov_p(2, 100, 50); // Move point[2] to coordinate (100, 50)`
set_p(idx, x, y)	Arguments: `idx`: <Number>, the index of the line point (0-based). `x`: <Number>, the x-coordinate. `y`: <Number>, the y-coordinate. Return: None	Sets the coordinate of a specific point without updating the line drawing. To apply the changes, call the `refresh()` method. `line.set_p(0, 10, 20); // Set point[0] to coordinate (10, 20) line.set_p(1, 10, 40); // Set point[1] to coordinate (10, 40) line.refresh(); // Update the line drawing`
refresh()	Arguments: None Return: None	Refreshes the line drawing to reflect any changes made to its points.

7.15. Panel

The Panel widget inherits all methods from Table 5.

7.16. QRCode

The QRCode widget inherits all methods from Table 5 and provides the following additional methods:

Table 17. QRCode Methods
Method	Arguments & Return	Description
`update(str)`	Arguments: `str`: String Returns: None	Updates the QRCode to display a new string.

7.17. Roller

The Roller widget inherits all methods from Table 5 and provides the following additional methods:

Table 18. Roller Methods
Method	Arguments & Return	Description
options(str, [mode=0])	Arguments: `str`: <String>, options separated by '\n' `mode`: <Number>, 0: Normal mode, 1: Infinite mode Return: none	Sets the roller options. `widget.options("Apple\nBanana\nStrawberry"); // Roller mode: normal widget.options("Apple\nBanana\nStrawberry", 1); // Roller mode: infinite`
options()	Arguments: none Return: <String>, options string	Retrieves the options string.
selected(pos, [anim=0])	Arguments: `pos`: <Number>, position to select `anim`: <Number>, 1: Enable animation, 0: Disable animation Return: none	Sets the selected position.
selected()	Arguments: none Return: <Number>, selected position	Retrieves the selected position.
selected_str()	Arguments: none Return: <String>, selected item string	Retrieves the string of the selected item.

7.18. Slider

The Slider widget inherits all methods from Table 5 and includes the following additional methods:

Table 19. Slider Methods
Method	Arguments & Return	Description
val(val, [anim=0])	Arguments: `val`: <Number>, the value to set `anim`: <Number>, 0 for no animation, 1 for animation Return: none	Sets the slider’s value.
val()	Arguments: none Return: <Number>, the current value of the slider	Retrieves the slider’s current value.
left_val(val, [anim=0])	Arguments: `val`: <Number>, the left value to set `anim`: <Number>, 0 for no animation, 1 for animation Return: none	Sets the left value of the slider.
left_val()	Arguments: none Return: <Number>, the current left value of the slider	Retrieves the slider’s current left value.
range(min, max)	Arguments: `min`: <Number>, the minimum range value `max`: <Number>, the maximum range value Return: none	Sets the range of the slider.
range()	Arguments: none Return: <String>, the range in the format `min,max` For example, if the range is 0 to 100, this will return the string `0,100`.	Retrieves the slider’s range as a string.
anim_val anim_play_val	Reference: [anim_x] [anim_play_x]	Refers to the animation properties of the widget.

7.19. Switch

The Switch widget inherits all methods from Table 5 and provides the following additional methods:

Table 20. Switch Methods
Method	Arguments & Return	Description
checked(val)	Arguments: `val`: <Number>, 0 for checked, 1 for unchecked Return: None	Sets the switch’s check status.
checked()	Arguments: None Return: <Number>, 0 for checked, 1 for unchecked	Retrieves the switch’s current check status.

7.20. Textarea

The Textarea widget inherits all methods from Table 5 and provides the following additional methods:

Table 21. Textarea Methods
Method	Arguments & Return	Description
text(val)	Arguments: `val`: <String\|Number> Returns: none	Sets the text of the Textarea.
text()	Arguments: none Returns: <String>, the current text.	Retrieves the text of the Textarea.
add_text(var)	Arguments: `var`: <String\|Number> Returns: none	Appends the specified string or number to the Textarea.
del_char(forward)	Arguments: `forward`: <Number> - `0`: Deletes a character backward. - `1`: Deletes a character forward. Returns: none	Deletes a character in the Textarea based on the specified direction.
cursor_pos(pos)	Arguments: `pos`: <Number>, the cursor position. Returns: none	Sets the cursor position in the Textarea.
cursor_move(dir)	Arguments: `dir`: <Number> - `0`: Moves the cursor left. - `1`: Moves the cursor right. - `2`: Moves the cursor up. - `3`: Moves the cursor down. Returns: none	Moves the cursor in the specified direction.

8. SD Card

The BunHMI device includes a single SD card slot, which can be accessed using BunTalk. BunHMI utilizes the LVGL filesystem library to interact with the SD card. Most of the APIs are similar to those provided by the LVGL filesystem.

8.1. File Descriptor

Due to resource constraints, BunHMI allows only a limited number of file descriptors. Currently, you can open a maximum of 4 files simultaneously. If you need to access another file, one of the previously opened files will be automatically closed.

8.2. API in the `sys` Object

The SD card API is included in the sys object. You can invoke file system APIs as shown below:

/* Print directory content */
ptr(sys.f_dir(""));

/* Open a file */
sys.f_open(0, "/test2.txt", 1);

This example opens the SD card file "/test2.txt" in write mode and assigns it to file descriptor 0.

Table 22. Sys Methods
Method	Arguments & Return Value	Description
f_dir(path, [offset=0], [cnt=0])	Arguments: - `path`: <String>, directory path - `offset`: <Number>, number of files to skip (default: 0) - `cnt`: <Number>, number of files to list (default: 0, no limit) Return: <String>, directory listing. The maximum string length is 512 bytes.	Lists the contents of a directory. For example: /image\n text.txt\n photo.jpg\n Entries starting with "/" indicate directories. If the directory content exceeds 256 bytes, the result will be truncated with "…" at the end, like: /image\n text.txt\n photo.jpg\n … You can use `offset` to skip a specified number of files and `cnt` to limit the number of files listed. If `cnt=0`, there is no limit.
f_open(fil_id, full_name, mode)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `full_name`: <String>, full file path - `mode`: <Number>, file open mode - `0`: Read mode - `1`: Write mode (creates or overwrites the file) - `2`: Read and write mode Return: <Number>, result code from the LVGL file system.	Opens a file. After opening, the file can be accessed using the specified `fil_id`. If a file is already open with the same `fil_id`, it will be closed automatically unless explicitly closed using `f_close()`.
f_close(fil_id)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) Return: None	Closes an open file. If the file has been modified, the cached data will be written back to the SD card. After closing, the `fil_id` becomes invalid.
f_gets(fil_id, max_len)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `max_len`: <Number>, maximum length to read (maximum: 512) Return: <String>	Reads a string from the file. If an error occurs or the end of the file (EOF) is reached, it returns `NONE`.
f_lseek(fil_id, pos)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `pos`: <Number>, absolute file position Return: <Number>	Sets the file pointer to the specified position.
f_puts(fil_id, string)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `string`: <String>, string to write to the file Return: <Number>, number of bytes written.	Writes a string to the file.
f_reads(fil_id, max_len)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `max_len`: <Number>, maximum length to read (maximum: 512) Return: <String>	Reads data from the file. The return string includes a two-character prefix: 1st character: Result code: `A`: Read successful, more data available. `E`: EOF reached or an error occurred. `X`: No SD card detected. 2nd character: Delimiter `\|`. For example: - Successful read: `A\|Hello World` - EOF: `E\|` - No SD card: `X\|` This method helps identify whether the EOF has been reached or if the file is empty.
f_size(fil_id)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) Return: <Number>, file size in bytes.	Returns the size of the file.
f_skips(fil_id, nline)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) - `nline`: <Number>, number of lines to skip (nline >= 0) Return: <Number>, number of lines actually skipped.	Skips the specified number of lines while reading a file. The return value indicates the actual number of lines skipped, which may be less than `nline` if the EOF is reached.
f_tell(fil_id)	Arguments: - `fil_id`: <Number>, file descriptor ID (0–3) Return: <Number>	Returns the current file pointer position.

9. Real-Time Clock (RTC)

The Real-Time Clock (RTC) controller provides real-time clock and calendar information. (This feature is only available on models equipped with an RTC.)

9.1. RTC API in the `sys` Object

The RTC API is included in the sys object, allowing you to invoke RTC-related functions as follows:

/* Set the current time to 2020-12-31 23:30:00 */
sys.rtc(2020, 12, 31, 23, 30, 0);

9.2. RTC API Methods

Method Arguments & Return Value Description

Method	Arguments & Return Value	Description
`rtc(year, month, day, hour, min, sec)`	Arguments: - `year` (<Number>): Year - `month` (<Number>): Month - `day` (<Number>): Day - `hour` (<Number>): Hour - `min` (<Number>): Minute - `sec` (<Number>): Second Return Value: None	Sets the current time of the RTC.
`rtc(field)`	Arguments: - `field` (<Number>): Index of the RTC field to retrieve Return Value: <Number>: The value of the specified RTC field Field indices: - `0`: Year - `1`: Month - `2`: Day - `3`: Hour - `4`: Minute - `5`: Second	Retrieves the value of a specific RTC field (e.g., year, month, day, hour, minute, second). `/* Print the year value of the RTC */ ptr(sys.rtc(0));`
`rtc_str(format)`	Arguments: - `format` (<Number>): Format specifier for the RTC string Return Value: <String>: A formatted string representing the RTC time Format options: - `0`: `yyyy-mon-day hh:mm:ss` - `1`: `yyyy-mon-day` - `2`: `day/mon/yyyy` - `3`: `hh:mm:ss` - `4`: `hh:mm` - `5`: Day of the week	Generates a formatted string representing the RTC time. `/* Print a string like "RTC:2000-12-31 12:01:30" / ptr("RTC:", sys.rtc_str(0));` `/ Print a string like "10:30(Wed)" */ ptr(sys.rtc_str(4), "(", sys.rtc_str(5), ")");`

rtc(year, month, day, hour, min, sec)

Arguments:
- year (<Number>): Year
- month (<Number>): Month
- day (<Number>): Day
- hour (<Number>): Hour
- min (<Number>): Minute
- sec (<Number>): Second

Return Value: None

Sets the current time of the RTC.

rtc(field)

Arguments:
- field (<Number>): Index of the RTC field to retrieve

Return Value: <Number>: The value of the specified RTC field
Field indices:
- 0: Year
- 1: Month
- 2: Day
- 3: Hour
- 4: Minute
- 5: Second

Retrieves the value of a specific RTC field (e.g., year, month, day, hour, minute, second).

/* Print the year value of the RTC */
ptr(sys.rtc(0));

rtc_str(format)

Arguments:
- format (<Number>): Format specifier for the RTC string

Return Value: <String>: A formatted string representing the RTC time
Format options:
- 0: yyyy-mon-day hh:mm:ss
- 1: yyyy-mon-day
- 2: day/mon/yyyy
- 3: hh:mm:ss
- 4: hh:mm
- 5: Day of the week

Generates a formatted string representing the RTC time.

/* Print a string like "RTC:2000-12-31 12:01:30" */
ptr("RTC:", sys.rtc_str(0));

/* Print a string like "10:30(Wed)" */
ptr(sys.rtc_str(4), "(", sys.rtc_str(5), ")");

10. WAV File Playback

BunHMI supports WAV file playback. This feature is only available on HMI models equipped with audio output capabilities. The default source for WAV files is the SD card. The supported WAV file formats are:

Channels: Mono (1) or Stereo (2)
Sampling bits: 8, 16, or 24 bits

10.1. API in the `sys` Object

The WAV playback API is included in the sys object. You can invoke the WAV playback API as follows:

/* Start playing "audio.wav". For simplicity, use only the main file name without the ".wav" extension. */
sys.wav_play("audio"); // Note: Do not include the ".wav" extension.
/* BunHMI also supports WAV playlists using the following methods: */
/* Note: Playlist functionality is not supported on all BunHMI models. */
sys.wav_drv(0); // Set the WAV file source to the SD card.
sys.wav_clr();  // Clear the playlist.
sys.wav_add("music1", "music2"); // Add files to the playlist.
sys.wav_add("music3");
sys.wav_play(""); // Start playing "music1.wav" -> "music2.wav" -> "music3.wav" sequentially.

10.2. API Methods

Method Arguments & Return Value Description

Method	Arguments & Return Value	Description
`wav_add(…)`	Arguments: `<String>`: Main filename of the WAV file (without the ".wav" extension). Return: None	Adds files to the WAV playlist. This method accepts variable arguments. To start playing the playlist, pass an empty string `""` to the `sys.wav_play()` method. Example: `sys.wav_play("");`
`wav_clr()`	Arguments: None Return: None	Clears the WAV playlist.
`wav_cur()`	Arguments: None Return: `<Number>`: The current playback time of the WAV file in 0.01-second increments (e.g., 100 = 1 second).	Retrieves the current playback time of the WAV file.
`wav_drv(drv)`	Arguments: `drv`: `<Number>`: Storage drive: `-1`: Onboard flash memory `0`: SD card `1`: USB drive Return: None	Selects the source drive for WAV files. This method is only available on HMI models with multiple storage options.
`wav_dur()`	Arguments: None Return: `<Number>`: The duration of the current WAV file in 0.01-second increments (e.g., 100 = 1 second).	Retrieves the duration of the current WAV file.
`audio_mute(mute)`	Arguments: `mute`: `<Number>`: `1`: Mute audio `0`: Unmute audio Return: None	Mutes or unmutes the audio output.
`wav_pause(pause)`	Arguments: `pause`: `<Number>`: `1`: Pause WAV playback `0`: Resume WAV playback Return: None	Pauses or resumes WAV playback.
`wav_play(file, [pause=0], [loop=0])`	Arguments: `file`: `<String>`: Main filename of the WAV file (without the ".wav" extension). `pause`: `<Number>`: `1`: Pause playback at the start `0`: Do not pause at the start `loop`: `<Number>`: `1`: Enable loop playback `0`: Disable loop playback If only the `file` argument is provided, both `pause` and `loop` default to `0`. Return: `<Number>`: `0`: Success `>0`: File open error (FATFS error) `-1`: File format error `-2`: Audio decoder error	Opens and plays a WAV file. If the `file` argument is an empty string `""`, the system will play the WAV playlist. To set the audio volume at the beginning, set `pause=1`, adjust the audio volume, and then disable pause to start playback. When a WAV file reaches the end or encounters a read error, BunHMI will send the string `!^WAV_PLAY_END` to notify the MCU.
`wav_stop()`	Arguments: None Return: None	Stops WAV playback.
`wav_to(time)`	Arguments: `time`: `<Number>`: Playback position in 0.01-second increments (e.g., 100 = 1 second). Return: None	Sets the playback position of the WAV file.
`audio_vol(vol)`	Arguments: `vol`: `<Number>`: Audio volume (0–15). Return: None	Sets the audio output volume.
`audio_vol(l_vol, r_vol)`	Arguments: `l_vol`: `<Number>`: Left channel audio volume (0–15). `r_vol`: `<Number>`: Right channel audio volume (0–15). Return: None	Sets the audio output volume for the left and right channels separately.
`audio_vol()`	Arguments: None Return: `<Number>`: Current audio volume.	Retrieves the current audio output volume.

wav_add(…)

Arguments: <String>: Main filename of the WAV file (without the ".wav" extension).

Return: None

Adds files to the WAV playlist.
This method accepts variable arguments.
To start playing the playlist, pass an empty string "" to the sys.wav_play() method.
Example: sys.wav_play("");

wav_clr()

Arguments: None

Return: None

Clears the WAV playlist.

wav_cur()

Arguments: None

Return: <Number>: The current playback time of the WAV file in 0.01-second increments (e.g., 100 = 1 second).

Retrieves the current playback time of the WAV file.

wav_drv(drv)

Arguments: drv: <Number>: Storage drive:

-1: Onboard flash memory
0: SD card
1: USB drive

Return: None

Selects the source drive for WAV files. This method is only available on HMI models with multiple storage options.

wav_dur()

Arguments: None

Return: <Number>: The duration of the current WAV file in 0.01-second increments (e.g., 100 = 1 second).

Retrieves the duration of the current WAV file.

audio_mute(mute)

Arguments: mute: <Number>:

1: Mute audio
0: Unmute audio

Return: None

Mutes or unmutes the audio output.

wav_pause(pause)

Arguments: pause: <Number>:

1: Pause WAV playback
0: Resume WAV playback

Return: None

Pauses or resumes WAV playback.

wav_play(file, [pause=0], [loop=0])

Arguments: file: <String>: Main filename of the WAV file (without the ".wav" extension). pause: <Number>:

1: Pause playback at the start
0: Do not pause at the start loop: <Number>:
1: Enable loop playback
0: Disable loop playback If only the file argument is provided, both pause and loop default to 0.

Return: <Number>:

0: Success
>0: File open error (FATFS error)
-1: File format error
-2: Audio decoder error

Opens and plays a WAV file. If the file argument is an empty string "", the system will play the WAV playlist.

To set the audio volume at the beginning, set pause=1, adjust the audio volume, and then disable pause to start playback.

When a WAV file reaches the end or encounters a read error, BunHMI will send the string !^WAV_PLAY_END to notify the MCU.

wav_stop()

Arguments: None

Return: None

Stops WAV playback.

wav_to(time)

Arguments: time: <Number>: Playback position in 0.01-second increments (e.g., 100 = 1 second).

Return: None

Sets the playback position of the WAV file.

audio_vol(vol)

Arguments: vol: <Number>: Audio volume (0–15).

Return: None

Sets the audio output volume.

audio_vol(l_vol, r_vol)

Arguments: l_vol: <Number>: Left channel audio volume (0–15).

r_vol: <Number>: Right channel audio volume (0–15).

Return: None

Sets the audio output volume for the left and right channels separately.

audio_vol()

Arguments: None

Return: <Number>: Current audio volume.

Retrieves the current audio output volume.

11. Buntalk with Checksum

When using Buntalk communication, there is a possibility of bit errors occurring on the UART. To detect such errors, you can use a checksum mechanism.

11.1. Checksum Format

The checksum is calculated by summing all the characters in the Buntalk script, taking the modulo of the sum by 0xFF, and appending the resulting two hexadecimal digits to the end of the script.

When using the checksum format, you must append <ETB>(17h) at the end of the command string instead of <EOT>(04h). The BunHMI system will check the last byte of the script. If the last byte is <ETB>(17h), the system will validate the script using the checksum.

For example, if you want to send the following command:

ptr("Hello");

You first calculate the sum of all characters:

70h + 74h + 72h + 28h + 22h + 48h + 65h + 6Ch + 6Ch + 6Fh + 22h + 29h + 3Bh = 41Ah

The modulo of 41Ah is 1Ah.

Thus, the command to send becomes:

ptr("Hello");1A<ETB>

If the checksum is incorrect, you will receive an error response message:

!!cksum err<EOT>

11.2. Printing with Checksum

When receiving a string from the UART with a checksum, you can use the ptk() function. Similar to ptr(), the ptk() function appends the two hexadecimal digits of the checksum to the end of the string.

For example, when executing the script:

ptk("Buntalk");

The sum of the characters in "Buntalk" is calculated as follows:

42h + 75h + 6Eh + 74h + 61h + 6Ch + 6Bh = 2D1h

The modulo of 2D1h is D1h. Therefore, the resulting string will be:

BuntalkD1<ETB>

To validate the checksum, you can first check the last byte. If the last byte is <ETB>(17h), the two characters preceding <ETB> represent the checksum.

12. Conclusion

This document provides an overview of BunHMI, BunTalk scripting, and the various features and widgets available. For further details, refer to the included documentation files or contact support at mcuidea@gmail.com.

Thank you for using BunHMI!

BunHMI Developer Manual

1. Overview

1.1. BunHMI Display

1.2. The Host Device

2. BunMaker

2.1. Widget Naming Rules

2.2. Name Scope

2.3. Widget Events

2.4. Widget Flags

2.5. Style Selector

3. BunTalk Script

3.1. BunTalk Syntax

3.2. Keywords

3.3. Arithmetic and Bitwise Operations

3.4. Flow Control and Logical Operations

3.5. BunTalk Datatype

3.6. BunTalk by UART

3.7. BunTalk in BunMaker

3.8. Error message

3.9. Event message

3.10. Color format

4. Global Functions

5. System Methods

5.1. Variables

5.2. load_str() and save_str()

5.3. Message Box

5.4. Gesture Events

5.5. System Tick

5.6. Timer

5.7. Method List

6. Screen

6.1. Screen Tick

6.2. Accessing Widgets on Unloaded Screens

6.3. Screen Methods

7. Widgets

7.1. Widget Base

7.1.1. Animation Methods

7.2. Arc

7.3. Bar

7.4. Button

7.5. Calendar

7.5.1. Get User-Selected Date

7.6. Chart

7.6.1. Chart Types

7.6.2. Custom X-Axis Labels

7.6.3. Line Chart Styles

7.6.4. Modifying Chart Data

Adding Data Points

Setting Data Values

Updating Multiple Data Points

Resetting Chart Data

7.6.5. Chart Methods

7.7. Checkbox

7.8. Drop-down

7.9. Image

7.9.1. Rotation

7.9.2. Recolor

7.10. ImgBtn

7.11. Keyboard

7.11.1. Keyboard Hint

7.12. Label

7.13. LED

7.14. Line

7.15. Panel

7.16. QRCode

7.17. Roller

7.18. Slider

7.19. Switch

7.20. Textarea

8. SD Card

8.1. File Descriptor

8.2. API in the sys Object

9. Real-Time Clock (RTC)

9.1. RTC API in the sys Object

9.2. RTC API Methods

10. WAV File Playback

10.1. API in the sys Object

10.2. API Methods

11. Buntalk with Checksum

11.1. Checksum Format

5.2. `load_str()` and `save_str()`

8.2. API in the `sys` Object

9.1. RTC API in the `sys` Object

10.1. API in the `sys` Object