Can't connect to Client - is server mode possible?

[bobmorane06]

Congratulations for the project and thank you for making it open source.

Can ble-serial send a serial stream over BLE to an Android phone?

I got your stack working as I am able to scan and ble-serial connect to an HM19 module. But instead to connect to an HM10/HM19, I would like to establish a serial link over BLE via a USB BLE dongle (without using the HM19) to my android phone.

FYI without ble-serial and a USB-BLE dongle, I am able to connect my phone to the HM19: I first connected the HM19 to a USB-to-serial module CP210x and data sent to the COM port of the CP210x module would show on “Serial Bluetooth Terminal” on Android.

How come my phone doesn’t show with a ble-scan?

Is It possible to ble-serial to the phone?

[Jakeler]

Interesting question. The thing is that the Bluetooth architecture has different roles for devices. Usually the peripheral device provides a server and constantly sends out advertisements, then other devices can scan and connect in client mode. For example HM19 is per default a server (can be changed through AT commands) and ble-serial is always the client.

Now Android mostly also acts as client, connecting to servers in headphones etc. That is why it will not directly work with ble-serial, because it is just another client with the Terminal.
To connect both you need some software on the smartphone to run it as server. I searched on Google Play and this is apparently very rare, I only found this: https://play.google.com/store/apps/details?id=com.roguefactories.btsppserver
It seems to do what is claims, but is only SPP = legacy bluetooth 2.0.
For BLE 4.0+ I could not find any app, so I looked at the Android API and fairly recently (with Android 10) there was a option added to create BLE servers too: https://developer.android.com/reference/android/bluetooth/BluetoothServerSocket
I don't think anyone has it implemented so far, but it should be possible.

[bobmorane06]

Thank you Jakeler. I actually need to use an existing Android app that acts as a client, so to get this working I need to find a way to send serial data over BLE from Windows with the BLE USB dongle acting as a server. I haven't found anything doing so. Have you come across anything along these lines during your own research?

I understand that what I'm looking for isn't the standard scheme when it comes to IoT and typical makers' arduino sensor projects...

[Jakeler]

Ok, I see, making the PC a server should work too. Problem is that the BLE lib (bleak) which I use is only a client implementation, so I can't easily enable it. There are APIs that would allow this though, on Linux with BlueZ/DBus:
https://punchthrough.com/creating-a-ble-peripheral-with-bluez/
On Windows UWP:
https://docs.microsoft.com/de-de/windows/uwp/devices-sensors/gatt-server
Again I am not aware of anything that implements these, but I also did not do extensive research on the Windows side. Maybe that info helps you a bit to find or build something, they have also some sample code: https://github.com/microsoft/Windows-universal-samples/tree/main/Samples/BluetoothLE

Edit: Some related discussion happened already on bleak: hbldh/bleak#81
This project might be worth a closer look: https://github.com/kevincar/bless
It is not hugely popular, but development looks quite active.

[Jakeler]

I made an experimental server implementation now, it can be installed like this:

pip install bless
pip install https://github.com/Jakeler/ble-serial/archive/refs/heads/server-mode.zip

Note this this version always acts as server, you have to install the normal version if the client function is needed again. (this will be different in the final release)

To start it the service, read and write UUIDs have to be specified, for example the Nordic UART profile:

ble-serial -d server -s 6e400001-b5a3-f393-e0a9-e50e24dcca9e -w 6e400002-b5a3-f393-e0a9-e50e24dcca9e -r 6e400003-b5a3-f393-e0a9-e50e24dcca9e -vv

