BunTalk: A communication protocol of BunHMI

1. Overview

BunTalk is a script like communication protocol transmit by UART to interact with BunHMI display.

1.1. BunHMI

BunHMI display like Figure 1. It’s base on LVGL and use BunTalk to interact with GUI widgets. An easy way for you to create GUI applications. Just like the delicious buns. (quick, easy and diverse).

Figure 1. BunHMI device

1.2. The Host device

BunHMI use UART to communicate with host which only needs two siganls (Tx,Rx), any host with UART interface can communicate with BunHMI.

Warning

The voltage level of BunHMI UART is 3.3V. Which should work fine with 5V TTL interface devices. But not for 5V CMOS devices!

Warning

Don’t connect BunHMI with RS-232 interface. This will cause damage of BunHMI display, and not recoverable.

The host maybe an Arduino boards (Figure 2) or MCUs, or even PC via USB-UART(TTL) which can interact with BunHMI easily.

Figure 2. Arduino board link with BunHMI via UART interface

You have to cross Tx & Rx signal between Host and BunHMI display.

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

And the default baudrate is: 115200/8n1, you can change baudrate in BunMaker.

2. BunMaker

BunMaker (Figure 3) is a GUI design app by utilize LVGL. library. BunMaker helps to create LVGL. widgets and you can use BunTalk in BunMaker also, to interact widgets with host.

Figure 3. BunMaker, a GUI designer base on LVGL

2.1. Widget Naming rule

There is a widget name setting at the Widget Settings Panel (Figure 4) of the right side of BunMaker. BunTalk interact with widgets by widget name.

Like most programming code. There is a naming rule. A valid widget name must be

Start with char _, a-z, A-Z.
And only contain _, a-z, A-Z, 0-9

Figure 4. Widget Settings Panel

Now you can set the Button property by using BunTalk script like

btn1.width(100) // Set btn1 width to 100px

2.2. Name Scope

In Buntalk the System object "sys" is always accessable. Other objects includes screen and widget which are created in BunMaker that can be accessed by object name.

Screens: Screen name is awlays exist, you can access screen name any time.
Widget Name: Widget name is only exist when screen is loaded.

You may create multiple screens in one project. like following example.

Table 1. Screen layout example
Screen name	Widget name
Screen1	btn1 btn2 lab1
Screen2	btn1 btn2 img1 arc2

And you can load screen like

sys.scr(Screen1)
//or
sys.scr(Screen2)

When Screen1 is loaded, you can access following widget by widget name.

btn1
btn2
lab1

You can use Buntalk like

btn1.x(100) (1)
lab1.text("Hello") (2)

Set btn1 x position
Set text display of lab1

When Screen2 is loaded, you can access following widget by widget name.

btn1
btn2
img1
img2

The btn1 in Screen1 and Screen2 is different object, depend on which screen is loaded. Also, you can’t access img1 when Screen2 is’t loaded. So, make sure which screen is loaded when access the widget.

You can set a EVENT trigger when screen is load, like Figure 5

Figure 5. Screen Load Event

This will print screen name to BunHMI UART, when screen is loaded.

A valid name of widget must be unique in the same screen.

Tip	You can use an invalid widget name like "#background", if you don’t want to interact with that widget. An invalid name do not need be an unique name in the same screen.

2.3. Widget Event

When interact with GUI, we always interesting in event, and make some response. BunHMI is based on LVGL library. You can set BunTalk script when LVGL events triggered.

On the widget Settings panel in BunMaker. You can select the Events page. Here list events that relative to the widget. Like figure Figure 6

Figure 6. BunTalk in Events Setting

In the above example. if the widget named "arc" with value=33. When the Button is clicked, BunHMI will run the BunTalk script and print string Arc:33 to UART and set widget named "label" with text V=33.

Although BunHMI is base on LVGL, but not all LVGL’s events are supported in BunHMI display. please check the BunMaker’s Widget Events Panel for events that are suppored.

For the detail of events description, please check LVGL Events doc.

3. Start BunTalk by example

3.1. BunTalk packet format on UART

BunTalk is a script like protocol, Just send string to interact with it. 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.

Here’s an example of BunTalk command

ptr("hello world")<EOT>

The BunHMI will send back string "hello world<EOT>" to host by UART.

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

#define EOT 0x04
// Send BunTalk to BunHMI
Serial1.printf("ptr(\"Hello\")");
Serial1.write(EOT); (1)
// or like this. This BunTalk command will set widget text to "CNT:xx"
Serial1.printf("widget.text(\"CNT:%d\")\x04", test_cnt++); (2)

Send EOT separately.
Use printf escape char \x04 in string format.

