Skip to main content

bluetooth.open(uart, firmware, options)

Initializes the imp’s Bluetooth sub-system and readies it for use

Availability

Device
Only available on the imp004m (impOS 38+) and imp006 (impOS 42+)

Parameters

Name Type Description
uart An imp UART object The imp UART bus connected to the module’s Bluetooth sub-system imp004m only
firmware String or blob The Broadcom-proprietary firmware for the Bluetooth sub-system imp004m only
options Table Optional overrides imp004m only

Returns

A new bluetooth instance

Description

This method initializes a compatible imp’s Bluetooth sub-system and opens it for use. It returns an instance of the bluetooth class for you to use, so make sure you don’t allow the instance to go out of scope if you don’t want it to be automatically closed.

The behavior of the call depends on which imp you are using.

imp006

The imp006’s Cypress CYW43455 chip is connected on a dedicated UART which is not exposed via Squirrel and consequently not configurable by your application. In addition, the imp006’s modem firmware is supplied and loaded by impOS. The MAC address cannot be changed. Therefore hardware.bluetooth.open() on the imp006 takes no arguments, as you can see from the example code, below. If you provide arguments, an exception will be thrown.

Note This behavior supersedes that offered on the imp006 by impOS 41.23 and under.

Example imp006 Code

// Set up BT on imp006 Breakout Board
bt <- null;

local start = hardware.millis();

try {
    // Instantiate BT
    bt = hardware.bluetooth.open();
    server.log("BLE initialized after " + (hardware.millis() - start) + " ms");
} catch (err) {
    server.error(err);
    server.log("BLE failed after " + (hardware.millis() - start) + " ms");
}

imp004m

The uart parameter takes the imp UART bus which you have connected to the Bluetooth component of the imp004m’s integrated Cypress CYW43438 communications chip. It will be taken over and configured by impOS and should not be used for other tasks while you have the bluetooth instance open — ie. until you call the bluetooth.close() method on the instance returned by this call.

Note It is possible to set the size of the selected imp004m UART’s receive buffer by calling uart.setrxfifosize() before you call bluetooth.open(). A minimum receive buffer size of 1KB is imposed, so any buffer size smaller than this will be increased to 1KB by bluetooth.open(), but sizes greater than 1KB will be respected. If you do not call uart.setrxfifosize(), bluetooth.open() will set the receive buffer size to 1KB.

For the imp004m, you must pass in Cypress-proprietary radio firmware. This is then loaded into the CYW43438/43455, which is restarted. The firmware is approximately 16KB in size, and you can choose to include it as a string in your application code, or as binary data stored on and read in from SPI flash. Indeed, you should note that a future implementation of this API will replace this parameter with a reference to a function in your application that will stream the firmware in from flash.

The required Bluetooth LE firmware is available as a Squirrel library which you can include in your code. The imp004m example code, below, shows how this is done.

Note You will need to include the firmware in any subsequent bluetooth.open() call you make on an imp004m, for example after an earlier call to bluetooth.close().

The final parameter, options, allows you to override certain connection settings if you wish. To make changes, pass a table into options containing any of the following keys:

options Key Data Type Description
mac String An alternative MAC address. It must be provided as a 12-character lower-case hexadecimal string
baudrate Integer The preferred baud rate to use for HCI traffic once bluetooth has booted

Example imp004m Code

#require "bt_firmware.lib.nut:1.0.0"

// Set up BT on imp004m Breakout Board
bt <- null;
bt_uart <- hardware.uartFGJH;
bt_lpo_in <- hardware.pinE;
bt_reg_on <- hardware.pinJ;

// Boot up BT
bt_lpo_in.configure(DIGITAL_OUT, 0);
bt_reg_on.configure(DIGITAL_OUT, 1);

// Pregnant pause while BT boots...
imp.sleep(0.05);

local start = hardware.millis();

try {
    // Instantiate BT
    bt = hardware.bluetooth.open(bt_uart, 
                                 BT_FIRMWARE.CYW_43438, 
                                 {"mac": "76bdac7f672a"});
    server.log("BLE initialized after " + (hardware.millis() - start) + " ms");
} catch (err) {
    server.error(err);
    server.log("BLE failed after " + (hardware.millis() - start) + " ms");
}