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).

BunHMI
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.

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.

Bunmaker
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

  1. Start with char _, a-z, A-Z.

  2. And only contain _, a-z, A-Z, 0-9

WidgetName
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)
  1. Set btn1 x position

  2. 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

Screen load event
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

Event BunTalk
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)
  1. Send EOT separately.

  2. 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.

BunTalk in event settings
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

  1. Number: Integer number.

  2. String: String is surround by double quote and is encoded with UTF-8 format.

  3. 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)
  1. This will trigger BunHMI onboard beeper.

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

  1. OVER_LEFT

  2. OVER_RIGHT

  3. OVER_TOP

  4. OVER_BOTTOM

  5. MOVE_LEFT

  6. MOVE_RIGHT

  7. MOVE_TOP

  8. MOVE_BOTTOM

  9. 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

  1. lv_anim_path_linear

  2. lv_anim_path_ease_in

  3. lv_anim_path_ease_out

  4. lv_anim_path_ease_in_out

  5. lv_anim_path_bounce

  6. 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.

Keyboard event

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

Keyboard event handler

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.