Anything cross-platform would start with Unix port (well, Linux for things not mandated by POSIX), that's the way to implement API covering the widest array of diverse systems.

That's harder than you might think. The semantics of BlueZ are quite different from the semantics of all the BLE implementations for MCUs I've looked at, and requires unfortunate things like linking against dbus/glib and a separate thread to interact with dbus. Also, last time I looked BlueZ support for peripheral mode was still very immature.

One example of the differences is that BLE stacks for MCUs allow you to construct a raw advertisement packet. BlueZ simply doesn't allow this, which makes the implementation much harder.

In theory, you could also work directly with the hci socket on Linux, but that requires root access and does not work when you have BlueZ running at the same time (most modern Linux laptops with Bluetooth).

EDIT:

I think it is much easier to say "this module works on microcontrollers" and then implement support for multiple BLE stacks to make sure you're getting the cross-platform part right. This is why I've done the esp32 and nrf support at the same time. A NimBLE port would also be nice, and much easier than BlueZ.

Forget about BlueZ, it's crappy bloatware.

In theory, you could also work directly with the hci socket on Linux

There're also L2CAP sockets which shouldn't have root requirements, etc. Yep, probably can't do advertizement using them, but advertizement to Bluetooth is the same as e.g. BGP to Internet protocols. What's important is not advertizement and other "control plane" stuff, but data communication API.

Don't confuse classic BT and BLE. The main thing that connects them is their name, and little else. Yes, you may be able to do L2CAP as non-root, but that's only a very small part of what this bluetooth package is about. While classic BT is nice to have, BLE is what is most interesting at the moment (nrf doesn't even have classic BT).

Forget about BlueZ, it's crappy bloatware.

That may be so, but it's required for non-root BLE.

Don't confuse classic BT and BLE. The main thing that connects them is their name, and little else.

Looks like you aren't very familiar with BLE stack architecture, which isn't the best premise to write anything "cross-platform", again.

I couldn't get it to work on the esp32 yet due some weird crash so it's disabled at the moment.

I pushed a commit to master fcace26 which should fix this.

I pushed a commit to master fcace26 which should fix this.

Many thanks @dpgeorge, this fixes the issue! I would have needed a lot of time to find that bug.
This code now works on both the esp32 and the BBC micro:bit:

import bluetooth
bt = bluetooth.Bluetooth()
bt.active(1)
bt.advertise(100, 'MicroPython')
print('----')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
tx.write('foo')

Very nice @aykevl. This is a great start to make a uniform API across targets providing BLE.
I have verified the current implementation on nr52832, and based on what is already implemented it works quite well. :)

Already with this limited feature set, i could envision this to be a second BLE wrapper for nrf-port for a while, and phase out the ubluepy when this gets up to a certain feature set. This will easy further development of a common API.

Have you given any thoughts on how to handle events (connect / disconnect / notifications etc)?

Already with this limited feature set, i could envision this to be a second BLE wrapper for nrf-port for a while,

I think having two wrappers complicates things, for example who will handle events? Also, I think it's not really necessary to keep them both around either, as I intend to finish this PR in the next ~2 weeks.

Have you given any thoughts on how to handle events (connect / disconnect / notifications etc)?

Yes, but I'm not sure what the best way would be. One requirement for me is that there are fine-grained events, not one big event loop. That way, multiple modules could independently register a service and handle events for that service (example: an independent DFU module). For connect/disconnect, I think a global event handler would be more appropriate.
These events are somewhat lower priority than most IRQs and you will likely want to do more advanced stuff (such as heap allocations) in them, so I think it would perhaps be better to use micropython.schedule. I'll have to investigate this further.

EDIT: I should also mention that I am being sponsored by a company called Sensorberg. They have agreed with merging this upstream under the MIT license.

I think having two wrappers complicates things, for example who will handle events? Also, I think it's not really necessary to keep them both around either, as I intend to finish this PR in the next ~2 weeks.

Yeah, i did not think running them at the same time (ublupy/bluetooth). With this timeline i would guess full replacement right away should work as well as long as the basic feature set is in place. Any plans for BLE REPL replacement? :)

multiple modules could independently register a service and handle events for that service (example: an independent DFU module).

This sounds reasonable.

For connect/disconnect, I think a global event handler would be more appropriate.

