====== BBC micro:bit ======

//Taken from the official DroidScript documentation with some more texts and API documentation.//

=====Getting Started=====

//:!: Please make sure you have the Espruino firmware file installed on your micro:bit before trying to use this plugin. See [[http://www.microbit-js.org]] for more details.//

//:!: You have to install the plugin over the plugin section within DroidScript//

=====Using the BBC micro:bit Plugin=====

In order to use the micro:bit, you must first load the plugin at the top of your script using the **LoadPlugin** method like this:
<code javascript>app.LoadPlugin( "MicroBit" );</code>
Then you can create the microbit object like this:
<code javascript>microbit = app.CreateMicroBit();</code>
You will need to connect to your micro:bit using Bluetooth and you can scan for it like this:
<code javascript>microbit = microbit.Scan();</code>

===== MicroBit Methods =====
^ Method                                                                             ^ Description                                                               ^
| [[microbit_analogread|AnalogRead( pin )]]                                          |                                                                           |
| [[microbit_connect|Connect( address )]]                                            |                                                                           |
| [[microbit_createcontroller|CreateController( size )]]                             |                                                                           |
| [[microbit_disconnect|Disconnect()]]                                               | Disconnects the Bluetooth link between your phone and the BBC micro:bit.  |
| [[microbit_getimage|GetImage()]]                                                   | Returns full path to micro:bit top view image.                            |
| [[microbit_getversion|GetVersion( num, txt )]]                                     |                                                                           |
| [[microbit_oncancel|OnCancel()]]                                                   |                                                                           |
| [[microbit_onconnect|OnConnect()]]                                                 |                                                                           |
| [[microbit_ondevice|OnDevice( name, address, bonded, rssi )]]                      |                                                                           |
| [[microbit_ondisconnect|OnDisconnect()]]                                           |                                                                           |
| [[microbit_onreceive|OnReceive( data )]]                                           |                                                                           |
| [[microbit_onselect|OnSelect( title, body )]]                                      |                                                                           |
| [[microbit_reset|Reset()]]                                                         |                                                                           |
| [[microbit_save|Save()]]                                                           |                                                                           |
| [[microbit_scan|Scan( address )]]                                                  |                                                                           |
| [[microbit_scrolltext|ScrollText( text, interval )]]                               |                                                                           |
| [[microbit_send|Send( msg )]]                                                      |                                                                           |
| [[microbit_sendcode|SendCode( code )]]                                             |                                                                           |
| [[microbit_setleds|SetLEDs( bits )]]                                               |                                                                           |
| [[microbit_setonbutton|SetOnButton( callback )]]                                   |                                                                           |
| [[microbit_setonconnect|SetOnConnect( callback )]]                                 |                                                                           |
| [[microbit_setondevice|SetOnDevice( callback )]]                                   |                                                                           |
| [[microbit_setondisconnect|SetOnDisconnect( callback )]]                           |                                                                           |
| [[microbit_setonevent|SetOnEvent( callback )]]                                     |                                                                           |
| [[microbit_setonmotion|SetOnMotion( callback )]]                                   |                                                                           |
| [[microbit_setonreceive|SetOnReceive( callback )]]                                 |                                                                           |
| [[microbit_setontemp|SetOnTemp( callback )]]                                       |                                                                           |
| [[microbit_setsplitmode|SetSplitMode( mode, p1, p2 )]]                             |                                                                           |
| [[microbit_startscan|StartScan()]]                                                 |                                                                           |
| [[microbit_stopscan|StopScan()]]                                                   |                                                                           |
| [[microbit_watchaccelerometer|WatchAccelerometer( precision, interval, cancel )]]  |                                                                           |
| [[microbit_watchbutton|WatchButton( name, cancel )]]                               |                                                                           |
| [[microbit_watchinput|WatchInput( pin, cancel )]]                                  |                                                                           |


===== Using MicroBitCtrl Control =====

This control shows micro:bit image which shows interactive LED array and Bluetooth indicator.

In order to use the MicroBitCtrl control, you must first load the plugin and initialize MicroBit object:

<code javascript>
//Load the MicroBit plugin.
app.LoadPlugin( "MicroBit" );

//Called when application is started.
function OnStart()
{
  //Lock screen orientation to Portrait.
  app.SetOrientation( "Portrait" );

  //Create our main layout.
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );
  lay.SetBackColor( "#222222" );

  //Create the Microbit plugin.
  microbit = app.CreateMicroBit();

  //Create MicroBit controller.
  ctrl = microbit.CreateController( 0.9 );
  lay.AddChild( ctrl );

  //Create horizontal layout for buttons
  layButs = app.CreateLayout( "Linear", "Horizontal" );
  layButs.SetMargins( 0,0.05,0,0 );
  lay.AddChild( layButs );

  //Create a bluetooth connect button.
  btnConnect = app.CreateButton( "[fa-bluetooth-b]", 0.25, 0.15, "FontAwesome" );
  btnConnect.SetTextSize( 66 );
  btnConnect.SetTextColor( "#3366ff" );
  btnConnect.SetOnTouch( txtBT_OnTouchDown );
  layButs.AddChild( btnConnect );

  //Create clear button.
  btnClear= app.CreateButton( "[fa-times]", 0.25, 0.15, "FontAwesome" );
  btnClear.SetTextSize( 66 );
  btnClear.SetTextColor( "#ff4444" );
  btnClear.SetOnTouch( btnClear_OnClick );
  layButs.AddChild( btnClear );

  //Add main layout to the app.
  app.AddLayout( lay );
}

