BT900 Series Bluetooth Module

Changing the advertised device name is accomplished using three different functions prior to calling the BleAdvertStart () function.

First, the BleGapSvcInit () function is used to change the device name from the default, Laird [BL600 | BT900], to the desired device name.
Next, the BleAdvRptInit () funtion must be called to create and initialize the advert report with the new device name.
Finally, the BleAdvRptsCommit () function must be called to commit the changes.

Below is an example of a simplified smartBASIC app which changes the default device name to "My Device":
 

//******************************************************************************
// Laird Connectivity
// Rikki Horrigan
//******************************************************************************

//******************************************************************************
//Definitions
//******************************************************************************

//******************************************************************************
//Global Variable Definitions
//******************************************************************************
dim rc     //result code
dim nameWritable
dim nAppearance
dim nMinConnInterval
dim nMaxConnInterval
dim nSupervisionTout
dim nSlaveLatency

//******************************************************************************
// Initialize Global Variable
//******************************************************************************
nameWritable = 0 //The device name will not be writable by peer.
nAppearance = 1091 //Device will apear as Walking sensor on hip (org.bluetooth.characteristic.gap.appearance.)
nMinConnInterval = 500000 // must be smaller than nMaxConnInterval.
nMaxConnInterval = 1000000 //must be larger than nMinConnInterval
nSupervisionTout = 4000000 //Range is between 100000 to 32000000 microseconds (rounded to the nearest 10000 microseconds)
nSlaveLatency = 0 //value must be smaller than (nSupervisionTimeout/nMaxConnInterval)-1

//******************************************************************************
//Functions & Subroutines
//******************************************************************************

//ERROR HANDLER
SUB assertRC(rc, line)
  IF rc != 0 THEN
    PRINT "\nError on line ";line;", code: ";INTEGER.H'rc
  ENDIF
ENDSUB

// Change Device Name

FUNCTION OnStartup()
print "Default Device Name: "; BleGetDeviceName$ ();"\n"
dim deviceName$ //declare variable for DEVICENAME
deviceName$= "My Device" //Set new DEVICENAME
rc = BleGapSvcInit (deviceName$, nameWritable, nAppearance, nMinConnInterval, nMaxConnInterval, nSupervisionTout, nSlaveLatency )
print "\n New Device Name: "; BleGetDeviceName$ (); "\n"

//Create and Initializing the Advert Report (not advertised until BLEADVRPTSCOMMIT is called)
dim adRpt$ //advert report
adRpt$ = ""
rc = BleAdvRptInit(adRpt$, 2, 0, 16)

//Commit the advert report
dim scRpt$ //scan report
scRpt$ = ""
rc = BleAdvRptsCommit(adRpt$,scRpt$)

//Start Advertising
dim addr$
addr$ = ""
rc = BleAdvertStart(0,addr$,100,0,0)

ENDFUNC 1 // Remain in WAITEVENT
//******************************************************************************
//Handler Definitions
//******************************************************************************

//******************************************************************************
//OnEvent Statements
//******************************************************************************

//******************************************************************************
//Equivalent to Main() in C
//******************************************************************************
rc = OnStartup()

Waitevent

If you are having issues using the Online Xcompilers it could be related to security settings in your system which may be blocking access to the Online Xcompilers. If you are not able to resolve this it is possible to Xcompile locally by following the steps below:

1. Disable (uncheck) the Online XCompilers on the Config Tab in UwTerminalX as shown below:
2. Locate the Xcomp_mmmmm_xxxx_xxxx.exe file in the firmware zip folder (downloaded from module's Product Page) for the version of firmware loaded to the module.
   Note: the Xcomp version MUST match the firmware version loaded to the module or the application will not compile.
   mmmmm = module
   xxxx_xxxx =Xcomp version
3. Copy or Move the Xcomp_mmmmm_xxxx_xxxx.exe to the same folder the smartBASIC application is stored in as shown below:

You should now be able to Xcompile the application using UwTerminalX by right-clicking in the terminal and selecting one of the Xcompile options :

• Xcompile
• Xcompile+Load
• Xcompile+Load+Run

Select the application from the folder where the Xcomp file is located. UwTerminalX will now look for the local Xcompiler in the application folder.

It is because the “pairing mode” has not been enabled in the smartBASIC application. Please search for “PAIRABLE_ON_STARTUP”, and modify the value to 1 in the sample smartBASIC application.

In general, cleaning the populated modules is strongly discouraged. Residuals under the module cannot be easily removed with any cleaning process. 

• Cleaning with water can lead to capillary effects where water is absorbed into the gap between the host board and the module. The combination of soldering flux residuals and encapsulated water could lead to short circuits between neighboring pads. Water could also damage any stickers or labels.
• Cleaning with alcohol or a similar organic solvent will likely flood soldering flux residuals into the RF shield, which is not accessible for post-washing inspection. The solvent could also damage any stickers or labels.
• Ultrasonic cleaning could damage the module permanently.

However, if water washing is required you will need to use deionized water. We do not recommend chemical cleaning and cannot guarantee it will not damage the modules. If you MUST clean PCB with chemicals it is recommended that you test on one board and then confirm the module still works after the process, prior to adding it to production, while understanding the above affects washing the populated PCBs can have on the module.

Our Bluetooth 5.0 smartBASIC modules (BL652, BL653, BL654) have the capability of supporting LE Secure Connections Pairing as well as encryption. LE Secure Connection is an enhanced security feature introduced in Bluetooth v4.2. It uses a Federal Information Processing Standards (FIPS) compliant algorithm called Elliptic Curve Diffie Hellman (ECDH) for key generation. 
 
LE Secure Connections, supports four association models: 

• Just Works
• Numeric Comparison (Only for LE Secure Connections)
• Passkey Entry
• Out of Band (OOB)

Additional information about LE Secure Connections and the models can be found here: www.bluetooth.com.
 

Our Bluetooth 4.0 smartBASIC modules (BT900 /BL600 /BL620) support Simple Secure Pairing and Encryption 
Additional information about Simple Secure Pairing can be found here:
lairdconnect.com/resources/newsroom/secure-ble-pairing-iot
lairdconnect.com/resources/white-papers/ble-and-lairds-bl6x0-series-bt900-modules-guide-security-and-privacy
 
We recommend reviewing the Pairing, Bonding and Security Manager functions in the BL6xx/BT900 smartBASIC Extensions User Guides. The full security of the Bluetooth/Bluetooth Low Energy connection will depend largely on how the smartBASIC application is written, and what the input/output capabilities are of the devices that are connecting. If either device will not have any input/output capabilities then pairing will have to default to Just Works, which is the least secure pairing method. However there are additional layers of security that can be added to increase protection from hacking when the Just Works pairing model is used.

With Bluetooth Low Energy, to further secure the connection, it is recommended that the metadata for the characteristic attributes are configured for Encryption with man-in-the-middle protection for characteristic value access. This will prevent anyone from accessing data on the module without proper encryption keys. (See BleAttrMetadataEx in the BL6xx/BT900 smartBASIC Extensions User Guides.) Additionally, when using Just Works pairing, or any time additional security is required, we recommend adding a challenge/response question to the application layer, with a timer, which expects the connecting device to respond to the challenge question in a specified period of time after a connection has occurred. If the correct response is not received within that time period the application would force a disconnection. Finally, whisper mode pairing can be used during the pairing process as an additional layer of security. This is accomplished by reducing the Tx power while pairing using BleTxPwrWhilePairing as per the BL6xx/BT900 smartBASIC Extensions User Guide, which will reduce the radius which a hacker would need to breach in order to capture or spoof the encryption procedure.

smartBASIC is a programming language developed for our BT900 and BL6xx modules to simplify the code required for programming them. It is not used for developing Android or iOS device applications. BLE applications for Android and iOS devices would need to written in code specific to the Android or iOS platform.

Our, Laird Toolkit Application available for iOS and Android is currently in the process of being updated for Android and iOS to work with newer OS platforms.
Once it is complete we expect to make the source code available, to customers working with our smartBASIC modules, for reference when developing Apps for these platforms.
As of the writing of this FAQ the current version of the Laird Toolkit is still available on the App store for iOS and Google Play for Android, however, it may not work with newer versions of iOS or Android until the updates have been made.
Google Play Store
Apple Store

An alternate resource, the Nordic nRF Toolbox is also available from the iOS App Store and Google Play. The source code for this application is available from Nordic's Website.
nRf Toolbox
Android
iOS

Bluetooth Low Energy uses Services as opposed to the set of standardized profiles that exists for Classic Bluetooth. While some Bluetooth Low Energy services have been standardized by the Bluetooth SIG, the development of custom services is allowed to meet custom application requirements.
 
Because Bluetooth Low Energy uses a completely different protocol than Classic Bluetooth and supports custom services, Bluetooth Low Energy devices cannot connect to a computer through the typical Bluetooth configuration of a computer. Therefore, connecting to a PC requires writing and running a Bluetooth Low Energy Central Role/Client application to collect the data sent from the Bluetooth Low Energy peripheral modules. Application development for PCs and Mobile devices is outside the scope of our support. Alternatively, a BL654 USB dongle could be used as a BLE Central Role device, to collect the BLE data and pass it to the PC over a COM Port. However, you would still need an application to view and process the data received over that COM Port.
 
We generally recommend customers who are new to Bluetooth Low Energy obtain a copy of Getting Started with Bluetooth Low Energy to help them understand the Bluetooth Low Energy protocol and the GATT table. There are also many resources available online which explain this. 

When Bluetooth Low Energy was first introduced and we launched our BL6xx product line (predecessors to the BL65x series) we produced the BL600 and BL620 smartBASIC Application Walkthrough document, which provides an overview of how Bluetooth Low Energy works and how a GATT table is constructed. 

The Master is the device that initiates the connection as per the classic BT inquiry and paging process. There is no option to configure Master/Slave roles in smartBASIC. However, if the BT900 initiates the connection using the BtcSppConnect(BTA$) command then it can be assumed that it has taken the Master role. The BT900 will have performed the inquiry/page, and the remote device will have performed the inquiry/page scan.

By adjusting the FrameSize and Receive Credit in  BTCSPPSETPARAMS API, the throughput will be improved, Detail application note: Application Note - BT900 SPP Throughput Analysis.pdf