The string widget.text(), which is to invoke widget’s method, We will talk about widgets 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.setRX(PIN_SERIAL1_RX);
  Serial1.setTX(PIN_SERIAL1_TX);
  Serial1.begin(115200);
  // Set UART Rx Time out to 10ms
  Serial1.setTimeout(10);
}

// Check and receive data from BunHMI
int rxBunHmiData(char* dat, int dat_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;
  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 hmi_len = (i < dat_len) ? i : dat_len;
      // Copy hmiBuff to dat
      memcpy(dat, hmiBuff, hmi_len);
      // Move remain data to the head of hmiBuff
      int remain_len = 0;
      while (i < hmiBuffLen) {
        hmiBuff[remain_len++] = hmiBuff[i++];
      }
      hmiBuffLen = remain_len;
      return hmi_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.2. Multiple BunTalk script

You can send multiple BunTalk script at once by separate with ;

Here’s an example

ptr("hello world");widget.val(100)

This will print "hello world" and set widget’s value to 100.

3.3. BunTalk in Bunmaker

You can use BunTalk script in Bunmaker too. When use BunTalk in Bunmkaer, 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.

3.4. 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:

Send: 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.5. 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_VAL_END:widget_name

3.6. BunTalk Datatype

There 3 major data type

Number: Integer number.
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.7. 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 translate as a 16bit binary code to represent a RGB565 color code.

4. Global Functions

The following table show globol funtion in BunTalk

Table 2. Global Functions
Function	arguments & return	Desc.
ptr(…)	args: Number/String, ptr accept variable arguments you can pass 10 args at most. Argument maybe number or string. return: none ex: print widget width ptr("W=", widget.width(),"px") If width of widget is 100px, this will output W=100px to BunHMI UART.	ptr is used to send string to BunHMI UART Tx let host make response by the message. 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 maybe 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. Sys Methods

Sys is a globol object. you can access Sys by name sys. Like this code

sys.beep(2000, 100) (1)
ptr(sys.scr()) (2)

This will trigger BunHMI onboard beeper.
This will print current loaded screen name.

Table 3. Sys Methods
Method	arguments & return	Desc.
beep(hz, ms)	args: hz: Number, Beeper frequency ms: Number, millisecond return: none	Trigger BunHMI on board beeper, to generate frequency for millisecond.
bright(val)	args: val: Number, Set LCD backlight bright (0~100). return: none	Set LCD backlight
bright()	args: none return: Number, LCD backlight bright	Get LCD backlight
scr(screen)	args: screen: Screen name. return: none	Load screen
scr(screen, anim_type, time, delay)	args: screen: Screen name anim_type: OVER_LEFT OVER_RIGHT OVER_TOP OVER_BOTTOM MOVE_LEFT MOVE_RIGHT MOVE_TOP MOVE_BOTTOM FADE_ON time: time of the animation, in millisecond delay: delay before the transition, in millisecond return: none	Load screen with animation
scr()	args: none return: Object, The current screen object	Get current screen object
map(value, fromLow, fromHigh, toLow, toHigh)	args: value: the number to map. fromLow: the lower bound of the value’s current range. fromHigh: the upper bound of the value’s current range. toLow: the lower bound of the value’s target range. toHigh: the upper bound of the value’s target range. return: Number, The mapped value.	Re-maps a number from one range to another. Note that the "lower bounds" of either range may be larger or smaller than the "upper bounds" so the map() function may be used to reverse a range of numbers, for example y = map(x, 1, 50, 50, 1); The function also handles negative numbers well, so that this example y = map(x, 1, 50, 50, -100); is also valid and works well.
rand(max) rand(min, max)	args: max: Number, random number max value min: Number, random number min value return: Number, Random number	Get random number in range of min~max If only max is provided, the range will be 0~max
mb_show(title, mesg, btn1, btn2, …)	args: title: String, Title of message box. mesg: String, Message of message box. btn1: String, Button1 text btn2: String, Button2 text return: none	Show message box ex: sys.mb_show("Test", "This is test mesg", "OK", "Cancel") This will display message box with 2 buttons. You can use 1, 2 or 3 buttons, depend on how many arguments you passed. If button is clicked, BunHMI will send button text to UART. ie: if Button OK is clicked, you will get "OK" by UART. And message will disappear, if any button is clicked.
mb_close()	args: none return: none	Close message box
scr()	args: none return: String, The screen name	Get current screen name
stop_anim()	args: none return: none	Stop all animation in current screen.
save_str(slot, pos, string)	args: slot: Number, Slot of flash memory (0 or 1) pos: Number, pos of memory (0~255) string: String, string to save return: none	Save string in BunHMI nonvolatile flash memory. BunHMI proide 2 slot (slot 0, 1), each slot has 256bytes memory size. You can use these memory to save some product information like serial Number or version number. To save string to nonvolatile flash memory, you can use save_str() like `sys.save_str(0, 10, "123465")` This will save string "12345" to flash memory slot0 at position 10.
load_str(slot, pos, len)	args: slot: Number, Slot of flash memory (0 or 1) pos: Number, pos of memory (0~255) len: Number, max load length return: String, String from flash memory.	Load string from BunHMI nonvolatile flash memory. BunHMI proide 2 slot (slot 0, 1), each slot has 256bytes memory size. To load string from nonvolatile flash memory, you can use load_str() like `ptr(sys.load_str(0, 10, 50))` This will print string from memory slot0 at position 10. with max string length is 50
timer(id, delay, interval, repeat, script)	args: id, Number: Timer id (0~7) delay, Number, delay time in ms interval, Number, interval time in ms repeat, Number, enable repeat script, String, BunTalk script to run return: none	Set timer to run BunTalk script. There are 8 timers you can use. Use id to select which timer you want to use, and set the delay, interval and repeat to run BunTalk script. timer example `sys.timer(0, 500, 100, 1, "led.toggle()")` This will set timer0 to run script led.toggle() repeatedly wieh interval 100ms, after 500ms delay. Note: When new screen is loaded, old screen timer will be all stopped.
timer(id)	args: id, Number: Timer id (0~7) return: none	Stop timer. Use this method to stop timer.

6. Screen

Screen object can be got by sys.scr(), which is return current display screen object.

If you want to print name of screen you can write BunTalk like

ptr(sys.scr().name())

Table 4. Screen Methods
Method	arguments & return	Desc.
name()	args: val: none return: String	Get name of screen
bg_img(var)	args: var: Number, Image ID. var: String, Filename in SDCard return: none	If var is number. This will set image source by image id. Image ID is assigned in BunMaker editor. If var is string. This will set image source by filename in SDCard, image format may be jpg, png or bmp file.
bg_color(var)	args: val: Number, RGB565 color code. return: none.	Set background color

7. Widgets

7.1. Widget object

Widget is created by Bunmaker, you can call widget method by widget name which is set in Bunmaker.

Like w1.width(), the w1 is widget name, the width() method will return the width of the widget.

Table 5. Widget Methods
Method	arguments & return	Desc.
x(val)	args: val: Number, The transformed position x. return: none	Set the transformed position x value of widget.
x()	args: none return: Number, the transformed position x of widget.	Get the transformed position x value of widget relative to parent widget.
y(val)	args: val: Number, The transformed position y. return: none	Set the transformed position y value of widget.
y()	args: none return: Number, the transformed position y of widget.	Get the transformed position y value of widget relative to parent widget.
co_x()	args: none return: Number, the x position relative to screen.	Get the x position relative to screen.
co_y()	args: none return: Number, the y position relative to screen.	Get the y position relative to screen.
pos(x,y)	args: x,y: Number, the transformed position. return: none	Set the transformed position x,y value of widget.
width()	args: none return: Number, the width of widget.	Get the width of widget.
width(val)	args: val: Number, The width of widget. return: none.	Set the width of widget.
height()	args: none return: Number, the height of widget.	Get the width of widget.
height(val)	args: val: Number, The height of widget. return: none.	Set the height of widget.
size(w,h)	args: w,h: Number, the size of widget. return: none	Set the size of widget.
hidden(val)	args: val: Number, 0:Set widget hidden, 1: Set widget showup. return: none.	To show/hide widget.
hidden()	args: none return: Number, the hidden flag.	Get the hidden flag of the widget.
clickable(val)	args: val: Number, 0:Disable widget clickable, 1: Enable widget clickable. return: none.	Set widget clickable flag.
clickable()	args: none return: Number, the clickable flag.	Get the clickable flag of the widget.
disabled(val)	args: val: Number, 0:Set widget enable, 1: Set widget disabled. return: none.	To enable/disabled widget.
disable()	args: none return: Number, the disable flag.	Get the disable flag of the widget.
opa(val)	args: val: Number, Opacity range 0~255(full opacity) return: none.	To set opcity of widget
opa()	args: none return: Number, the opacity value.	Get the opacity value of widget.
text_color(val)	args: val: Number, RGB565 color code. return: none.	Set text color of the widget and widget’s children
text_opa(val)	args: val: Number, text Opacity: 0~255 return: none.	Set text opacity of the widget and widget’s children

7.1.1. Animation Methods

The animation methods get a little complicated. But they are quite similar.

This table show how to animation on x properties of widget, other properties are apply in similar way.

Table 6. Animation Methods
Method	arguments & return	Desc.
anim_x(end, duration[ms], delay[ms], path, [finish_evt=0])	args: end: Number, end value of animation duration: Number, duration time of animation in ms delay: Number, delay time of animation in ms path: Number, Select 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, default to 0, if arg omit, 0: No event send, 1: Send out event message, when animation done. code example: `/* anim x property with path 1:lv_anim_path_ease_in / widget.anim_x(150, 500, 0, 1) / or / widget.anim_x(150, 500, 0, 1, 0)` This will animate widget x property to 150 in 500ms with path ease in. Send finish Event when animation done. return:* none.	Do animation change on widget’s x property.
anim_x()	args: none return: none.	Stop animation. If you don’t pass any args, this will stop animation immediately
anim_play_x(start, end, duration[ms], delay[ms], path, playback_time, playback_delay, repeate_count, repeate_delay, [send_finish_evt=0])	args: start: Number, start value of animation end: Number, end value of animation duration: Number, duration time of animation in ms delay: Number, delay time of animation in ms path: Number, Set animation path, same as anim_x() playback_time: Numnber, duration time of animation palyback in ms playback_delay: Number, playback delay time of animation in ms repeate_count: Number, repeate count of animation repeate_delay: Number, delay time of repeate in ms finish_evt: Number, default to 0, if arg omit, 0: No event send, 1: Send out event message, when animation done. code example: `/* play x property with path 1:lv_anim_path_ease_in / widget.anim_play_x( -150, 150, 300, 0, 1, 100, 200, 3, 500) / or / widget.anim_play_x( -150, 150, 300, 0, 1, 100, 200, 3, 500, 0)` This will animate widget x property from -150 to 150 in 300ms, no delay, with path linear, No Event send when animation done. and playback duration in 100ms, playback delay 200ms, repeate count is 3 times and repeate delay is 500ms. return:* none.	Do animation play forward & backword on widget’s x property.
anim_y anim_play_y	refer: anim_x anim_play_x	Animatie y property
anim_w anim_play_w	refer: anim_x anim_play_x	Animatie width property
anim_h anim_play_h	refer: anim_x anim_play_x	Animatie height property
anim_opa anim_play_opa	refer: anim_x anim_play_x	Animatie opacity property

If you want stop all animations, you can use

code example:

sys.stop_anim()

This will stop all animations.

And when a new screen is loaded, all animations in old screen will be stoped.

7.2. Arc

Arc widget inherit all from Table 5. Plus following methods

Table 7. Arc Methods
Method	arguments & return	Desc.
val(val)	args: val: Number, value return: none	Set value
val()	args: none return: Number, value of arc	Get arc value
angle(start, end)	args: start: Number, start angle (0~360) end: Number, end angle (0~360) return: none	Set arc angle. Zero degrees is at the middle right (3 o’clock) of the object and the degrees are increasing in clockwise direction.
angle()	args: none return: String, x,y	Get arc angle, if start angle is 120, stop angle is 60 this will return string 120,60
bg_angle(start, end)	args: start: Number, start angle (0~360) end: Number, end angle (0~360) return: none	Same as angle(start, end), this set the background angle of arc.
rotation(val)	args: val: Number, roataion angle (0~360) return: none	Set arc rotation angle
range(min, max)	args: min: Number, min range value max: Number, max range value return: none	Set value range.
range()	args: none return: String, min,max	Get range, if range min is 0, range max 100 this will return string 0,100
anim_val anim_play_val	refer: [anim_x] [anim_play_x]	Animatie widget property

7.3. Bar

Bar widget inherit all from Table 5. Plus following methods

Table 8. Slider Methods
Method	arguments & return	Desc.
val(val,[anim=0])	args: val: Number, value anim: Number, 0: No animation, 1: With animation return: none	Set value
val()	args: none return: Number, bar value	Get value
start_val(val)	args: val: Number, value return: none	Set start value
start_val()	args: none return: Number, start value	Get start value
range(min, max)	args: min: Number, min range value max: Number, max range value return: none	Set value range.
range()	args: none return: String, min,max	Get range, if range min is 0, range max 100 this will return string 0,100
anim_val anim_play_val	refer: [anim_x] [anim_play_x]	Animatie widget property

7.4. Button

Button widget inherit all from Table 5.

7.5. Calendar

Calendar widget inherit all from Table 5. Plus following methods

Table 9. Calendar Methods
Method	arguments & return	Desc.
today_date(year,month,day)	args: year: Number, Year month: Number, Month day: Number, day return: none	Set today date
today_date()	args: none return: String, today date.	Get today date. if today date is 2020/1/1，it will return 2020,1,1
showed_date(year,month)	args: year: Number, Year month: Number, Month return: none	Set showed date
showed_date()	args: none return: String, showed date.	Get showed date. if showed date is 2020/1，it will return 2020,1

7.6. Chart

Chart widget inherit all from Table 5. Plus following methods.

The first series id is start by 0.

Table 10. Chart Methods
Method	arguments & return	Desc.
next(ser,val)	args: ser: Number, series id val: Number, value return: none	Set next value of series
mnext(…)	args: Number, multiple arguments return: none	Set next value to multiple series ex: widget.mnext(10,22,15) This will set multiple series next value for series[0]: 10, series[1]: 22, series[2]: 15
set_value(ser, id, val)	args: ser: Number, series id id: Number, series data index val: Number, value return: none	Set particular data point of series
set_all(ser, val)	args: ser: Number, series id val: Number, value return: none	Set all data set of series
next2(ser, x_val, y_val)	args: ser: Number, series id x_val: Number, x value y_val: Number, y value return: none	Set next x,y values of series. This is for scatter type of chart.
set_value2(ser, id, x_val, y_val)	args: ser: Number, series id id: Number, series data index x_val: Number, x_value y_val: Number, y_value return: none	Set particular data point of series, This is for scatter type of chart.
set_range(ser, min, max)	args: ser: Number, series id min: Number, min value max: Number, max value return: none	Set range of series
update_mode(mode)	args: mode: Number, 0: Shift mode, 1: Circular mode return: none	Set update mode
type(type)	args: type: Number 0: NONE Type 1: Line Type 2: Bar Type 3: Scatter Type return: none	Set chart type
get_point_pos(ser, id)	args: ser: Number, series id id: Number, data id return: String	Get point position, if point is at x:10, y:30, this method will return 10,30
x_start(ser, point)	args: ser: Number, series id point: Number, point index return: none	Set x start point
x_start(ser)	args: ser: Number, series id return: Number	Get x start point of series
zoom_x(val)	args: val: Number, zoom value return: none	Set zoom factor of x axis, 128=50%, 256=100%, 512=200% and so on.
zoom_x()	args: none return: Number, zoom factor	Get zoom factor of x axis
zoom_y(val)	args: val: Number, zoom value return: none	Set zoom factor of y axis, 128=50%, 256=100%, 512=200% and so on.
zoom_y()	args: none return: Number, zoom factor	Get zoom factor of y axis
point_count(val)	args: val: Number, point count return: none	Set point count of chart.
point_count()	args: none return: Number, pointer count	Get point count of chart
div_line(hdiv, vdiv)	args: hdiv: Number, horizontal div line count vdiv: Number, vertical div line count return: none	Set div line count
ser_hide(ser, hide)	args: ser: Number, series id hide: Number, 0: Show series, 1: Hide series return: none	Set show/hide series
ser_color(ser, color)	args: ser: Number, series id color: Number, RGB565 color code. return: none	Set series color

7.7. Checkbox

Checkbox widget inherit all from Table 5. Plus following methods

Table 11. Checkbox Methods
Method	arguments & return	Desc.
text(val)	args: val: String/Number return: none	Set display text
text()	args: none return: String, text.	Get display text.
checked(val)	args: val: Number, 0: checked, 1: unchecked return: none	Set checkbox check status
checked()	args: none return: Number, 0: checked, 1: unchecked	Get checkbox check status

7.8. Dropdown

Dropdown widget inherit all from Table 5. Plus following methods

Table 12. Dropdown Methods
Method	arguments & return	Desc.
options(str)	args: str: String, options separate by '\n' return: none	Set dorpdown options. ex: widget.options("Apple\nBanna\nStrawberry")
options()	args: none return: String, options string.	Get options string.
add_option(str, pos)	args: str: String, option pos: Number, add position return: none.	Add option item.
clear_options()	args: none return: none.	Clear all options
selected(pos)	args: pos: Number, select position return: none.	Set select position
selected()	args: none return: Number, selected position.	Get selected position
selected_str()	args: none return: String, selected item string.	Get selected item string.
text(val)	args: val: String/Number return: none	Set display title text or number of dropdown title
text()	args: none return: String, title text.	Get display title.
dir(val)	args: val: Number 0: Left 1: Right 2: Top 3: Buttom return: none	Set popup menu display direction
dir()	args: none return: Number, disp dir, refer dir(val) method.	Get popup menu display dir
highlight(val)	args: Number, 0: disable highlight, 1: enable highlight return: none	Set highlight status
highlight()	args: none return: Number, 0: highlight is disable, 1: highlight is enable	Get highlight status
open()	args: none return: none.	Open dorpdown menu
close()	args: none return: none.	Close dorpdown menu
is_open()	args: none return: Number. 0: menu is close, 1: menu is open	Get dorpdown menu open status.
option_cnt()	args: none return: Number. Option count.	Get dorpdown options count.

7.9. Image

Image widget inherit all from Table 5. Plus following methods

Table 13. Image Methods
Method	arguments & return	Desc.
angle(val)	args: val: Number, Angle value in 0.1deg (0~3600) return: none	Set rotation angle
angle()	args: none return: Number, Rotation angle.	Get rotation angle.
zoom(val)	args: val: Number, Zoom factor return: none	Set zoom factor, 128=50%, 256=100%, 512=200% and so on.
zoom()	args: none return: Number, zoom factor	Get zoom factor.
src(var)	args: var: Number, Image ID. var: String, Filename in SDCard return: none	If var is number. This will set image source by image id. Image ID is assigned in BunMaker editor. If var is string. This will set image source by filename in SDCard, image format may be jpg, png or bmp file. Note: If you select image source in Bunmaker is not a gif image, Don’t use src() to assign a gif image. It won’t showup.
offset_x(val)	args: val: Number, offset x return: None	Set image display offset x value.
offset_x()	args: none return: Number, offset x	Get image display offset x value.
offset_y(val)	args: val: Number, offset y return: None	Set image display offset y value.
offset_y()	args: none return: Number, offset y	Get image display offset y value.
pivot(x, y)	args: x: Number, piovt x y: Number, piovt y return: None	Set image rotation pivot.
pivot()	args: None return: String, pivot value with the format "x,y"	Get image rotation pivot.
anim_angle anim_play_angle anim_zoom anim_play_zoom	refer: [anim_x] [anim_play_x]	Animatie widget property

7.10. ImgBtn

Imgbtn widget inherit all from Table 5.

7.11. Keyboard

Keyboard widget has 2 special key that will trigger event.

You can write BunTalk in event handler when these key is pressed.

Keyboard widget inherit all from Table 5. Plus following methods

Table 14. Keyboard Methods
Method	arguments & return	Desc.
mode(val)	args: val: Number 0: Mode text lower 1: Mode text upper 2: Mode special 3: Mode number 4: Digital pad return: none	Set keyboard mode
mode()	args: none return: Number. refer val list in mode() method.	Get kayboard mode.
popover(val)	args: Number: 0 disable popover, 1: enable popover return: none.	Set show the button title in a popover when pressed.
popover()	args: none return: Number popover status	Get popover status.
textarea(obj)	args: obj: Textarea Widget name return: none	Set keyboard target textarea widget
ptrkey(prefix, [ctrl_only=0])	args: prefix: String, Prefix of print message ctrl_only: Number, 0: print all key char, 1: print control key only return: None	Print the last key of keyboard pressed. This will be used in EVENT_PRESSED of keyboard widget usually. Normal key are like 0-9,A-Z,… control keys are like backspace, left, right … Control keys are listed below, which contains more than one char 1#: To Number mode ABC: To Upper case mode abc: To Lower case mode NL: Key New Line OK: Key OK CL: Key Close BK: Key Backspace LT: Key Left RT: Key Right KB: Key Keyboard If you pass and set ctrl_only=1, then only control keys will be printed. ex: widget.ptrkey("KB:") : This will print "KB:a", if the key 'a' is pressed. widget.ptrkey("KB:",1) : This will print control key only, like "KB:BK", when 'Backspace' is pressed. But will not print message when normal key is pressed, for example key 'a';

7.12. Label

Label widget inherit all from Table 5. Plus following methods

Table 15. Label Methods
Method	arguments & return	Desc.
text(val)	args: val: String/Number return: none	Set label display text or number
text()	args: none return: String, Label text.	Get label display text.

7.13. Led

Led widget inherit all from Table 5. Plus following methods

Table 16. Led Methods
Method	arguments & return	Desc.
on(val)	args: val: Number, 0: LED off, 1: LED on. return: none	Set Led on/off
toggle()	args: none return: none	Set Led state between on/off
bright(val)	args: val: Number, brightness (0~255). return: none	Set Led brightness
bright()	args: none return: Number, Led brightness(0~255)	Get Led brightness
color(color)	args: color: Number, RGB565 color code. return: none	Set Led color
anim_bright anim_play_bright	refer: [anim_x] [anim_play_x]	Animatie led bright

7.14. Line

Line widget inherit all from Table 5. Plus following methods

Table 17. Line Methods
Method	arguments & return	Desc.
color(color)	args: color: Number, RGB565 color code. return: none	Set Line color

7.15. Panel

Panel widget inherit all from Table 5.

7.16. QRCode

QRCode widget inherit all from Table 5. Plus following methods

Table 18. QRCode Methods
Method	arguments & return	Desc.
update(str)	args: str: String return: none	Update qrcode to show new string.

7.17. Roller

Roller widget inherit all from Table 5. Plus following methods

Table 19. Roller Methods
Method	arguments & return	Desc.
options(str, [mode=0])	args: str: String, options separate by '\n' mode: Number, 0: Roller normal, 1: Roller infinite return: none.	Set roller options ex: widget.options("Apple\nBanna\nStrawberry") or widget.options("Apple\nBanna\nStrawberry", 1)
options()	args: none return: String, options string.	Get options string.
selected(pos, [anim=0])	args: pos: Number, select position anim: Number, 1: Enable anim, 0: Disable anim return: none.	Set select position
selected()	args: none return: Number, selected position.	Get selected position
selected_str()	args: none return: String, selected item string.	Get selected item string.

7.18. Slider

Slider widget inherit all from Table 5. Plus following methods

Table 20. Slider Methods
Method	arguments & return	Desc.
val(val,[anim=0])	args: val: Number, value anim: Number, 0: No animation, 1: With animation return: none	Set value
val()	args: none return: Number, value of slider	Get value
left_val(val,[anim=0])	args: val: Number, value anim: Number, 0: No animation, 1: With animation return: none	Set left value
left_val()	args: none return: Number, left value of slider	Get left value
range(min, max)	args: min: Number, min range value max: Number, max range value return: none	Set value range.
range()	args: none return: String, min,max	Get range, if range min is 0, range max 100 this will return string 0,100
anim_val anim_play_val	refer: [anim_x] [anim_play_x]	Animatie widget property

7.19. Switch

Switch widget inherit all from Table 5. Plus following methods

Table 21. Switch Methods
Method	arguments & return	Desc.
checked(val)	args: val: Number, 0: checked, 1: unchecked return: none	Set switch check status
checked()	args: none return: Number, 0: checked, 1: unchecked	Get switch check status

7.20. Textarea

Textarea widget inherit all from Table 5. Plus following methods

Table 22. Textarea Methods
Method	arguments & return	Desc.
text(val)	args: val: String/Number return: none	Set text
text()	args: none return: String, text.	Get text.
add_text(var)	args: var: String/Number return: none	Add text, you can add string or number.
del_char(forward)	args: forward: Number, 0: del char backward, 1: del char forward return: none	Del char in textarea.
cursor_pos(pos)	args: pos: Number, Cursor pos return: none	Set cursor pos
cursor_move(dir)	args: dir: Number 0: move left 1: move right 2: move up 3: move down return: none	Move cursor dir

8. SD Card

There is one SD card slot on BumHMI, you can access SD Card by Buntalk. BunHMI leverage Fatfs filesystem library to access SD Card. Most API are similar with Fatfs.

8.1. File descriptor

Due to resource constraints BunHMI only allow limited file descripts. Currently, you can open 4 files at the same time. If you need access another file, the original opened file will be closed.

8.2. API in sys object

SD Card API is included in sys object. So you can invoke file system API like

/* print directory content */
ptr(sys.f_dir(""))

/* open file */
sys.f_open(0,"/test2.txt", 1)

This will open SD Card file "/test2.txt" in write mode, and use file descriptor 0.

Table 23. Sys Methods
Method	arguments & return	Desc.
f_dir(path, [offset=0], [cnt=0])	args: path: String, Dir path offset: Number, files to skip cnt: Number,file list count, cnt=0 is no count limitation. If only path is passed, the offset and cnt is set to 0 return: String, directory list, The max length of string is 512	This will list directory content. like /image\n text.txt\n photo.jpg\n The max return string length is 256Bytes, if the returned directory’s content exceed 256Bytes, it will show '…' at the end like /image\n text.txt\n photo.jpg\n … You can use offset to skip files items, that will not includes in return string. You can use cnt to limit files list count, that only includes cnt number of files in return string. if cnt=0, there will be no count limitation.
f_open(fil_id, full_name, mode)	args: fil_id: Number, file descriptor id(0~3) full_name: String, file full name includes path. mode: Number, open mode 0: Read mode 1: Write mode, Open/Create file, If the file is existing, it will be truncated and overwritten. 2: Append mode, Open/Create file, If the file is existing read/write pointer is set end of the file. return: Number, result code of f_open of fatfs.	Open file method, after file open, you can access file by the fil_id. The f_open() will close previous opened fil_id, if you don’t invoke f_close() before.
f_close(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: none	Close file. Closes an open file object. If the file has been changed, the cached information of the file is written back to the SD Card. After close file, The fil_id will become invalid.
f_sync(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: none	Sync file function. flushes the cached information of a writing file. and keep file opened, you can use same fil_id to do read/write after f_sync().
f_gets(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: String	Reads a string from the file. If something wrong or reach end of file(EOF), this will return none.
f_puts(fil_id, string)	args: fil_id: Number, file descriptor id(0~3) string: String, String to write return: Number, result code of f_puts of fatfs.	Writes a string to the file. If something wrong or reach end of file(EOF), this will return none.
f_read(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: String	This method just like f_gets() but this will add 2 char at begining of return string. 1st char represent the result code: A: read OK, and there are more data to read, not EOF(end of file). E: file pointer reach the EOF or error. X: No SD Card exist. 2nd char is delimiter '\|' A read OK example may like this: A\|Hello World If reach EOF it will return E\| If no SD Cards exist it will return X\| Use this method can help to identify if we has reached the EOF or just get an empty string.
f_lseek(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: Number	This method, invoke f_leek of fatfs.
f_size(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: Number	This method, invoke f_size of fatfs.
f_tell(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: Number	This method, invoke f_tell of fatfs.
f_eof(fil_id)	args: fil_id: Number, file descriptor id(0~3) return: Number	This method, invoke f_eof of fatfs.
f_ulink(full_name)	args: full_name: String, file full name includes path. return: Number	This method, invoke f_unlink of fatfs.
f_rename(old_name, new_name)	args: old_name: String, old file full name includes path. new_name: String, new file full name includes path. return: Number	This method, invoke f_rename of fatfs.

9. Wav File playback

BunHMI model can play wavfile(not for all models). The wav file format supported are

Channels: 1 or 2
Sampling bits: 8/16/24 bits

9.1. API in sys object

Wav play API is included in sys object. So you can invoke wav play API like

/* Play wav file */
sys.wav_play("file.wav")

Method	arguments & return	Desc.
wav_play(file, [pause=0], [loop=0])	args: file: String, full filename wav file in SD Card pause: Number, 1: pause play at start, 0: not pause at start loop: Number, 1: loop play mode, 0: not loop If pass file argument only, the pause and loop arguments are 0. return: 0:OK >0: SD Card open file error(fatfs error) -1: file format error -2: Audio decoder error	Open and Play wav file in SD Card, If you want set audio volume value at beginning, you can set pause=1, and adjust audio volume, then disable pause to start play audio.
wav_pause(pause)	args: pause: Number, 1: pause wav playing, 0: start wav playping. return: none	Pause/Unpause wav playing
wav_stop()	args: none return: none	Stop wav playing
wav_dur()	args: none return: Number, duration of wav file in 0.01 Sec. ie: 100=1Sec.	Get duration of current playing wav file.
wav_cur()	args: none return: Number, current playing time of wav file in 0.01 Sec. ie: 100=1Sec.	Get current playing time of wav file.
wav_to(time)	args: time: Number, Set playing wav file to time, in 0.01 Sec. ie: 100=1Sec. return: none	Set playing wav file to time
audio_mute(mute)	args: mute: Number, 1: Audio mute, 0: Audio unmute. return: none	Mute/Unmute audio
audio_vol(l_vol, r_ovl)	args: l_vol Number, Audio volume of left channel (0~15). r_vol Number, Audio volume of right channel (0~15). return: none	Set audio output volume.
audio_vol()	args: none return: String: n,n, n=0~15	Get audio output volume.

10. Buntalk with Checksum

When using Buntalk communication there are chance with bit error on UART. You can use checksum to check if there are bit error occure.

10.1. Checksum format

The checksum calculation is to sum of all char’s of Buntalk script and modulo by 0xff, and append 2 hex number at the end of script.

When using checksum format, you must add <ETB>(17h) at the end of command string. instead of <EOT>(04h). BunHMI will check last byte of script, when last byte of script is <ETB>(17h), it will check script with checksum.

Here is an example, if you want send:

ptr("Hello")

Then sum up all chars.

70h + 74h + 72h + 28h + 22h + 48h + 65h + 6Ch + 6Ch + 6Fh + 22h + 29h = 3DFh

The modulo of 3dfh is DFh

Then you have to send:

ptr("Hello")DF<ETB>

If checksum is error, you will get error response message

!!cksum err<EOT>

10.2. Print with checksum

When you want receive string from UART with checksum, you can use ptk() function. Just like ptr(), but ptk() will append 2 hex number of checksum at the end of string.

For example, when run script

ptk("Buntalk")

You will get string

BuntalkD1<ETB>

You can ckeck last byte, if last byte is <ETB>(17h), then last two chars is checksum.