Silicon Labs BGSCRIPT User manual
BGSCRIPT SCRIPTING LANGUAGE
DEVELOPER GUIDE
Wednesday, 2 December 2020
Version 34.
Table of Contents
1 Version History ________ ________________________________________________________________ 5
2 Introduction ___________________________________________________________________________ 6
3 What is BGScript? ______________________________________________________________________ 7
3.1 BGScript Scripting Language ________________________________________________________ 7
3.2 BGScript vs. BGAPI ________________________________________________________________ 8
4 BGScript Syntax _______________________________________________________________________ 9
4.1 Comments _______________________________________________________________________ 9
4.2 Variables and Values _______________________________________________________________ 9
4.2.1 Values ____________________________________________________________________ 9
4.2.2 Variables __________________________________________________________________ 9
4.2.3 Global Variables ___________________________________________________________ 11
4.2.4 Constant Values ___________________________________________________________ 11
4.2.5 Buffers ___________________________________________________________________ 11
4.2.6 Strings ___________________________________________________________________ 12
4.2.7 Constant Strings ___________________________________________________________ 12
4.3 Expressions _____________________________________________________________________ 14
4.4 Commands ______________________________________________________________________ 15
4.4.1 event <event_name> (<event_parameters>) _____________________________________ 15
4.4.2 if <expression> then [else] end if _______________________________________________ 15
4.4.3 while <expression> end while _________________________________________________ 16
4.4.4 call <command name>(<command parameters>..)[(response parameters)] _____________ 16
4.4.5 let <variable> = <expression> _________________________________________________ 16
4.4.6 return ____________________________________________________________________ 17
4.4.7 sfloat(mantissa, exponent) ___________________________________________________ 17
4.4.8 float(mantissa, exponent) ____________________________________________________ 18
4.4.9 memcpy(destination, source, length) ___________________________________________ 18
4.4.10 memcmp(buffer1, buffer2, length) _____________________________________________ 18
4.4.11 memset(buffer, value, length) ________________________________________________ 19
4.5 Procedures ______________________________________________________________________ 20
4.6 Using multiple script files ___________________________________________________________ 21
4.6.1 import ___________________________________________________________________ 21
4.6.2 export ___________________________________________________________________ 21
5 BGScript Limitations ___________________________________________________________________ 23
5.1 32-bit resolution __________________________________________________________________ 23
5.2 Declaration required before use ______________________________________________________ 23
5.3 Reading internal temperature meter disabled IO interrupts _________________________________ 23
5.4 Writing data to an endpoint, which is not read ___________________________________________ 23
5.5 No interrupts on Port 2 _____________________________________________________________ 23
5.6 Performance _____________________________________________________________________ 23
5.7 RAM ___________________________________________________________________________ 23
5.8 Flash ___________________________________________________________________________ 24
5.9 Stack ___________________________________________________________________________ 24
5.9.1 Interface drivers ____________________________________________________________ 24
5.10 Debugging _____________________________________________________________________ 24
6 Example BGscripts ____________________________________________________________________ 25
6.1 Basics __________________________________________________________________________ 25
6.1.1 Catching system start-up _____________________________________________________ 25
6.1.2 Catching Bluetooth connection event ___________________________________________ 26
6.1.3 Catching Bluetooth disconnection event _________________________________________ 27
6.2 Hardware interfaces _______________________________________________________________ 28
6.2.1 ADC _____________________________________________________________________ 28
6.2.2 I2C ______________________________________________________________________ 30
6.2.3 GPIO ____________________________________________________________________ 31
6.2.4 SPI ______________________________________________________________________ 33
6.2.5 Generating PWM signals ____________________________________________________ 35
6.3 Timers __________________________________________________________________________ 36
6.3.1 Continuous timer generated interrupt ____________________________________________ 36
6.3.2 Single timer generated interrupt ________________________________________________ 37
Silicon Labs Page of 3 55
6.4 USB and UART endpoints __________________________________________________________ 38
6.4.1 UART endpoint ____________________________________________________________ 38
6.4.2 USB endpoint _____________________________________________________________ 39
6.5 Attribute Protocol (ATT) ____________________________________________________________ 40
6.5.1 Catching attribute write event _________________________________________________ 40
6.6 Generic Attribute Profile (GATT) ______________________________________________________ 41
6.6.1 Changing device name ______________________________________________________ 41
6.6.2 Writing to local GATT database _______________________________________________ 42
6.7 PS store ________________________________________________________________________ 43
6.7.1 Writing a PS keys __________________________________________________________ 43
6.7.2 Reading a PS keys _________________________________________________________ 44
6.8 Flash ___________________________________________________________________________ 45
6.8.1 Erasing, Reading and Writing Flash ____________________________________________ 45
6.9 Advanced scripting examples ________________________________________________________ 47
6.9.1 Catching IO events and exposing them in GATT __________________________________ 47
6.10 Bluegiga Development Kit Specific Examples __________________________________________ 48
6.10.1 Display initialization ________________________________________________________ 48
6.10.2 FindMe demo ____________________________________________________________ 49
6.10.3 Temperature and battery readings to display ____________________________________ 50
6.11 BGScript tricks __________________________________________________________________ 52
6.11.1 HEX to ASCII _____________________________________________________________ 52
6.11.2 UINT to ASCII ____________________________________________________________ 52
7 BGScript editors ______________________________________________________________________ 54
7.1 Notepad ++ ______________________________________________________________________ 54
7.1.1 Syntax highlight for BGScript _________________________________________________ 54
Silicon Labs Page of 4 55
1
Version History
Version Comments
2.3 BGScript limitations updated with performance comments
2.4 Added new features included in v.1.1 software.
Small improvements made into BGScript examples
Added a 4-channel PWM example
2.5 Reading ADC does not disable IO interrupts
2.6 Added battery reading example using the internal battery monitor
2.7 Updated ADC internal reference to 1.24V (was 1.15V)
3.0 BLE SW1.2 additions and changes:
Procedure support added
Memset support for buffer handling added
Limitations section aligned with the new SW enhancements
In addition, editorial improvements are done within the document.
3.1 Improved BGScript syntax documentation
3.2 I2C example improved and corrected
3.3 Splitting BGScript into multiple files through IMPORT and export directive made possible
3.4 Improvements to BGScript syntax description
3.5
3.6 Editorial changes
3.7
3.8 Added comments about RAM and Flash availability to BGScript limitations.
Added example how to use the raw flash API.
3.9 Comments added to flash example script
4.0 Removed BGScript limitation of 255 byte variables
4.1 Added debug instructions
4.2 Editorial changes
4.3 Renamed "Bluetooth Smart" to "Bluetooth Low Energy" according to the official Bluetooth SIG
nomenclature.
Bluetooth Low Energy Software 1.3.0 compatible document version. The limitation for the
maximum size of all DIM variables is removed.
Bluetooth Low Energy Software 1.3.1 compatible document version. Editorial changes and
Examples section updated.
Silicon Labs Page of 5 55
2
Introduction
THIS DOCUMENT IS NOT A COMPREHENSIVE REFERENCE FOR THE COMPLETE BGAPI
PROTOCOL.
This covers only the BGScript syntax and some brief examples, but is not meant to show every
possible command, response, and event that is part of the Bluegiga API. For this information, please
see the latest corresponding for the modules which you are using. The API API Reference Guide
Reference Guide may be downloaded from the same Documentation page from which this document
came.
This document briefly describes the Bluegiga BGScript programming language for Bluegiga
Energy Products. It explains what the BGScript programming language is, what its benefits are, how it may be
used, and what its limitations are. The document also contains multiple examples of BGScript code and some
API methods, and how it can be used to perform various tasks such as detecting
receiving and transmitting data, and managing hardware interfaces like UART, USB, SPI, and I2C.
Bluetooth
Bluetooth
connections,
Low
Silicon Labs Page of 6 55
3
What is BGScript?
Figure: BGScript System Architecture
A simple BGScript code example:
3.1 BGScript Scripting Language
Bluegiga BGScript is a simple BASIC-style programming language that allows end-user applications to be
embedded to the Bluegiga
fully standalone
size, cost and power consumption reductions. Although being a simple and easy-to-learn programming
language BGScript does provide features and functions to create fairly complex and powerful applications and it
provides the necessary APIs for managing Bluetooth connections, security, data transfer and various hardware
interfaces such as UART, USB, SPI, I2C, GPIO, PWM and ADC.
BGScript is fully event based programming language and code execution is started when events such as
system start-up,
BGScript applications are developed with Bluegiga's free-of-charge
BGScript applications are executed in the BGScript Virtual Machine (VM) that is part of the Bluegiga Bluetooth
Low Energy software. The Bluetooth Low Energy SDK comes with all the necessary tools for code editing and
compilation and also the needed tools for installing the complied firmware binary to the Bluegiga Bluetooth Low
Energy modules. Multiple example applications and code snipplets are also available for Bluegiga implementing
applications like thermometers, heart rate transmitters, medical sensors and iBeacons just to mention a few.
The illustration below describes the Bluegiga Bluetooth Low Energy software, API and how BGScript VM and
applications interface to it.
Bluetooth
Bluetooth
Bluetooth
Low Energy devices without the need of an external MCU and this enables further
connection, I/O interrupt etc. occur.
Low Energy modules. The benefit of using BGScript is that one can create
Bluetooth
Low Energy SDK and the
Silicon Labs Page of 7 55
# system started, occurs on boot or reset
event system_boot(major, minor, patch, build, ll_version, protocol_version, hw)
# Enable BLE advertising mode
call gap_set_mode(gap_general_discoverable, gap_undirected_connectable)
# Enable BLE bonding mode
call sm_set_bondable_mode(1)
# Start a repeating timer at 1-second interval (32768Hz = crystal frequency)
call hardware_set_soft_timer(32768, 0, 0)
end
3.2 BGScript vs. BGAPI
BGScript applications are just one way of controlling the Bluegiga Bluetooth Low Energy modules and it may
not be usable in every use case. For example the amount of available hardware interfaces, RAM or Flash may
limit you to implement and execute your application on the microcontroller on-board the Bluegiga Bluetooth Low
Energy modules. If this is the case an alternate way of controlling the module is the BGAPI protocol. BGAPI
protocol is a simple binary based protocol that works over the physical UART and USB interfaces available on
the Bluetooth Low Energy modules. An external host processor can be used to implement the end user
application and this application can control the Bluetooth Low Energy modules using the BGAPI protocol.
When BGScript is enabled, the BGAPI protocol is disabled. BGScript cannot be used at the same
time as BGAPI control from an external host.
Silicon Labs Page of 8 55
4 BGScript Syntax
The BGScript scripting language has BASIC-like syntax. Code is executed only in response to and events,
each line of code is executed in successive order, starting from the beginning of the definition and ending event
at a or statement. Each line represents a single command.return end
BGScript scripting language is currently supported by multiple Bluegiga's Low Energy and Wi-Fi
Bluetooth
products and the BGScript commands and events are specific to each technology.
Below is a conceptual code example of a simple BGScript based Bluegiga Wi-Fi software. The code below is
executed at the system start i.e. when the device is powered up and the code will start the Wi-Fi subsystem and
connects to a Wi-Fi access point with the SSID " ".test_ssid
Simple BGScript syntax example
# system start-up event listener
event system_boot(major, minor, patch, build, bootloader, tcpip, hw)
# Turn Wi-Fi subsystem on
call sme_wifi_on()
end
# Wi-Fi ON event listener
event sme_wifi_is_on(result)
# connect to a network
call sme_connect_ssid(9, "test_ssid")
end
4.1 Comments
Anything after a character is considered as a comment, and ignored by the compiler.#
x = 1 # comment
4.2 Variables and Values
4.2.1 Values
Values are always interpreted as integers (no floating-point numbers). Hexadecimal values can be expressed
by putting before the value. Internally, all values are 32-bit signed integers stored in memory in little-endian $
format.
x = 12 # same as x = $0c
y = 703710 # same as y = $abcde
IP addresses are automatically converted to their 32-bit decimal value equivalents.
x = 192.168.1.1 # same as x = $0101A8C0
4.2.2 Variables
Variables (not buffers) are signed 32-bit integer containers, stored in little-endian byte order. Variables must be
defined before usage.
dim x
Silicon Labs Page of 9 55
Example
dim x
dim y
x = (2 * 2) + 1
y = x + 2
Silicon Labs Page of 10 55
4.2.3 Global Variables
Variables can be defined globally using definition which must be used outside an block.dim event
dim j
# software timer listener
event hardware_soft_timer(handle)
j = j + 1
call attributes_write(xgatt_counter, 2, j)
end
4.2.4 Constant Values
Constants are signed 32-bit integers stored in little-endian byte order and they also need to be defined before
use. Constants can be particularly useful because they do not take up any of the limited RAM that is available to
BGScript applications and instead constant values are stored in flash as part of the application code.
const x = 2
4.2.5 Buffers
Buffers hold 8-bit values and can be used to prepare or parse more complex data structures. For example a
buffer might be used in a Low Energy on-module application to prepare an attribute value before
Bluetooth
writing it into the attribute database.
Similar to variables buffers need to be defined before usage. Currently the maximum size of a buffer is 256
bytes.
event hardware_io_port_status(delta, port, irq, state)
tmp(0:1) = 2
tmp(1:1) = 60 * 32768 / delta
call attributes_write(xgatt_hr, 2, tmp(0:2))
end
dim u(10)
Buffers use an index notation with the following format:
BUFFER(< >:< >)
expression size
The < > is used as the index of the first byte in the buffer to be accessed and < > is used to
expression size
specify how many bytes are used starting from the location defined by < >. Note that this is
expression <size>
the end index position.not
u(0:1) = $a
u(1:2) = $123
The following syntax could be used with the same result due to little-endian byte ordering:
u(0:3) = $1230a
When using constant numbers to initialize a buffer, only (4) bytes may be set at a time. Longer buffers four
must be written in multiple parts or using a string literal (see section below).Strings
Silicon Labs Page of 11 55
u(0:4) = $32484746
u(4:1) = $33
Buffer index and size are optional and if left empty default values are used. Default value for index is 0 and
default value for size is maximum size of buffer.
Using Buffers with Expressions
Buffers can also be used in mathematical expressions, but only a maximum of (4) bytes are supported at a four
time since all numbers are treated as signed 32-bit integers in little-endian format. The following examples show
valid use of buffers in expressions.
a = u(0:4)
a = u(2:2) + 1
u(0:4) = b
u(2:1) = b + 1
The following example is :not valid
if u(0:5) = "FGH23" then
# do something
end if
This is because the mathematical equality operator ("=") interprets both sides as numerical values and in
BGScript numbers are always 4 bytes (32 bits). This means you can only compare (with '=') buffer segments
which are exactly four (4) bytes long. If you need to compare values which are not four (4) bytes in length you
must use the function, which is described later in this document.memcmp
if u(1:4) = "GH23" then
# do something
end if
4.2.6 Strings
Buffers can be initialized using literal string constants. Using this method more than four (4) bytes at a time may
be assigned.
u(0:5) = "FGH23"
Literal strings support C-style escape sequences, so the following example will do the same as the above:
u(0:5) = "\x46\x47\x48\x32\x33"
Using this method you can assign and subsequently compare longer values such as 128-bit custom UUIDs for
example when scanning or searching a GATT database for proprietary services or characteristics. However
keep in mind that the data must be presented in little-endian format, so the value assigned here as a string
literal should be the reverse of the 128-bit UUID entered into the UUID attributes if that is what you are gatt.xml
searching for.
4.2.7 Constant Strings
Constant strings must be defined before use. Maximum size of constant string depends on application and
stack usage. For standard BLE examples safe size is around 64 bytes.
Silicon Labs Page of 12 55
const str() = "test string"
And can be used in place of buffers. Note that in following example index and size of buffer is left as default
values.
call endpoint_send(11, str(:))
Note
Command "endpoint_send" is specific for Wi-Fi stack.
Silicon Labs Page of 13 55
4.3 Expressions
Expressions are given in infix notation.
x = (1+2) * (3+1)
The following are supported:mathematical operators
Operation Symbol
Addition: +
Subtraction: Multiplication: *
Division: /
Less than: <
Less than or equal: <=
Greater than: >
Greater than or equal: >=
Equals: =
Not equals: !=
Parentheses ()
Note
Currently there is no support for or operators.modulo power
The following are supported:bitwise operators
Operation Symbol
AND &
OR |
XOR ^
Shift left <<
Shift right >>
The following are supported:logical operators
Operation Symbol
AND &&
OR ||
Silicon Labs Page of 14 55
4.4 Commands
4.4.1 event <event_name> (<event_parameters>)
A code block defined between and keywords is event listener and will be run in response to a event end
specific event. BGscript allows implementing multiple listeners for a single event. This makes it easier and more
natural to implement helper libraries for specific tasks. Event listeners will be executed in the order in which they
appear in the script source. Execution will stop when reaching keyword of last event listener or end return
keyword in any event listener. BGScript VM (Virtual Machine) queues each event generated by the API and
executes them in FIFO order, atomically (one at a time and all the way through to completion or early
termination).
This example shows a basic system boot event handler for the Low Energy modules. The example
Bluetooth
will start Low Energy advertisements as soon as the module is powered on or reset:
Bluetooth
event system_boot(major, minor, patch, build, ll_version, protocol_version, hw)
call gap_set_mode(gap_general_discoverable, gap_undirected_connectable)
end
This example shows multiple event listeners in BGscript. Multiple listeners allow to import files without breaking
previous implementation. The example executes imported code if handle equals ota_data, otherwise executes
event code from custom.bgs file:
ota.bgs
event attributes_value(connection, reason, handle, offset, value_len, value_data)
if handle = ota_data then
# Do something
return # Return and prevent propagating event to next event listeners
end if
end
custom.bgs
import "ota.bgs"
event attributes_value(connection, reason, handle, offset, value_len, value_data)
# This is executed if handle != ota_data
end
4.4.2 if <expression> then [else] end if
Conditions can be tested with clause. Any commands between and will be executed if <if then end if
> is true (or non-zero).expression
if x < 2 then
x = 2
y = y + 1
end if
If is used and if the condition is success, then any commands between and will be executed. else then else
However if the condition fails then any commands between and will be executed.else end if
if x < 2 then
x = 2
y = y + 1
else
y = y - 1
end if
Silicon Labs Page of 15 55
Note! BGScript uses . This means that bitwise and operators have lower C language operator precedence & |
precedence than the comparison operator, and so comparisons are handled first if present in the same
expression. This is important to know when creating more complex conditional statements. It is a good idea to
include explicit parentheses around expressions which you need to be evaluated first.
if $0f & $f0 = $f0 then
# will match because ($f0 = $f0) is true, and then ($0f & true) is true
end if
if ($0f & $f0) = $f0 then
# will NOT match because ($0f & $f0) is $00, and $00 != $f0
end if
4.4.3 while <expression> end while
Loops can be made using . All commands on lines between and will be executed while <while while end while
> is true (or non-zero).expression
a = 0
while a < 10
# will loop 10 times
a = a + 1
end while
4.4.4 call <command name>(<command parameters>..)[(response parameters)]
The command is used to execute BGAPI commands and receive command responses. Command call
parameters can be given as expressions and response parameters are variable names where response values
will be stored. Response parentheses and parameters can be omitted if the response is not needed by your
application.
Note
Note that all response variables must be declared before use.
dim r
# write 2 bytes from tmp buffer index 0 to xgatt_hr attribute
# (response will be stored in variable "r")
call attributes_write(xgatt_hr, 2, tmp(0:2))(r)
If buffer or string is needed as parameter, then the buffer size is set in previous parameter.
event system_boot(major, minor, patch, build, ll_version, protocol_version, hw)
call endpoint_send(0,13,"Hello, world!")
end
The command can also be used to execute user-defined procedures (functions). The syntax in this case is call
similar to executing a BGAPI command, except return values are not supported.
4.4.5 let <variable> = <expression>
Optional command to assign an expression to a variable.
Silicon Labs Page of 16 55
let a = 1
let b = a + 2
4.4.6 return
This command returns from an event or a procedure.
event hardware_io_port_status(delta, port, irq, state) if state = 0 return #returns from event end if tmp(0:1) = 2 tmp(1:1) = 60 * 32768 / delta
call attributes_write(xgatt_hr, 2, tmp(0:2))
end
4.4.7 sfloat(mantissa, exponent)
This function changes given mantissa and exponent in to a 16bit IEEE-11073 SFLOAT value which has base-
10. Conversion is done using following algorithm:
Exponent Mantissa
Length
4 bits 12 bits
Type
2's-complement 2's-complement
Mathematically the number generated by () is calculated as . The return sfloat <mantissa> * 10^<exponent>
value is a 2-byte uint8 array in the SFLOAT format. Below are some example parameters, and their resulting
decimal sfloat values:
Mantissa Exponent Result (actual)
-105 -1 -10.5
100 0 100
320 3 320,000
Use the function as follows, assuming that is already defined as a 2-byte uint8s array (or bigger):sfloat() buf
buf(0:2) = sfloat(-105, -1)
The array will now contain the SFLOAT representation of . buf -10.5
Some reserved special purpose values:
NaN (not a number)
exponent 0
mantissa 0x007FF
NRes (not at this resolution)
exponent 0
mantissa 0x00800
Positive infinity
exponent 0
mantissa 0x007FE
Silicon Labs Page of 17 55
Negative infinity
exponent 0
mantissa 0x00802
Reserved for future use
exponent 0
mantissa 0x00801
4.4.8 float(mantissa, exponent)
Changes the given mantissa and exponent in to 32-bit IEEE-11073 FLOAT value which has base-10.
Conversion is done using the following algorithm:
Exponent Mantissa
Length
8 bits 24 bits
Type
signed integer signed integer
Some reserved special purpose values:
NaN (not a number)
exponent 0
mantissa 0x007FFFFF
NRes (not at this resolution)
exponent 0
mantissa 0x00800000
Positive infinity
exponent 0
mantissa 0x007FFFFE
Negative infinity
exponent 0
mantissa 0x00800002
Reserved for future use
exponent 0
mantissa 0x00800001
4.4.9 memcpy(destination, source, length)
The function copies bytes from the source buffer to destination buffer. Destination and source should memcpy
not overlap. Note that the buffer index notation only uses the byte index, and should not also include the start
portion, for example " " instead of " ".size dst(start) dst(start:size)
dim dst(3)
dim src(4)
memcpy(dst(0), src(1), 3)
4.4.10 memcmp(buffer1, buffer2, length)
The function compares and , for the length defined with . The function returns memcmp
buffer1 buffer2 length
1 if the data is identical.
dim x(3)
dim y(4)
if memcmp(x(0), y(1), 3) then
# do something
end if
Silicon Labs Page of 18 55
Loading...