Back

BluetoothLE

Please make sure you have a phone that supports Bluetooth Low Energy.

This plugin enables your device to communicate with Bluetooth Low Energy (Bluetooth Smart) devices, detect Bluetooth beacons such as Eddystone and iBeacons and measure their signal strength. It also allows bi-directional serial UART communications to devices that support that functionality.

In order to use BluetoothLE, you must first load the plugin at the top of your script using the LoadPlugin method like this:

app.LoadPlugin( "BluetoothLE" );

Then you create the BluetoothLE object like this:

ble = app.CreateBluetoothLE();

You can scan for BluetoothLE devices (including beacons) and get their signal strength using the following methods:

ble.StartScan();
ble.StopScan();

Example - Scan for devices

app.LoadPlugin( "BluetoothLE" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );

  txt = app.CreateText( "", 0.8, 0.6, "Log" );
  lay.AddChild( txt );

  btn = app.CreateToggle( "Scan", 0.4, 0.1 );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );

  app.AddLayout( lay );

  ble = app.CreateBluetoothLE();
  ble.SetOnDevice( OnDevice );

}

function btn_OnTouch( isChecked )
{
  if( isChecked ) ble.StartScan();
  else ble.StopScan();
}

function OnDevice( name, address, bonded, rssi, data )
{
  txt.Log( (name?name:data.type) + ": " + address + " -> " + rssi +" dBm" );
}

Copy Copy All Run

You can allow the user to select a device using the Select method and then connect to that device with the Connect method (if the device supports connections)

ble.Select();
ble.Connect();

Example - Connect to a device

app.LoadPlugin( "BluetoothLE" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );

  btn = app.CreateButton( "Connect", 0.4, 0.1 );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );

  app.AddLayout( lay );

  ble = app.CreateBluetoothLE();
  ble.SetOnSelect( OnSelect );
  ble.SetOnConnect( OnConnect );

}

function btn_OnTouch()
{
  ble.Select();
}

function OnSelect( name, address )
{
  ble.Connect( address );
}

function OnConnect()
{
  app.ShowPopup( "Connected!" );
}

Copy Copy All Run

If you know the service IDs and characterstic IDs of the device, then you can watch for changes in those characterstic values. The types supported are as follows: byte, char, float, double, short, int, long, hex, text, array.

Note: Some devices will need to be paired before characterstics can be read

Example - Watch a characterstic

app.LoadPlugin( "BluetoothLE" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );

  txt = app.CreateText( "", 0.9, 0.6, "Log" );
  lay.AddChild( txt );

  btn = app.CreateButton( "Connect", 0.4, 0.1 );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );

  app.AddLayout( lay );

  ble = app.CreateBluetoothLE();
  ble.SetOnSelect( OnSelect );
  ble.SetOnConnect( OnConnect );

}

function btn_OnTouch()
{
  ble.Select();
}

function OnSelect( name, address )
{
  ble.Connect( address );
}

function OnConnect()
{
  app.ShowPopup( "Connected!" );

  /*Watch for button A changes on a BBC micro:bit (with default firmware)*/
  var svcId = "e95d9882-251d-470a-a062-fa1922dfa9a8";
  var charId = "e95dda90-251d-470a-a062-fa1922dfa9a8";
  ble.WatchValue( svcId, charId, "byte", OnValue );
}

function OnValue( svcId, charId, val )
{
  txt.Log( charId + " -> " + val );
}

Copy Copy All Run

Many devices support UART serial communications, such as those based on Nordic's nRF5X series of bluetooth chips. This allows us to send and receive text or bytes of data to and from those devices once we have connected to them.

Once the BluetoothLE object is created, you can use the SetOnUartReceive function to set a callback function which will be called every time data is received from the remote device.

ble.SetOnUartReceive( callbackFunc );

If you want the received UART data to be automatically split into chunks and the callback fired only when a full chunk has been received, you can use the SetSplitMode function. This is useful if the device you are communicating with sends messages of a fixed length or certain start/end codes. Using SetSplitMode is also more efficient than processing each byte at a time.

ble.SetSplitMode( "Size", 2 );

ble.SetSplitMode( "End", 0xFC );

ble.SetSplitMode( "End", "FF" );

ble.SetSplitMode( "End", "." );

ble.SetSplitMode( "Start-End", 0xfa, 0xfc );

Adding the following line of code would cause the callack to be fired whenever a new line character is encountered

ble.SetSplitMode( "End", "\n" )

You can use the SetUartMode method to enable sending and receiving of data in various modes Text allows transmission of text characters Hex which allows you to use comma seperated hex codes or Int which allows sending of comma seperated integers.

ble.SetUartMode( "Hex" );

You can use the SetUartIds method to set custom GATT service and Charactaristic ids for use with the UART functionality. For example to use RedBear nRf8001 ids, you could do the following before connecting.

ble.SetUartIds(
  "713d0000-503e-4c75-ba94-3148f18d941e", //Svc
  "713d0003-503e-4c75-ba94-3148f18d941e", //Tx
  "713d0002-503e-4c75-ba94-3148f18d941e" //Rx
);

Note: If you use the keyword 'RedBear' in the options parameter of the Connect() method you don't actually need to use the SetUartIds method for RedBear nRf8001 devices, as those Ids are built-in.

Example - Send and receive serial data

app.LoadPlugin( "BluetoothLE" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );

  txt = app.CreateText( "", 0.9, 0.6, "Log" );
  lay.AddChild( txt );

  btn = app.CreateButton( "Connect", 0.4, 0.1 );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );

  app.AddLayout( lay );

  ble = app.CreateBluetoothLE();
  ble.SetOnSelect( OnSelect );
  ble.SetOnConnect( OnConnect );
  ble.SetOnUartReceive( OnUartReceive );

}

function btn_OnTouch()
{
  ble.Select();
}

function OnSelect( name, address )
{
  ble.Connect( address, "UART" );
}

function OnConnect()
{
  app.ShowPopup( "Connected!" );

  ble.SendUart( "hello" );
}

function OnUartReceive( data )
{
  txt.Log( data );
}

Copy Copy All Run