NOTES.txt

   1 BLE comm library, intended for libsigrok use, similar to libserialport.
   2 Based on the GPLv3 experiment at https://github.com/mrnuke/bluetooth-le-tests.
   3
   4 Current status:
   5 - Uses CMake, thus shall build and install on all major platforms (but
   6   see below for source code portability).
   7 - The library API is platform agnostic, shall be portable enough to work
   8   on all platforms supported by sigrok.
   9 - The library's internal implementation currently assumes Linux, uses
  10   AF_BLUETOOTH sockets and BlueZ headers (introduces new unconditional
  11   build dependency: libbluetooth-dev).
  12 - Assumes that BLE devices use "cable extender" mode. Sends an initial
  13   "characteristic value" to one handle, then keeps reading from another
  14   handle. Grabs payload data from indications (tested) as well as
  15   notifications (untested). BT classic is not covered (RFCOMM provides
  16   virtual COM ports and doesn't need libble, but see TODO items below).
  17 - Was tested with an EEVBlog 121GW multimeter (builtin BLE122 module).
  18   Owon OW18B may work in similar ways (TI CC254x module). Uni-T UT-D07
  19   status is unknown.
  20
  21 Build the library:
  22
  23   nothing fancy, straight cmake approach, like so:
  24
  25   $ mkdir build; cd build; cmake ..
  26   $ [ cmake -DCMAKE_INSTALL_PREFIX=$HOME .; ccmake . ]
  27   $ make
  28   $ [ make install ]
  29
  30 Example use:
  31
  32   see builtin help
  33   $ ./ble-test -h
  34
  35   select device address, see raw bytes in text and binary format
  36   $ ADDR=88:6B:12:34:56:78
  37   $ ./ble-test -m $ADDR -r 8 -w 9 -W 0x0003
  38   $ ./ble-test -m $ADDR
  39   $ ./ble-test -m $ADDR -b | hexdump -Cv
  40
  41   feed a COM port (assumes loopback between two of them, COM port loop
  42   becomes obsolete when libsigrok grows native libble support)
  43   $ COM_FEED=/dev/ttyUSB1; COM_READ=/dev/ttyUSB0
  44   $ ( exec > $COM_FEED; exec < $COM_FEED; stty 115200; ./ble-test -m $ADDR -b ) &
  45   $ sigrok-cli -d eevblog-121gw:conn=$COM_READ --scan
  46   $ sigrok-cli -d eevblog-121gw:conn=$COM_READ --samples 100
  47
  48   scan for BT devices (note that LE scan requires priviledges)
  49   $ ./ble-test -s 8
  50
  51   communicate to an RFCOMM server
  52   $ SRV_ADDR=11:22:33:44:55:66
  53   $ [ ./rfcomm-test & ]
  54   $ ./ble-test -m $SRV_ADDR -R 1 -d 100
  55   $ [ kill $! ]
  56
  57 Known issues, TODO items:
  58 - Improve robustness. Optionally re-connect and re-initiate reception
  59   upon connection loss, from previously cached parameters? Could apply
  60   to both RFCOMM as well as BLE indications/notifications, but apps
  61   may differ in their preference. In either case, apps must be able to
  62   learn of errors, even when auto-recovery applies.
  63 - Improve usability. Handle timeouts during connect, which currently
  64   blocks indefinitely when the specified peer does not become available.
  65 - Do integrate with libsigrok's infrastructure. Provide a namespace in
  66   the serial layer (assumes serial-over-HID as a foundation) for simple
  67   devices like DMMs. Optionally allow "deep" access from individual
  68   drivers for more complex devices or unusual communication approaches
  69   (other than notify/indicate).
  70 - Come up with the appropriate conn= syntax. Like conn=bt/ble122/<addr>
  71   or conn=bt/ti-cc254x/<addr> etc for BLE, optionally followed by handle
  72   and value specs (while their defaults result from the 'ble122' etc
  73   "profile" names). Or conn=bt/rfcomm/<addr> for BT classic and RFCOMM
  74   channels, optionally followed by the channel number (default 1).
  75 - I'm aware of libserialport's support for bluetooth ports. But IIUC
  76   libsp expects users to explicitly configure these, while libble can
  77   use them in transparent ways with just the server address spec. Users
  78   still can either specify conn=<rfcomm-port> or conn=bt/rfcomm/<addr>
  79   as they please.
  80 - Rename the library to libbtserial or similar, since it deals with BLE
  81   as well as RFCOMM?
  82 - Check whether support for other platforms can fit under the library's
  83   public API. It's assumed that this is the case, as the API purposely
  84   was designed to not encode specific assumptions of the first available
  85   implementation.
  86 - Implement support for other platforms. CMake can handle build variants
  87   just fine, including platform dependent parts as well as common code.
  88   The Linux implementation can either remain separate, or can use common
  89   code that covers multiple platforms if such a library exists, can and
  90   will be used, or gets implemented. (Searches on the 'Net suggest that
  91   available libs are either written in Python or .Net, or authors think
  92   that cross platform means "mobile Apple and Windows", the latter WIP
  93   perhaps. Qt may support BT including BLE, but only on most recent
  94   versions of these platforms, and is quite large a dependency for a
  95   libsigrok driver or comm layer)