Block for inclusion of Bluetooth UART service needed

It would be great if there was a tray containing Bluetooth related blocks.

In this tray, there should/could be a block per Bluetooth "service".

Dragging a Bluetooth service block into a PXT app would result in the corresponding Bluetooth being included in the generated code.

This issue requests a block for the micro:bit Bluetooth UART service.

Note that the UART service is a little more complicated than the other services which generally only require a single line of code for them to be included in a build. The UART service needs to be instantiated in the same way but also needs user code for either the production of data to transmit to a connected client and / or user code to receive and process data received from a connected client. At least one of these is required for use of this service to make sense.

It would generally make sense to implement producer/consumer code with reference to the state of the Bluetooth connection, for which events are available. i.e. there's no sense trying to transmit data over UART if you're not in a connection.

Note also that when creating an instance of the UART service, a buffer size must be supplied for the underlying serial data buffer.

The Lancaster University documentation covers this well: http://lancaster-university.github.io/microbit-docs/ble/uart-service/

I've repeated an example application here to show what the possible structure of an application which creates the UART service and then both receives data from it and transmits data using it might look like.

#include "MicroBit.h"
#include "MicroBitSamples.h"
#include "MicroBitUARTService.h"
MicroBit uBit;
MicroBitUARTService *uart;

int connected = 0;

void onConnected(MicroBitEvent e)
{
    uBit.display.scroll("C");

    connected = 1;

    // my client will send ASCII strings terminated with the colon character
    ManagedString eom(":");

    while(1) {
        ManagedString msg = uart->readUntil(eom);
        uBit.display.scroll(msg);
    }

}

void onDisconnected(MicroBitEvent e)
{
    uBit.display.scroll("D");
    connected = 0;
}

void onButtonA(MicroBitEvent e)
{
    if (connected == 0) {
        uBit.display.scroll("NC");
        return;
    }
    uart->send("YES");
    uBit.display.scroll("YES");
}

void onButtonB(MicroBitEvent e)
{
    if (connected == 0) {
        uBit.display.scroll("NC");
        return;
    }
    uart->send("NO");
    uBit.display.scroll("NO");
}

void onButtonAB(MicroBitEvent e)
{
    if (connected == 0) {
        uBit.display.scroll("NC");
        return;
    }
    uart->send("GOT IT!!");
    uBit.display.scroll("GOT IT!!");
}

int main()
{
    // Initialise the micro:bit runtime.
    uBit.init();

    // listen for Bluetooth connection state changes
    uBit.messageBus.listen(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_CONNECTED, onConnected);
    uBit.messageBus.listen(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_DISCONNECTED, onDisconnected);

    // listen for user button interactions
    uBit.messageBus.listen(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, onButtonA);
    uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonB);
    uBit.messageBus.listen(MICROBIT_ID_BUTTON_AB, MICROBIT_BUTTON_EVT_CLICK, onButtonAB);

    uart = new MicroBitUARTService(*uBit.ble, 32, 32); 
    uBit.display.scroll("AVM");

    release_fiber();
}

Note that inclusion of Bluetooth services has consequences for memory configuration on the micro:bit, specifically with respect to GATT table size. I've suggested an approach to addressing this to Joe Finney of Lancaster University and we're evaluating. Will update issue once this discussion has progressed further.

[pelikhan]

What are the config.json changes required for this feature?

Just those required for any other service i.e.

            "enabled": 1,
            "pairing_mode": 1,
            "private_addressing": 0,
            "open": 0,
            "whitelist": 1,
            "advertising_timeout": 0,
            "tx_power": 0
        },

...possibly with

            "dfu_service": 1,
            "event_service": 1,
            "device_info_service": 1

if those services have also been selected.

Is the MicroBitUARTService class available to PXT? It's relatively new so maybe not. I get compilation errors if I include this code in Bluetooth.cpp

    /**
    *  Starts the Bluetooth UART service
    * @param rx_buffer buffer into which data received from the remote device will be received
    * @param tx_buffer buffer into which data to be sent to the remote device will be written    
    */
    //% help=bluetooth/start-uart-service
    //% blockId=bluetooth_start_uart_service block="bluetooth uart service" blockGap=8
    void startUartService(int rx_buffer, int tx_buffer) {
        new MicroBitUARTService(*uBit.ble,rx_buffer, tx_buffer);       
    }

in 'void bluetooth::startUartService(int, int)':\n/home/build/prj2/source/microbit-bluetooth/bluetooth.cpp:69:13: error: expected type-specifier before 'MicroBitUARTService'\n         new MicroBitUARTS
ervice(*uBit.ble,rx_buffer, tx_buffer);       \n             ^\nninja: build stopped: subcommand failed.\n"