See what you mean. But i would like to challenge this a bit as well. :)
If i'm not misunderstanding the current code/design, this is limited to one role at the time, either Central/Pehipheral/Broadcaster/Scanner? Would it make sense to extend the API to facilitate for Bluetooth() instances (and not one singleton)? Even if not supporting more than one in the beginning, the API opens up for multiple roles/instances at the same time in the future? If so, would the global connect/disconnect event handler work ? or could events be supplied with a instance handle supplementing the global event in order to distinguish which of the links had an event?

Any plans for BLE REPL replacement? :)

The MVP should support NUS written in Python. I'm not sure I want to directly include support in C at the same time, but it would certainly be very useful in the future.

Central/Pehipheral/Broadcaster/Scanner

To be honest, I never really got the focus on these roles. There is no inherent limitation in the API to have multiple roles at the same time. While not yet supported, I don't see why you wouldn't be able to advertise while a central is connected and at the same time perform a scan for new devices and connect to them. The only limitation is the BLE stack like s110.

What may be useful, however, is support for presenting as multiple devices at once. I think s132 supports that? To the outside world it looks like there are multiple devices but they're actually running on a single radio and BLE stack. I haven't investigated this area a lot. But I think they cannot be separated entirely at the API level: it's still one stack that has to be enabled.

Another issue that I'd like to get some feedback on: how should notifications work?
Notifications are basically a signal from the peripheral to the central that a characteristic has been updated. This is used to send information from the peripheral to the central, for example to send serial data over NUS, or to send heart rate updates in a classic BLE example.

I see two possible implementations:

1. Connections are managed by MicroPython. You can get a notification when a device connects or disconnects, but the only thing you have to do is send a notification and it'll get sent to all connected devices (if multiple connections are supported in the BLE stack).
2. Connections are managed by the Python script. It will have to track of all connect/disconnect events and manually send a notification to all of the connected devices.

Example of the former:

bt = bluetooth.Bluetooth()
bt.active(1)
bt.advertise(100, 'MicroPython')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
bt.set_event_handler(handle_event)

while 1:
    time.sleep(1)
    tx.write('log something\n')

Example of the latter:

connected_devices = set()
def handle_event(code, device):
    # TODO: can we even do memory allocations in an event handler?
    if code == bluetooth.CONNECTED:
        connected_devices.add(device)
    elif code == bluetooth.DISCONNECTED:
        connected_devices.remove(device)

def log(msg):
    for device in connected_devices:
        try:
            tx.notify(msg, device)
        except OSError:
            pass # probably this device disconnected but the event hasn't yet triggered

bt = bluetooth.Bluetooth()
bt.active(1)
bt.advertise(100, 'MicroPython')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
bt.set_event_handler(handle_event)

while 1:
    time.sleep(1)
    log('log something\n')

While the former is a bit more implementation work and less flexible, it is more modular. There is no central module that has to manage all connections: this is all done from within the Bluetooth wrapper. While it results in a bit more code size on devices that support more than one connection, I think it is ultimately far less error prone than the latter which is easy to get slightly wrong. The former also results in less Python code which usually leads to reduced RAM consumption. Remember that many of the more interesting BLE stuff requires notifications so it isn't really optional.
I would prefer to go with the former option, but would like to hear comments on this. Let me know if you can think of a use case that requires the flexibility of the latter.

how should notifications work?
...
I see two possible implementations:

On the one hand it's nice to push code into the Python level (ie approach 2) because it gives more flexibility and results in simpler/smaller firmware. On the other hand things that are low level and a necessary part of the stack which will be implemented the same way each time are good candidates to go in the C implementation (approach 1).

So I think it makes more sense to go for approach 1. Then Python code doesn't even need to know/worry whether multiple connections are supported or not, their BLE code remains the same. And there is already a lot to do on the Python side to configure and manage a BLE service, which is suitable for putting in Python-level libraries and/or helper functions, that adding more complexity in the Python code could make it difficult to maintain.

For BLE stacks that only support a single connection, approach 1 should be relatively simple to implement because it's likely that GAP/GATT callback functions already exist at the C level for other purposes. (And some BLE stacks may even handle notifications automatically so approach 2 would not be possible to implement on such stacks.)

