README

   1 Bluetooth-Frwk-NG - BlueZ framework new generation
   2 **************************************************
   3
   4
   5 Copyright (C) 2013-2014 Intel Corporation
   6
   7 Overreview
   8 ===========
   9
  10 The overall goal of the Bluetooth-Frwm-NG project is to provide a bluetooth
  11 framework for embedded/mobile and desktop systems based on Linux.
  12
  13 Within Bluetooth-Frwk-NG there is clear abstraction between the application
  14 interfaces based on CAPI, the lower level (via D-Bus) and the integration with
  15 other system components (plugins). The whole architecture is modular and
  16 flexible.
  17
  18 Architecture:
  19
  20         Application                System-Message-Dialog
  21             +                             +
  22             |                             |
  23             |                             |
  24             +                             +
  25         CAPI-Bluetooth +---------+ Bluetooth-Service
  26             +                             +
  27             |                             |
  28             |                             |
  29             +-----bluez-lib/obex-lib------+
  30                             +
  31                             |
  32                             |
  33                             +
  34                         BlueZ 5.x
  35
  36 CAPI-Bluetooth provide a series of API based on BlueZ's features, and it's
  37 easy to use through bluez-lib/obex-lib that encapsulate D-Bus interfaces about
  38 BlueZ. All applications use CAPI-Bluetooth to call BlueZ's function. Mostly
  39 APIs directly use bluez-lib/obex-lib to call BlueZ, but others call
  40 Bluetooth-Service that also using bluez-lib/obex-lib to access BlueZ, because
  41 some features should be keeping during the calling procedure, such as send
  42 file through Obex. System-Message-Dialog show the extern message, such as
  43 input-pincode, using plugin to walk up it.
  44
  45 Develop Mode (on PC) and Runing Mode (on target):
  46
  47 Bluetooth-Frwk-NG can be developed on PC and running on other system (such as
  48 mobile). Develop, run and test it on PC. Once the feature's development is
  49 finished, porting it to other system is easy using cross-compile, that means
  50 compile it on the target (such as mobile) environment. Package it to RPM,
  51 then push the RPM package to target machine, install the RPM on target
  52 machine, run binary.
  53
  54 Compilation and installation
  55 ============================
  56
  57 In order to compile Bluetooth-Frwk-NG you need following software packages:
  58         - CMake tool
  59         - GCC compiler
  60         - D-Bus library
  61         - glib-2.0 library
  62         - gio-2.0 library
  63         - gio-unix-2.0 library
  64
  65 Develop Mode (on PC):
  66
  67         To compile and install:
  68                 cmake . && make && make install
  69
  70         The files are installed to right position. Goto 'Running and Test'
  71         section to test the development feature.
  72
  73 Running Mode (on Target):
  74
  75         After test feature on PC, it can be ported to target. Pakaging RPM
  76         with target.
  77
  78         Firstly build the target environment. Build cap-network-bluetooth
  79         project that download from source code repo, using building tool
  80         (such as gbs) with local that will create a local-target-environment.
  81         With gbs it like this:
  82                 ~/GBS-ROOT/local/BUILD-ROOTS/scratch.i586.0/home/abuild/
  83         named ${TARGET_ENVIRONMENT_DIR}
  84
  85         Secondly package cap-network-bluetooth-${version}.tar.gz from source
  86         code, then push the tarball and .spec file in packaing dir in source
  87         code to $(TARGET_ENVIRONMENT_DIR)/rpmbuild/SOURCES/
  88
  89         ${version}: project version, for example 0.1.39
  90
  91         To switch to target environment:
  92                 cd ${TARGET_ENVIRONMENT_DIR}
  93                 gbs chroot .
  94
  95         Now, in the target environment, compile and package RPM are all with
  96         target (such as mobile).
  97
  98         To package RPM:
  99                 rpmbuild -ba packaging/capi-network-bluetooth.spec
 100
 101         The step will create capi-network-bluetooth-0.1.39-1.i586.rpm in
 102         $(TARGET_ENVIRONMENT_DIR)/rpmbuild/RPM/i586/
 103
 104         Push it to target and login target machine.
 105
 106         To install on target (such as mobile):
 107                 rpm -ivh capi-network-bluetooth-0.1.39-1.i586.rpm
 108
 109 Running and Test
 110 ================
 111
 112 In order to run and test you should compile the whole project and install them.
 113         To run:
 114                 bluetooth-service
 115
 116         To test API (select one to test the corresponding API):
 117
 118         +-----------------------+---------------------------------------------------------------+
 119         | test case             | API & Interface               | File name                     |
 120         +-----------------------+-------------------------------+-------------------------------+
 121         | bluez-capi-test       | CAPI-Bluetooth API            | include/bluetooth.h           |
 122         +-----------------------+-------------------------------+-------------------------------+
 123         | bluez-lib-test        | bluez-lib Interface           | include/bluez.h               |
 124         +-----------------------+-------------------------------+-------------------------------+
 125         | obex-lib-test         | obex-lib Interface            | include/obex.h                |
 126         +-----------------------+-------------------------------+-------------------------------+
 127         | bt-serivce-lib-test   | Bluetooth-Service Interface   | include/bluetooth-service.h   |
 128         +-----------------------+-------------------------------+-------------------------------+
 129
 130
 131 Development for Bluetooth-Frwk-NG
 132 =================================
 133
 134 Develop Bluetooth-Frwk-NG on Linux and test it. See:
 135         Compilation and installation==>Develop Mode (on PC)
 136
 137 Finally port it to target (such as mobile). See:
 138         Compilation and installation==>Running Mode (on Target):
 139
 140         - Develop feature on PC
 141         - Compile project on PC
 142         - Run binary and Test on PC
 143         - Port it to target and test.
 144
 145 Once those are finished, you can submit the patch to project owner:
 146         - git add [modified files]
 147         - git commit
 148         - git format-patch <util>..<since>
 149         - checkpatch.pl [patch] --no-tree
 150         - git send-email [patch] --to=martin.xu@linux.intel.com
 151                                  --cc=<cc name> --from=your_email_addres
 152
 153 checkpatch.pl: download from kernel souce code checking patch.
 154
 155 Development apps basing on Bluetooth-Frwk-NG
 156 ============================================
 157
 158 All APIs are contained in include/bluetooth.h. Applications must use those API
 159 to finish the application's function. Most APIs have the returned value with
 160 bt_error_e, so all the API that has returned value, should be checked.
 161
 162 bt_initialize() should be invoked before all other APIs to initialize Bluetooth
 163 Framework, and bt_deinitialize() should be invoked after all other APIs to free
 164 resouce with Bluetooth Framework.
 165
 166 Flowing is a simple application example:
 167
 168 #include <stdio.h>
 169 #include <glib.h>
 170
 171 #include "bluetooth.h"
 172
 173 GMainLoop *loop;
 174 GIOChannel *channel;
 175
 176 int main(int argc, char **argv)
 177 {
 178         int ret;
 179
 180 #if (GLIB_MAJOR_VERSION <= 2 && GLIB_MINOR_VERSION < 36)
 181         g_type_init();
 182 #endif
 183
 184         loop = g_main_loop_new(NULL, FALSE);
 185
 186         ret = bt_initialize();
 187         if (ret != BT_SUCCESS) {
 188                 printf("initialize bluetooth framework failed %d", ret);
 189                 return -1;
 190         }
 191
 192         ret = bt_adapter_enable();
 193         if (ret != BT_SUCCESS) {
 194                 printf("enable bluetooth adapter failed %d", ret);
 195                 return -1;
 196         }
 197
 198         printf("enable bluetooth adapter success");
 199
 200         g_main_loop_run(loop);
 201
 202         return 0;
 203 }
 204
 205 Information
 206 ===========
 207
 208 For additional information, contact:
 209         martin.xu@intel.com
 210         wu.zheng@intel.com
 211         jiangbox.wu@intel.com