The device argument server does not matter, it will show up as your PC hostname instead. Currently it works only on Windows, not on Linux (kevincar/bless#60).
Also for some reason ble-serial in normal client mode is unable to connect to this server, I have to investigate why. Tests were successful with Android and Serial Bluetooth Terminal though.
So it is definitely not bug-free, but I want to put it already out there. Feel free to try it @bobmorane06, it might work for your application.

[bobmorane06]

Thanks for the work! Not working for me, here is what I get:

ble-serial -d server -s 6e400001-b5a3-f393-e0a9-e50e24dcca9e -w 6e400002-b5a3-f393-e0a9-e50e24dcca9e -r 6e400003-b5a3-f393-e0a9-e50e24dcca9e -vv
15:56:37.046 | DEBUG | main.py: Running: Namespace(verbose=2, port='BLE', device='server', timeout=5.0, addr_type='public', adapter='hci0', mtu=20, service_uuid='6e400001-b5a3-f393-e0a9-e50e24dcca9e', write_uuid='6e400002-b5a3-f393-e0a9-e50e24dcca9e', read_uuid='6e400003-b5a3-f393-e0a9-e50e24dcca9e', mode='rw', filename=None, binlog=False)
15:56:37.046 | DEBUG | proactor_events.py: Using proactor: IocpProactor
15:56:37.047 | INFO | ble_server.py: Receiver set up
15:56:37.047 | DEBUG | server.py: Creating a new service with uuid: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
15:56:37.047 | DEBUG | server.py: Adding service to server with uuid 6e400001-b5a3-f393-e0a9-e50e24dcca9e
15:56:37.058 | INFO | ble_server.py: Service 6e400001-b5a3-f393-e0a9-e50e24dcca9e (Handle: 0): Nordic UART Service
15:56:37.059 | INFO | ble_server.py: Write characteristic: 6e400002-b5a3-f393-e0a9-e50e24dcca9e:
15:56:37.059 | INFO | ble_server.py: Read characteristic: 6e400003-b5a3-f393-e0a9-e50e24dcca9e:
15:56:37.066 | ERROR | main.py: Unexpected Error: OSError(22, 'The device does not support the command feature', None, -2147024580, None)
15:56:37.066 | WARNING | main.py: Shutdown initiated
15:56:37.067 | INFO | windows_com0com.py: Stopping RX+TX loop
Traceback (most recent call last):
  File "C:\Program Files\Python310\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Program Files\Python310\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\user1\AppData\Roaming\Python\Python310\Scripts\ble-serial.exe\__main__.py", line 7, in <module>
  File "C:\Users\user1\AppData\Roaming\Python\Python310\site-packages\ble_serial\main.py", line 113, in launch
    m.start()
  File "C:\Users\user1\AppData\Roaming\Python\Python310\site-packages\ble_serial\main.py", line 13, in start
    asyncio.run(self._run())
  File "C:\Program Files\Python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Program Files\Python310\lib\asyncio\base_events.py", line 641, in run_until_complete
    return future.result()
  File "C:\Users\user1\AppData\Roaming\Python\Python310\site-packages\ble_serial\main.py", line 96, in _run
    await self.bt.disconnect()
  File "C:\Users\user1\AppData\Roaming\Python\Python310\site-packages\ble_serial\bluetooth\ble_server.py", line 99, in disconnect
    await self.server.stop()
  File "C:\Users\user1\AppData\Roaming\Python\Python310\site-packages\bless\backends\winrt\server.py", line 100, in stop
    service.service_provider.stop_advertising()
OSError: [WinError -2147483634] A method was called at an unexpected time

I tried with 3 different USB BLE dongles, Details of the last one:

    =========================== USB Port4 ===========================

Connection Status        : 0x01 (Device is connected)
Port Chain               : 1-3-4
Properties               : 0x01
 IsUserConnectable       : yes
 PortIsDebugCapable      : no
 PortHasMultiCompanions  : no
ConnectionIndex          : 4
CompanionIndex           : 0
 CompanionHubSymLnk      : USB#VID_2109&PID_0813#5&356b5377&0&19#{f18a0e88-c30c-11d0-8815-00a0c906bed8}
 CompanionPortNumber     : 4

      ======================== USB Device ========================

        +++++++++++++++++ Device Information ++++++++++++++++++
Device Description       : Broadcom BCM20702 Bluetooth 4.0 USB Device
Device Path              : \\.\usb#vid_0a5c&pid_21e8#000272cc89e4#{a5dcbf10-6530-11d2-901f-00c04fb951ed}
Device ID                : USB\VID_0A5C&PID_21E8\000272CC89E4
Driver KeyName           : {e0cbf06c-cd8b-4647-bb8a-263b43f0f974}\0004 (GUID_DEVCLASS_BLUETOOTH)
Driver                   : C:\WINDOWS\System32\drivers\BTHUSB.sys (Version: 10.0.22000.282  Date: 2021-11-10)
Driver Inf               : C:\WINDOWS\inf\oem15.inf
Legacy BusType           : PNPBus
Class                    : Bluetooth
Class GUID               : {e0cbf06c-cd8b-4647-bb8a-263b43f0f974} (GUID_DEVCLASS_BLUETOOTH)
Interface GUID           : {a5dcbf10-6530-11d2-901f-00c04fb951ed} (GUID_DEVINTERFACE_USB_DEVICE)
Service                  : BTHUSB
Enumerator               : USB
Location Info            : Port_#0004.Hub_#0004
Location IDs             : PCIROOT(0)#PCI(1400)#USBROOT(0)#USB(3)#USB(4), ACPI(_SB_)#ACPI(PCI0)#ACPI(XHC_)#ACPI(RHUB)#ACPI(HS03)#USB(4)
Container ID             : {ffe7ca51-42e1-53cb-b628-26c1d6807eeb}
Manufacturer Info        : Broadcom
Capabilities             : 0x94 (Removable, UniqueID, SurpriseRemovalOK)
Status                   : 0x0180600A (DN_DRIVER_LOADED, DN_STARTED, DN_DISABLEABLE, DN_REMOVABLE, DN_NT_ENUMERATOR, DN_NT_DRIVER)
Problem Code             : 0
Lower Filters            : bcbtums

[Jakeler]

Hmm, interesting. Your BCM20702 should support the server role in theory, are you sure the driver is correct?
What were the other 2?

I used a RTL8761B, which is in most generic/cheap BT 5.0 adapters and for example the Asus USB-BT500.

[bobmorane06]

The other ones show as "Generic Bluetooth Radio" (Cambridge Silicon Radio Ltd.). I uninstalled all bluetooth devices including hidden/not connected one from Device Manager, then let Windows load the drivers as well as check for updated rivers, no change. Any suggestion to ensure it's the proper driver?

[Jakeler]

Maybe try a different driver package, I would not recommend downloading from random websites, but for example Lenovo offers a old version and newer version (still 2015 though). You are using Windows 10, right?

Otherwise I honestly don't know. You could try to run this example script (just download and start it with python server.py). It is a bit simpler than my code, if it also fails you can create an issue on bless, Kevin might have more ideas how to debug this.

[zalexua]

I've looked to changes in the branch and see that parameter name to used is -g, not -d.

I've tried now on my Ubunty 22.04 and I can get this result:

# ble-serial -g server -s 6e400001-b5a3-f393-e0a9-e50e24dcca9e -w 6e400002-b5a3-f393-e0a9-e50e24dcca9e -r 6e400003-b5a3-f393-e0a9-e50e24dcca9e -vv
02:39:50.222 | DEBUG | main.py: Running: Namespace(verbose=2, port='/tmp/ttyBLE', timeout=5.0, adapter='hci0', mtu=20, device=None, addr_type='public', service_uuid='6e400001-b5a3-f393-e0a9-e50e24dcca9e', write_uuid='6e400002-b5a3-f393-e0a9-e50e24dcca9e', read_uuid='6e400003-b5a3-f393-e0a9-e50e24dcca9e', mode='rw', gap_role='server', filename=None, binlog=False)
02:39:50.222 | DEBUG | selector_events.py: Using selector: EpollSelector
02:39:50.222 | INFO | linux_pty.py: Slave created on /tmp/ttyBLE -> /dev/pts/6
02:39:50.222 | DEBUG | ble_server.py: Name/ID: BLE Serial Server 673932
02:39:50.222 | INFO | ble_server.py: Listener set up
02:39:50.231 | INFO | ble_server.py: Service 6e400001-b5a3-f393-e0a9-e50e24dcca9e (Handle: 0): Nordic UART Service
02:39:50.232 | INFO | ble_server.py: Write characteristic: 6e400002-b5a3-f393-e0a9-e50e24dcca9e: Nordic UART RX
02:39:50.232 | INFO | ble_server.py: Read characteristic: 6e400003-b5a3-f393-e0a9-e50e24dcca9e: Nordic UART TX
02:39:50.365 | INFO | ble_server.py: Server startup successful
02:39:50.365 | INFO | main.py: Running main loop!

And I could see my Ubuntu advertising as "BLE Serial Server 674248".
If I restart the command, the number in the name being changed a little.
Broadcasting performed, not so often - ~1270ms, which is unusual, as most of BLE devices I saw do it more offten.

I can connect to it from Android, using "nRF Connect" app from Nordic.

Also, I could connect from "Serial Bluetooth Terminal" app too, and send serial data, which I send/receive data on Linux on /tmp/ttyBLE in both directions !

03:03:39.793 | DEBUG | ble_server.py: Received write from 6e400002-b5a3-f393-e0a9-e50e24dcca9e: Nordic UART RX: bytearray(b'Hello from Android !\r\n    ')
03:03:39.793 | DEBUG | linux_pty.py: Write: bytearray(b'Hello from Android !\r\n    ')
03:04:04.160 | DEBUG | linux_pty.py: Read: b'HELLO from Linux Ubu'
03:04:04.160 | DEBUG | ble_server.py: Offering read b'HELLO from Linux Ubu'
03:04:04.160 | DEBUG | linux_pty.py: Read: b'ntu!\r\n'
03:04:04.160 | DEBUG | ble_server.py: Offering read b'ntu!\r\n'

Not every time connecting is successful, I often get error:
Connection failed: gatt status 133
but I retry and get it connected after a few attempts or so.

BT applet on my KDE Plasma properly shows that I have active connection from my Anroid phone name

So, maybe this should be merged to Master branch to be ready used when needed?

The only issue I have is, when I try to specify custom UUIDs, it fails:

# ble-serial -g server -s 0000ffe0‑0000‑1000‑8000‑00805f9b34fb -w 0000ffe2‑0000‑1000‑8000‑00805f9b34fb -r 0000ffe1‑0000‑1000‑8000‑00805f9b34fb -vv03:08:00.946 | DEBUG | main.py: Running: Namespace(verbose=2, port='/tmp/ttyBLE', timeout=5.0, adapter='hci0', mtu=20, device=None, addr_type='public', service_uuid='0000ffe0‑0000‑1000‑8000‑00805f9b34fb', write_uuid='0000ffe2‑0000‑1000‑8000‑00805f9b34fb', read_uuid='0000ffe1‑0000‑1000‑8000‑00805f9b34fb', mode='rw', gap_role='server', filename=None, binlog=False)
03:08:00.946 | DEBUG | selector_events.py: Using selector: EpollSelector
03:08:00.946 | INFO | linux_pty.py: Slave created on /tmp/ttyBLE -> /dev/pts/6
03:08:00.946 | ERROR | main.py: badly formed hexadecimal UUID string
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/main.py", line 34, in _run
    self.bt = self.BLE_class(args.adapter, args.service_uuid,
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/ble_server.py", line 15, in __init__
    self.write_uuid = check_fill_empty(service_uuid, write_uuid, 'write')
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/uuid_helpers.py", line 17, in check_fill_empty
    assert compare_node(service_uuid, uuid), f'Service and {typ} uuid are not from the same family'
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/uuid_helpers.py", line 10, in compare_node
    return UUID(uuid1).node == UUID(uuid2).node
  File "/usr/lib/python3.10/uuid.py", line 177, in __init__
    raise ValueError('badly formed hexadecimal UUID string')
ValueError: badly formed hexadecimal UUID string
03:08:00.947 | WARNING | main.py: Shutdown initiated
03:08:00.947 | INFO | linux_pty.py: Serial reader and symlink removed
03:08:00.947 | INFO | main.py: Shutdown complete.

I think this 'badly formed hexadecimal UUID string' issue can be easily fixed.

[zalexua]

After googling about reading this https://stackoverflow.com/questions/63220786/django-how-to-fix-uuid-valueerrorbadly-formed-hexadecimal-uuid-string
I've substituted all - in UUID and was able to run it successfully:

# ble-serial -g server -s 0000ffe000001000800000805f9b34fb -w 0000ffe200001000800000805f9b34fb -r 0000ffe100001000800000805f9b34fb
03:28:34.281 | INFO | linux_pty.py: Slave created on /tmp/ttyBLE -> /dev/pts/6
03:28:34.281 | INFO | ble_server.py: Listener set up
03:28:34.288 | INFO | ble_server.py: Service 0000ffe0-0000-1000-8000-00805f9b34fb (Handle: 0): Vendor specific
03:28:34.288 | INFO | ble_server.py: Write characteristic: 0000ffe2-0000-1000-8000-00805f9b34fb: Vendor specific
03:28:34.289 | INFO | ble_server.py: Read characteristic: 0000ffe1-0000-1000-8000-00805f9b34fb: Vendor specific
03:28:34.426 | INFO | ble_server.py: Server startup successful
03:28:34.426 | INFO | main.py: Running main loop!

But I could not get "Serial Bluetooth Terminal" successfully connected afterward (it has some issues with discovering UUIDs, I know, when device is BLE+Classic simultaneously).
Sometimes it says: "write characteristic not writable", sometimes the "gatt status 133"

But "nRF Connect" could connect and send/receive data.

[zalexua]

So, to get this new feature there is a PR #60, which is based on "server-mode" branch.
The branch is 9 commits ahead and 25 commits behind Master.

I've forked this repo to https://github.com/zalexua/ble-serial and managed to successfully rebase Master to "server-mode" branch and then merge "server-mode" back to Master.
Yes, there were merge conflicts, after TCP socket implementation in Master, but surprisingly I managed to resolve that!

Then I've tested both Client and Server modes, including Server mode with forwarding data to TCP socket and it really worked!
I'm still using Linux, as said above.

So, while in PR #60 are some concerns about data integrity (on high speed?) I think "server-mode" branch really worth to be merged to upstream Master to get both features available.
If needed, I could make a fresh PR from my repo, or you @Jakeler can do it yourself.

I'm going to do some minor improvements further. Like possibility to specify BLE name instead of generate it as predefined with a random PID part.

[zalexua]

FYI:
I was able to get 2 modes to be running simultaneously on the same Linux box - Server + Client:

Both were able transfer data in both directions.

Maybe there are some race conditions, because once I saw these exception errors printed for running client:

$ ble-serial -d 16:AA:22:02:23:45
03:00:23.462 | INFO | linux_pty.py: Port endpoint created on /tmp/ttyBLE -> /dev/pts/10
03:00:23.462 | INFO | ble_client.py: Receiver set up
03:00:23.646 | INFO | ble_client.py: Trying to connect with 16:AA:22:02:23:45: ANT-BLE16ZMUB
03:00:24.419 | INFO | ble_client.py: Device 16:AA:22:02:23:45 connected
03:00:24.419 | INFO | ble_client.py: Found write characteristic 0000ffe1-0000-1000-8000-00805f9b34fb (H. 15)
03:00:24.419 | INFO | ble_client.py: Found notify characteristic 0000ffe1-0000-1000-8000-00805f9b34fb (H. 15)
03:00:24.594 | INFO | main.py: Running main loop!
03:01:01.375 | ERROR | events.py: A message handler raised an exception: 'Device'.
Traceback (most recent call last):
  File "src/dbus_fast/message_bus.py", line 811, in dbus_fast.message_bus.BaseMessageBus._process_message
  File "/usr/local/lib/python3.10/dist-packages/bleak/backends/bluezdbus/manager.py", line 755, in _parse_msg
    self._service_map.setdefault(service_props["Device"], set()).add(
KeyError: 'Device'

03:04:07.877 | ERROR | events.py: A message handler raised an exception: 'Device'.
Traceback (most recent call last):
  File "src/dbus_fast/message_bus.py", line 811, in dbus_fast.message_bus.BaseMessageBus._process_message
  File "/usr/local/lib/python3.10/dist-packages/bleak/backends/bluezdbus/manager.py", line 755, in _parse_msg
    self._service_map.setdefault(service_props["Device"], set()).add(
KeyError: 'Device'

03:05:21.324 | WARNING | ble_client.py: Device 16:AA:22:02:23:45 disconnected
03:05:21.325 | INFO | ble_client.py: Stopping Bluetooth event loop
03:05:21.325 | WARNING | main.py: Shutdown initiated
03:05:21.325 | INFO | linux_pty.py: Serial reader and symlink removed
03:05:21.325 | INFO | main.py: Shutdown complete.

but data still was transferred.

If I Then I tried to interrupt it and restart thus Client again, while Server was still currently connected in another shell:

$ ble-serial -d 16:AA:22:02:23:45
03:05:28.532 | INFO | linux_pty.py: Port endpoint created on /tmp/ttyBLE -> /dev/pts/10
03:05:28.532 | INFO | ble_client.py: Receiver set up
03:05:28.790 | INFO | ble_client.py: Trying to connect with 16:AA:22:02:23:45: ANT-BLE16ZMUB
03:05:33.797 | ERROR | main.py: 
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/dist-packages/bleak/backends/bluezdbus/client.py", line 204, in connect
    reply = await self._bus.call(
  File "/usr/local/lib/python3.10/dist-packages/dbus_fast/aio/message_bus.py", line 370, in call
    await future
asyncio.exceptions.CancelledError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/main.py", line 53, in _run
    await self.bt.connect(args.device, args.addr_type, args.timeout)
  File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/ble_client.py", line 38, in connect
    await self.dev.connect()
  File "/usr/local/lib/python3.10/dist-packages/bleak/__init__.py", line 531, in connect
    return await self._backend.connect(**kwargs)
  File "/usr/local/lib/python3.10/dist-packages/bleak/backends/bluezdbus/client.py", line 141, in connect
    async with async_timeout(timeout):
  File "/usr/local/lib/python3.10/dist-packages/async_timeout/__init__.py", line 129, in __aexit__
    self._do_exit(exc_type)
  File "/usr/local/lib/python3.10/dist-packages/async_timeout/__init__.py", line 212, in _do_exit
    raise asyncio.TimeoutError
asyncio.exceptions.TimeoutError
03:05:33.806 | WARNING | main.py: Shutdown initiated
03:05:33.806 | INFO | linux_pty.py: Serial reader and symlink removed
03:05:33.806 | INFO | main.py: Shutdown complete.

But after Andriod app has disconnected from the Server (while it's still running/listening), this Client also was able to start and connect to a BLE device again.

So there are possible some minor glitches for such edge cases, just letting you know.

[Jakeler]

Hey @zalexua, thanks for trying it out and working on it.
I can/will rebase the branch myself, for the other improvements please send PRs to the server-mode branch, so we can merge it all together.

Before declaring a release with this feature I would really like to get the 2 points sorted out:

• fix bugs with notify reordering
  This causes the tests to fail because packets don't arrive in the order they have been sent. Of course this breaks data integrity. Yes indeed, happens only on high speed (saturated link). Still it's very weird, bluetooth normally guarantees correct ordering, high level apps should not have to care about this. Maybe it gets screwed up somewhere in between, like dbus or buffering. Have to open an issue on bleak, if it's reproducible there. But I also have to re-test with the latest version, maybe it's already fixed.
• session handling
  Currently the server app has no knowledge if a client is connected, it should at least log connects/disconnects. Also it does not always handle disconnects properly, so new devices can't reconnect without a restart. On server shutdown clients should get disconnected automatically.

Also since I am also on Linux, have to do at least do some basic checks on Windows as most users are there.

[zalexua]

Hello @Jakeler !
I see you are doing some magic with git repos, which is hard to me to track what you are doing. I hope you are preparing to do the rebase/merge yourself.
Then I could do some additional PR for some tiny features which I did in my fork.

I should share impression that Server mode works really well !
I'm using it already a lot. The only troubles are happening because such server does advertisement for both Classic BT and BLE simultaneous, which works not so well for all clients/applications.
But that's another story, not related to Server mode itself.
There are things/limitations related to Bless, BlueZ and Dbus.

[Jakeler]

Just a heads up, I worked more on the server mode branch recently and finally consider it ready!
Will tag it as 3.0.0 soon. See the readme for a current documentation.
@zalexua in case you haven't already seen, I included a few of your commits, thanks!

[zalexua]

@Jakeler thank you for recent work on this !!!!!