//Handle Bluetooth button press.
function txtBT_OnTouchDown()
{
  microbit.Scan();
}

//Handle 'clear' button press.
function btnClear_OnClick()
{
  ctrl.Clear();
}
</code>

===== MicroBitCtrl Methods =====
| [[microbitctrl_clear|Clear()]] | Clears LEDs to gray color. |
| [[microbitctrl_sendledstates|SendLEDStates()]] | Sends new LED states to micro:bit. |
| [[microbitctrl_setbluetoothstate|SetBluetoothState( connected )]] | If connected is true, then function sets Bluetooth indicator in blue color, if false, in gray color. |
| [[microbitctrl_setled|SetLED( x, y )]] | Sets LED in x and y position (range 0..4). It sets LED in red color. |
| [[microbitctrl_toggleled|ToggleLED( x, y )]] | Toggles LED in x and y position (range 0..4). It sets LED in red or gray color. |
| [[microbitctrl_imgtouch_ontouch|imgTouch_OnTouch( ev )]] | Custom LED array touch handler. |


=====Examples=====

====Send smiley face click to collapse contents ====
<code javascript>
app.LoadPlugin( "MicroBit" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );
  btn = app.CreateButton( "Smile" );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );
  app.AddLayout( lay );

  microbit = app.CreateMicroBit();
  microbit.Scan();
}

function btn_OnTouch()
{
  microbit.SetLEDs( "0111010001001000010010001" );
}
</code>

 
====Send scrolling texts====
<code javascript>
app.LoadPlugin( "MicroBit" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );
  btn = app.CreateButton( "Send" );
  btn.SetOnTouch( btn_OnTouch );
  lay.AddChild( btn );
  app.AddLayout( lay );

  microbit = app.CreateMicroBit();
  microbit.Scan();
}

function btn_OnTouch()
{
  microbit.ScrollText( "Hello", 150 );
}
</code>

If you want to receive messages from your micro:bit, then you will need to create a function to be called when new messages are available (a callback function). You can set the name of your function like this:
<code javascript>
 microbit.SetOnReceive( MyFunc );
</code>


====Detect button presses click to collapse contents====
<code javascript>
app.LoadPlugin( "MicroBit" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );
  txt = app.CreateText( "Press a button on your micro:bit" );
  lay.AddChild( txt );
  app.AddLayout( lay );

  microbit = app.CreateMicroBit();
  microbit.SetOnConnect( OnConnect );
  microbit.Scan();
}

function OnConnect()
{
  microbit.SetOnButton( OnButton );
}

function OnButton( name, state )
{
  txt.SetText( name + " : " + state );
}
</code>


====Detect movement click to collapse contents====
<code javascript>
app.LoadPlugin( "MicroBit" );

function OnStart()
{
  lay = app.CreateLayout( "Linear", "VCenter,FillXY" );
  txt = app.CreateText( "Move your micro:bit" );
  lay.AddChild( txt );
  app.AddLayout( lay );

  microbit = app.CreateMicroBit();
  microbit.SetOnConnect( OnConnect );
  microbit.Scan();
}

function OnConnect()
{
  microbit.SetOnMotion( OnMotion );
}

function OnMotion( x, y, z )
{
  txt.SetText( x + "," + y + "," + z );
}
</code>
You can also send programs to the micro:bit and have them run every time the micro:bit is powered up using the following methods (Advanced).
<code javascript>
 microbit.SendCode( code );
 microbit.Save();
</code>
See http://www.espruino.com/MicroBit for more code samples that can be run directly on the micro:bit
bit

====Save code on the micro:bit click to collapse contents====
<code javascript>
app.LoadPlugin( "MicroBit" );

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

  var code = "var text = 'Fred Blogs';\n" + 
  "g = Graphics.createArrayBuffer(5,5,1);\n" +
  "g.flip = function(){show(this.buffer);};\n" +
  "var x = 0;\n" +
  "\n" + 
  "function draw()\n" +
  "{\n" +
  "if( x++ > text.length*5 ) x=0;\n" +
  "g.clear();\n" +
  "g.drawString( text, 5-x);\n" +
  "g.flip();\n" +
  "}\n" +
  "\n" + 
  "setInterval(draw,150);\n";

  txt = app.CreateTextEdit( code, 0.9, 0.7, "MultiLine" );
  lay.AddChild( txt );
  app.AddLayout( lay );

  btnSave = app.CreateButton( "Save", 0.3, 0.1 );
  btnSave.SetOnTouch( btnSave_OnTouch );
  lay.AddChild( btnSave );

  btnReset = app.CreateButton( "Reset", 0.3, 0.1 );
  btnReset.SetOnTouch( btnReset_OnTouch );
  lay.AddChild( btnReset );

  microbit = app.CreateMicroBit();
  microbit.Scan();
}

function btnSave_OnTouch()
{
  microbit.SendCode( txt.GetText() );
  microbit.Save();
}

function btnReset_OnTouch()
{
  microbit.Reset();
}
</code>

===== Troubleshooting =====
There is a separate article on [[microbit:troubleshooting|Troubleshooting]] this plugin.