README.txt

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