The IG60-BL654 Laird Linux gateway includes an embedded BL654 module (BL654IG) as a Bluetooth low-energy (BLE) subsystem and comes preloaded with our own smartBASIC firmware.

Unlike the regular BL654 module on our DVK or the BL654 USB dongle, there is no direct connection from the outside to the BL654IG module’s UART interface available. Hence, tools like UwTerminalX cannot be used for downloading smartBASIC applications and communicating in interactive mode.

However, the BL654 UART is mapped to a native Linux serial interface (/dev/ttyS2), and we provide a set of command line utilities preloaded into the IG60-BL654 Laird Linux image which help load smartBASIC applications and upgrade smartBASIC firmware.

Compiling a smartBASIC App for the BL654IG

As mentioned above, it’s not possible to use the regular UwTerminalX tool with the BL654IG, since it does not support compilation for the BL654IG’s smartBASIC firmware build. However, we offer an online smartBASIC XCompiler available at http://uwterminalx.no-ip.org/. You can simply select the BL654IG as the target, select the corresponding firmware version, and select the smartBASIC application source file and the online compiler will compile and download the compiled .uwc file.

Please note that the online XCompiler can only utilize one single source file and cannot make use of #include statements to incorporate other source files into a main one. To accomodate this use case, we offer an sB_file_includer utility available at https://github.com/LairdCP/sB_file_includer/releases.

There also exists an Online XCompiler Tool as stand-alone Windows/Linux application. It’s a frontend for the online XCompiler with the identical device and firmware selections, but is capable of handling multiple source files with #include statements properly. It’s available at https://github.com/laird-connectivity-playground/Online-XCompiler-Tool. Precompiled binaries are available at https://github.com/laird-connectivity-playground/Online-XCompiler-Tool/releases.

Loading a Pre-Compiled smartBASIC App

A compiled smartBASIC app in .uwc format to the BL654-IG60 can be performed with the btpa_utility as follows:

btpa_utility <port> <baudrate> <command>

where the default port is: /dev/ttyS2 and default baudrate is: 115200

The compiled version of the sB app (.uwc) needs to be present in the file system of the IG60. This can be transferred by a USB memory stick or SCP’ing it over ethernet/wifi.

The btpa_utility supports the following set of commands: upload, list, delete, rename and cmd

Below are usage examples:

Usage Examples

Without commands, running btpa_utility.pi will show a usage message:

# btpa_utility.py
usage: btpa_utility <port> <baudrate> <command>
#

“List” command will show a list of file on the flash file system:

# btpa_utility.py /dev/ttyS2 115200 list
oldname (or other filename(s) loaded)
#

“Rename” command can rename a file:

# btpa_utility.py /dev/ttyS2 115200 rename oldname newname
# btpa_utility.py /dev/ttyS2 115200 list
newname
#

“Delete” will delete a file from file system:

# btpa_utility.py /dev/ttyS2 115200 delete newname
# btpa_utility.py /dev/ttyS2 115200 list
#

“Upload” will load a compiled smartBASIC application (.uwc) into the BL654IG:

# btpa_utility.py /dev/ttyS2 115200 upload myniceapp myniceapp.uwc
# btpa_utility.py /dev/ttyS2 115200 list
myniceapp
#

If the uploaded application should start automatically (which likely is the case on IG60), make sure to name the application $autostart$ on the BL654IG flash filesystem. On the Linux shell there is an issue with the $ character in filenames: Anything starting with $ is treated as an environment variable e.g., echo $PATH will not echo “$PATH” but would show the content of the PATH environment variable. So $autorun will show the contents of the variable “autorun” which is most likely not set. You must either escape the dollar signs, i.e \$autorun\$, or put the whole filename into single quotes. Below is an example of loading the AT Interface smartBASIC app properly:

# btpa_utility.py /dev/ttyS2 115200 upload \$autorun\$ ./$autorun$.AT.interface.BL654.single._.uwc
# btpa_utility.py /dev/ttyS2 115200 list
$autorun$
#

To talk to the BL654 UART when in smartBASIC interactive mode, or to later test the smartBASIC application, the simple terminal application “microcom” can be used (also preloaded):

# microcom -s 115200 /dev/ttyS2

However, this is somewhat of a “blind flight” as there is no local echo of the commands coming from microcom. It is absolutely minimalistic. Alternatively, other terminal programs could be installed on the IG60, such as “minicom”.

If uploading a new smartBASIC application it’s best to format the BL654 flash memory by AT&F* command through microcom in advance. See the general BL654 smartBASIC documentation:

smartBASIC Core Functionality User Guides (on BL654 page)
smartBASIC BL654 Extensions User Guides (firmware-specific, on BL654 page)

Note: For the purposes of smartBASIC documentation, the BL654IG module firmware most closely corresponds to the BL654 module firmware v29.5.7.2.

Exiting an $autorun$ smartBASIC Application

There exist pre-defined GPIOs in the IG60 to control the BL654 module, which can be found under /sys/devices/platform/gpio:

bt_nautorun: If set to 0 (low) autorun is active and and $autorun$ application will start after power up/reset and if set to 1 (high) autorun will be disabled.
card_nreset: Setting to 0 (low) asserts BL654 reset and 1 (high) releases reset.

To exit an $autorun$ application, set nAUTORUN and perform a module reset.

echo 1 > /sys/devices/platform/gpio/bt_nautorun/value (disables autorun)
echo 0 > /sys/devices/platform/gpio/card_nreset/value (assert reset)
echo 1 > /sys/devices/platform/gpio/card_nreset/value (release reset)
echo 0 > /sys/devices/platform/gpio/bt_nautorun/value (re-enable autorun)

You should now be able to connect to the BL654, e.g. via microcom, with access to the smartBASIC interactive mode:

microcom -s 115200 /dev/ttyS2

You can now use AT&F* to clear the flash file system before loading a new smartBASIC app to the module with the above Python script. (Note: CTRL-X will exit microcom).

Note: You can always check the current state of the above GPIOs with

cat /sys/devices/platform/gpio/.../value

Updating the smartBASIC Firmware

There exists a special smartBASIC firmware build for the BL654 in the IG60, hence you cannot load a regular BL654 firmware into it. This BL654IG smartBASIC firmware is available only on request. If needed, please contact Laird Connectivity technical support at support@lairdconnect.com for further advice. The BL654IG firmware most closely corresponds to the BL654 module firmware v29.5.7.2.

A second command line tool is preloaded on the Linux image to perform a firmware update:

btpa_firmware_loader <port> <baudrate> <path to UWF file> [device type]

The device type is optional and can be omitted.

Please note that the BL654IG must be set into smartBASIC interactive mode prior to updating the firmware, i.e. an eventually running $autorun$ application has to be exited (see above section).