I guess that for all characteristics that have a notify property there's rarely a case that they don't need to send a notification when their data changes, so having approach 1 do auto notification on characteristic change is not a big restriction. But if one day more flexibility is needed then a MANUAL_NOTIFY pseudo-property could be added which requires the user to do the notify.

On a related note, does the user need to restart advertising when the connection stops, or is that also automatic?

@dpgeorge thank you for your thoughts on the matter.

On a related note, does the user need to restart advertising when the connection stops, or is that also automatic?

This is automatic. At the moment, advertisement restarts on a disconnect event. This should be improved so advertisements continue to work when a device connects, and only when the max number of connections has been reached should it either switch to non-connectable advertisements or stop advertising. The former makes more sense to me (think of beacons that are connectable), while the latter seems to be more common in BLE devices.

Am I right there is no possibility to connect to the slave device directly knowing its address without scanning all available divices and matching their names/bdas???

Am I right there is no possibility to connect to the slave device directly knowing its address without scanning all available divices and matching their names/bdas???

Not sure what you're asking but this PR does not support central mode yet so it can't connect to any peripheral devices. If you're asking how other devices can connect to a BLE peripheral running MicroPython: that's completely up to them. They may scan first or connect directly when they know the MAC address.

This is automatic. At the moment, advertisement restarts on a disconnect event. This should be improved ...

This is an example where it might be more useful if the behaviour were controlled via Python code (not via the C driver). Because then the user could select how it worked: advertising stops, continues, changes, etc. The usual case is to handle just one connection, stop adv when connected and restart when disconnected. But adv can be more general than this, after all adv (and scanning) is used as the basis of BLE mesh.

For comparison, CircuitPython have a bleio module which is documented at https://circuitpython.readthedocs.io/en/latest/shared-bindings/bleio/__init__.html

Edit: see also a high-level wrapper for a UART NUS service: https://github.com/adafruit/Adafruit_CircuitPython_BLE/blob/master/adafruit_ble/uart.py

Also see the Adafruit library https://github.com/adafruit/Adafruit_CircuitPython_BLE, which implements a NUS service. We’ve tried to provide the basics in the native module, and then build the rest in Python.

Edit: [oops, crossed with @dpgeorge]

I have pushed support for notifications. Notifications are as simple as adding bluetooth.FLAG_NOTIFY to the characteristic flags, the rest is done inside the bluetooth module. However, I found some instability on nrf chips so I'll need to investigate the exact cause (something about BLE_ERROR_GATTS_SYS_ATTR_MISSING).

For comparison, CircuitPython have a bleio module which is documented at https://circuitpython.readthedocs.io/en/latest/shared-bindings/bleio/__init__.html

That's very interesting! They seem to handle notifications inside the module as well.

@aykevl Good work, looking forward to test your implementation on ESP32. Are you planning to do some more development or do you consider it done?

Also +1 for Sensorberg for permission to merge upstream.

I have pushed another change that adds a .on_update() method to characteristics to register writes by a central. For example:

def callback(char, data):
    print('data:', data)
rx.on_update(callback)

This works on both nrf52 and nrf51. Unfortunately, I haven't yet managed to get this working on the esp32, it crashes with a LoadProhibited on this line:

When I replace mp_call_function_2_protected with mp_call_function_2 (thinking it is something in exception handling), it crashes on this line with a load from address 0:

The crash for the second try is here:

Guru Meditation Error: Core  0 panic'ed (LoadProhibited). Exception was unhandled.
Core 0 register dump:
PC      : 0x400dd09e  PS      : 0x00060230  A0      : 0x800dd0ba  A1      : 0x3ffd4310  
A2      : 0x00000001  A3      : 0x00000001  A4      : 0x3ffb61b0  A5      : 0x00000080  
A6      : 0x00000001  A7      : 0x00000000  A8      : 0x800dd09e  A9      : 0x3ffd42f0  
A10     : 0x00000000  A11     : 0x00000000  A12     : 0x3ffb2b88  A13     : 0x00000000  
A14     : 0x00000001  A15     : 0x00000000  SAR     : 0x00000008  EXCCAUSE: 0x0000001c  
EXCVADDR: 0x00000000  LBEG    : 0x400014fd  LEND    : 0x4000150d  LCOUNT  : 0xffffffff  