In addition to the compilation error reported above, I would be grateful for some help in formulating this block such that it is declared outside of the main method and instantiated inside it so that there's a variable which can be used from within other blocks in much the same way as the serial block is used.

So the block would be defined something like......

    void startUartService(int rx_buffer, int tx_buffer) {
        new MicroBitUARTService(*uBit.ble,rx_buffer, tx_buffer);       
    }
'''

So in C++ we'd have something like...

#include "MicroBitUARTService.h"
MicroBitUARTService *uart;
.......

int main()
{
// Initialise the micro:bit runtime.
uBit.init();

uart = new MicroBitUARTService(*uBit.ble, 32, 32); 

....
}

Thanks

I have added a block for the UART service and a block for writing to it. All good. But I'm finding it difficult to create a block for reading from the UART service buffer until a specified delimiter character is encountered.

What I want is a parameter which accepts a single character. This seems to not be possible which has led me down the path of using an enum, translated into a set of corresponding character values via a function.

What I have now "works" but produces a uartRead block which has a string parameter of unlimited length:

using namespace pxt;

enum Delimiters {
    //% block="new line"
    NewLine = 1,
    //% block=","
    Comma = 2,
    //% block="$"
    Dollar = 3,
    //% block=":"
    Colon = 4,
    //% block="."
    Fullstop = 5,
    //% block="#"
    Hash = 6,
};


/**
 * Support for additional Bluetooth services.
 */
//% color=#0082FB weight=20
namespace bluetooth {

    /**
    *  Starts the Bluetooth UART service
    */
    //% help=bluetooth/start-uart-service
    //% blockId=bluetooth_start_uart_service block="bluetooth uart service" blockGap=8

    void startUartService() {
        // 61 octet buffer size is 3 x (MTU - 3) + 1
        // MTU on nRF51822 is 23 octets. 3 are used by Attribute Protocol header data leaving 20 octets for payload
        // So we allow a RX buffer that can contain 3 x max length messages plus one octet for a terminator character
        uart = new MicroBitUARTService(*uBit.ble, 61, 60);
    }

    /**
    *  Writes to the Bluetooth UART service buffer. From there the data is transmitted over Bluetooth to a connected device.
    */
    //% help=bluetooth/uart-write
    //% blockId=bluetooth_uart_write block="bluetooth uart write %data" blockGap=8
    void uartWrite(StringData *data) {
            uart->send(ManagedString(data));
    }    

    /**
    *  Reads from the Bluetooth UART service buffer, returning its contents when the specified delimiter character is encountered.
    */
    //% help=bluetooth/uart-read
    //% blockId=bluetooth_uart_read block="bluetooth uart read %del" blockGap=8
    StringData* uartRead(StringData *del) {
        return uart->readUntil(ManagedString(del)).leakData();
    }    

To try using the enum/function mapping approach I created file bluetooth.ts which now contains:

//% blockId="delimiter_conv" block="%del"
export function delimiters(del : Delimiters) : string {
    switch(del) {
        case Delimiters.NewLine: return "\n";
        case Delimiters.Comma: return ",";
        case Delimiters.Dollar: return "$";
        case Delimiters.Colon: return ":";
        case Delimiters.Fullstop: return ".";
        case Delimiters.Hash: return "#";
        default: return "\n";
    }
}

and changed my bluetooth..cpp function to look like this:

    /**
    *  Reads from the Bluetooth UART service buffer, returning its contents when the specified delimiter character is encountered.
    */
    //% help=bluetooth/uart-read
    //% blockId=bluetooth_uart_read block="bluetooth uart read %del=delimiter_conv" blockGap=8
    StringData* uartRead(StringData *del) {
        return uart->readUntil(ManagedString(del)).leakData();
    }    

This essentially breaks the whole bluetooth category. If I click on the category I get a single block appear:

There's clearly something I don't understand about this.

Without the use of an enum and function, what I have works pretty well and the only issue is that I am unable to restrict the parameter to uartRead to being a single character. Is this possible?

The following blocks generated code works a treat with my Animal Vegetable Mineral guessing game:

let uart_data: string = "";
let connected = 0;
basic.showString("UART");
bluetooth.startUartService();
bluetooth.onBluetoothConnected(() => {
    basic.showString("C");
    connected = 1;
    while (connected == 1) {
        uart_data = bluetooth.uartRead(":");
        basic.showString(uart_data);
    }
});
bluetooth.onBluetoothDisconnected(() => {
    basic.showString("D");
});
input.onButtonPressed(Button.A, () => {
    if (connected == 1) {
        bluetooth.uartWrite("HELLO");
    }
});
input.onButtonPressed(Button.B, () => {
    if (connected == 1) {
        bluetooth.uartWrite("GOODBYE");
    }
});

[pelikhan]

Done.

[lock]

This thread has been automatically locked since there has not been
any recent activity after it was closed. Please open a new issue for
related bugs.