Backtrace: 0x400dd09e:0x3ffd4310 0x400dd0b7:0x3ffd4340 0x400dfe75:0x3ffd4360 0x400dc045:0x3ffd4390 0x400dc0a2:0x3ffd43b0 0x400f76f9:0x3ffd43e0 0x400f2332:0x3ffd4410 0x40143d16:0x3ffd4430 0x40144976:0x3ffd4450 0x401417be:0x3ffd4490 0x40092b7d:0x3ffd44c0

Does anyone have an idea what might be going wrong on the esp32? I'm suspecting it has something to do with being handled in a different task. I have tried to increase the stack size for callbacks, but that didn't help.

If you specifically are talking about REPL over webluetooth then this currently only works with Nordic UART service (NUS), therefore only nrf boards are supported. I think this might be the same for Adafruit Bluefruit LE connect app. If you look at the supported device for the app they are all nordic chipset based.

NUS is proprietary in that it uses 128-bit UUIDs generated by Nordic, but there's no licensing requirement for it, and you don't have to use Nordic's code. Some people have implemented it on ESP32 (e.g., https://forum.arduino.cc/index.php?topic=580958.0, but see caveat).
The Adafruit Bluefruit LE app does depend on NUS for the vast majority of its functionality. There's a somewhat ad hoc protocol implemented on top of that for the control functionality the app provides (button presses, color picker, etc.). But it also provides generic UART capability.

for an idea of how to implement it using api similar to "bluepy" you can take a look at:
api_repl.py

for reference: #4893

@superted6851 yes I use chrome for testing WebBluetooth. it works well with Arduino code on ESP32 https://github.com/espressif/arduino-esp32/blob/master/libraries/BLE/examples/BLE_uart/BLE_uart.ino the MicroPython code seems to transmit the data, but only once, so seems that the notification doesn't work. needs more testing to understand it anyway

@dhalbert as far as I understood the NUS service are just the IDs yes and it's just publishing and subscribing data on the specified characteristics. or is there more to the NUS service ?

@silbo could you try the PR linked just above #5051 it's a newer superset of the changes from here updated to more platforms.

And yes, there's nothing special about NUS, it's just a service with characteristics labelled tx and rx to send raw data over, anyone can use it by copying the uuid's. It's become the defacto standard for fake-serial over ble.

@andrewleech I am currently trying to compile it and flash it, but I am missing something I guess, as I am not able to import bleutooth for esp32 ImportError: no module named 'bluetooth'

That PR contains BLE support only for STM32

Ah sorry, I know it's intended to be the standard api across all platforms, but missed the point that esp and nrf are still in progress there.

@andrewleech Thanks for the update, I tried Circuitpython meanwhile on my nrf52840-dk, works great across all platforms. Adafruit has made quite cool features also. Like acting as a USB storage etc. I am in love with their new upcoming product https://www.adafruit.com/product/4333

Superseded by #5051

@silbo, the code posted by @vanminh0910 works:

import bluetooth

bt = bluetooth.Bluetooth()
bt.active(True)
bt.advertise(100, "MicroPython")
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])

def callback(dev, char, data):
	print('char_irq', dev.config('mac'), dev.connected(), char.uuid(), data)

rx.irq(callback, bluetooth.IRQ_WRITE) # Register the callback to execute on data received

print('done')

You can write data using tx.write('my data') and the data you send using the app will be printed by the callback.

Could you please share firmware that you have used to run this script on ESP32 ?

I pushed a commit to master fcace26 which should fix this.

Many thanks @dpgeorge, this fixes the issue! I would have needed a lot of time to find that bug.
This code now works on both the esp32 and the BBC micro:bit:

import bluetooth
bt = bluetooth.Bluetooth()
bt.active(1)
bt.advertise(100, 'MicroPython')
print('----')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
tx.write('foo')

Can you share the firmware .bin file on which you have worked?

This is PR is superseded by #5051 (nimble impl.)

This is PR is superseded by #5051 (nimble impl.)

I downloaded latest firmware from micropython. In that it only supports BLE, But above code demonstrates for classic Bluetooth. I want to try with Classic Bluetooth

I do not see any BT classic related code / example anywhere(?)

Nimble is BLE only. See #5672 for BlueKitchen which can support bluetooth classic. However, I think that PR only implements BLE and not classic.

There is currently no BT classic support in MicroPython. The bluetooth.Bluetooth() class in the examples above is now renamed to bluetooth.BLE().

I have an issue running this code on my esp32, i am using the 1.13 firmware version
import bluetooth

bt = bluetooth.Bluetooth()
bt.active(1)
bt.advertise(100, 'MicroPython')
print('----')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
tx.write('foo')

-------ERROR--------------------
AttributeError: 'module' object has no attribute 'Bluetooth'
♦>
MicroPython v1.13 on 2020-09-02; ESP32 module with ESP32
Type "help()" for more information.

bt = bluetooth.Bluetooth()

As @dpgeorge pointed out in the very commit before yours it got renamed to bluetooth.BLE() :)
The examples should have been updated as well - or is there any obsolete info still out there @FerxhNova?

bt = bluetooth.Bluetooth()

As @dpgeorge pointed out in the very commit before yours it got renamed to bluetooth.BLE() :)
The examples should have been updated as well - or is there any obsolete info still out there @FerxhNova?

Thank you very much, i wrote befote read it all, my bad

Hello,

Here is my program
import bluetooth
bt = bluetooth.BLE()
bt.active(1)
bt.advertise(100, 'MicroPython')
print('----')
tx = bluetooth.Characteristic('6E400002-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_READ|bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic('6E400003-B5A3-F393-E0A9-E50E24DCCA9E', bluetooth.FLAG_WRITE)
s = bt.add_service('6E400001-B5A3-F393-E0A9-E50E24DCCA9E', [tx, rx])
tx.write('foo')

I have an issue
%Run -c $EDITOR_CONTENT
I (517227) phy: phy_version: 4180, cb3948e, Sep 12 2019, 16:39:13, 0, 2
Traceback (most recent call last):
File "", line 4, in
AttributeError: 'BLE' object has no attribute 'advertise'

Do you an example with ubluetooth module?

thanks to help me
Julien

AttributeError: 'BLE' object has no attribute 'advertise'

Which is correct, as the method's name you're looking for probably is: gap_advertise(). You might have been looking at some old/obsolete docs (I kinda recall it was advertise() indeed in the beginning..)

Thanks, could you give me the URL to the doc. Thanks

Thanks, could you give me the URL to the doc. Thanks

https://docs.micropython.org/en/latest/library/ubluetooth.html

It's btw the first hit if you google for "micropython bluetooth" :)

@JLFra wrote

tx = bluetooth.Characteristic ('6E400002-B5A3-F393 -E0A9-E50E24DCCA9E ', bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic (' 6E400003-B5A3-F393-E0A9-E50E24DCCA9E ', bluetooth.FLAGser3_WRITE_WRITE)
???? > s_bluetooth.FLAG_WRITE_WRITE600006 -E50E24DCCA9E ', [tx, rx])
tx.write (' foo ')

this line generates a syntax error

TRYING TO TEST

import bluetooth

bt = bluetooth.BLE ()
print ('bt.active (1)')
bt.active (1)
print ("bt.advertise (100, 'MicroPython')")
bt.advertise (100, 'MicroPython') # cause reboot

print ('----')

tx = bluetooth.Characteristic ('6E400002-B5A3-F393 -E0A9-E50E24DCCA9E ', bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY)
rx = bluetooth.Characteristic (' 6E400003-B5A3-F393-E0A9-E50E24DCCA9E ', bluetooth.FLAGser3_WRITE_WRITE)

s = bt.add_service ('6E300000249-E395A-E395A-E395A-E395A-E395A' , [rx])
#s_bluetooth.FLAG_WRITE_WRITE600006 -E50E24DCCA9E ', [tx, rx]) #???

tx.write (' foo ')
------------------------- GENERATES AN ERROR on MP:esp32-idf3-20200902-v1.13

bt.active (1)
/home/micropython/esp-idf-v3/components/freertos/queue.c:1442 (xQueueGenericReceive)- assert failed!
abort() was called at PC 0x4009b73c on core 1

ELF file SHA256: 0000000000000000000000000000000000000000000000000000000000000000

Whats wrong? I just dublicate prev. code

Whats wrong? I just dublicate prev. code

@zoland this PR is closed and was not merged, so the code samples here do not apply (unless you're specifically building this branch). A slightly different approach was taken for the final implementation of BLE in MicroPython.

Please see https://docs.micropython.org/en/latest/library/ubluetooth.html and https://github.com/micropython/micropython/tree/master/examples/bluetooth