Changes between Initial Version and Version 1 of wireless/bleproject

07/09/2020 09:07:52 PM (2 years ago)
Ryan Erbstoesser

initial page


  • wireless/bleproject

    v1 v1  
     2= Bluetooth 5 and BLE =
     3== Introduction ==
     4=== About Bluetooth 5 ===
     5Bluetooth 5 offers considerable improvements to its data bandwidth
     6and operational range compared to its predecessors. For high data
     7bandwidth applications, bluetooth v4.2 was capable of up to 1Mbps
     8whereas v5 doubles this speed at a maximum rate of 2Mbps. At reduced
     9bandwidth, Bluetooth LE Coded PHY, a new PHY mode offered by
     10Bluetooth 5, provides an operational range of around 800ft. This is a
     11roughly four times range increase from v4.2. Additional benefits of
     12Bluetooth 5, in some cases, will reduce power consumption compared to
     13its predecessors.
     15To read more about Bluetooth 5, view the following link:
     19To look further in depth at how Bluetooth 5 accomplishes these
     20improvements, look at the following link:
     25'''The Bluetooth Core Spec'''
     27Bluetooth developers may want to familiarize themselves with the
     28Bluetooth Core Spec, which can be viewed here:
     32This spec details every operation available to Bluetooth developers.
     33Some important sections for Bluetooth development using GateWorks
     34boards include the following:
     35* ''Vol 4, Part E'': Host Controller Interface (HCI) Functional Spec (p.1794) - Describes the command interface to a Bluetooth Controller
     36* ''5.4.1'': HCI Command Packet Descriptions (p.1890) – Command descriptions and packet formats to send to the controller
     37* ''7.7'': HCI Events (p.2289) – List of events triggered by the controller
     38* ''7.8'': LE Controller Commands (p.2473) – Commands for configuring and modifying LE connections
     39* ''Vol 1, Part F'': Controller Error Codes – Details the error codes provided by the controller (p.361)
     41== Bluez ==
     42Bluez is the primary Bluetooth library for developing Bluetooth
     43applications in C on Linux. It provides several command line tools as
     44well as function calls for setting up and managing Bluetooth
     49On Ubuntu, the Bluez library can be installed with:
     51apt-get install bluez
     53To use the Bluez developer library, compile your code with
     54{{{-lbluetooth}}}, which can be installed on ubuntu with:
     56apt-get install libbluetooth-dev
     59'''Installing Bluez from Source'''
     61Installing Bluez from source provides access to example code and some
     62developer tools.
     64Install the necessary dependencies:
     66sudo apt-get install libglib2.0-dev libdbus-1-dev libudev-dev
     67libical-dev libreadline-dev
     70Download and install:
     73tar xvf bluez-5.53.tar.xz
     74cd bluez-5.53
     75./configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc
     76--localstatedir=/var --disable-systemd --enable-experimental
     79sudo make install
     80sudo cp attrib/gatttool /usr/bin
     83'''Bluez CLI Tools'''
     85Here are a few of the provided command line tools:
     86* ''bluetoothctl'': The best introduction to Bluez. It provides a relatively easy to use CLI for running scans and pairing devices. It is not as great for running custom applications or commands.
     87* ''btmgmgt'': Used for Bluez management
     88* ''hciconfig'': Sends configuration commands to the Bluetooth controller
     89* ''hcitool'': Configures Bluetooth connections and allows sending special or custom commands to the Bluetooth controller
     91'''Sending HCI Commands with Bluez'''
     93Bluez allows users to send custom HCI packets to the Bluetooth
     94controller using hcitool. Available commands and more information
     95about HCI can be found in the Bluetooth Core Spec. The commands can
     96be sent with hcitool in the following format:
     99hcitool cmd <OGF> <OCF> <Param1> <Param2> <Param…>
     102i. OGF = OpCode Group Field (6 bits): Specific to a command's group
     103ii. OCF = OpCode Command Field (10 bits): Specifies the command within its grouping
     104iii. Parameters = Specific the command as defined in the Bluetooth Core Spec
     106'''Additional Bluez Links'''
     108Bluetooth C Programming Quickstart:
     111Navigating the Bluez Source Code:
     114== Connecting GW16126 With Devices Using Bluez ==
     115'''Initial Setup'''
     116Follow the setup instructions for the GW16126 u-blox BLE module to
     117setup the module as an available Bluetooth Interface. This can be
     118found at:
     121'''Bluez Configuration'''
     123Before continuing, you may want to edit your
     127file to the desired values. It is recommended that you set the DiscoverableTimeout and PairableTimeout to 0 to disable them for testing purposes.
     129=== Setting Up a Connection ===
     130'''Using bluetoothctl'''
     1311. Start {{{bluetoothctl}}}
     132If your controller is set up properly, the first thing to display should be the MAC address of your Bluetooth controller. Bluetoothctl will then provide a prompt {{{[bluetooth]# }}}
     1342. Run {{{show}}} This should list the configuration information for your Bluetooth controller.
     1353. Run {{{devices}}} This provides the user with a list of available devices. If you have not scanned yet, this list may be empty except for your own Bluetooth controller.
     1364. To enable the controller and prepare for pairing with a device, run the following:
     138[bluetooth]# power on
     139Changing power on succeeded
     140[bluetooth]# agent on
     141Agent is already registered
     142[bluetooth]# discoverable on
     143Changing discoverable on succeeded
     144[bluetooth]# pairable on
     145Changing pairable on succeeded
     1475. To search for available Bluetooth devices, enable scanning with {{{scan on}}} This will begin listing all devices transmitting within range. Turn this off anytime with {{{scan off}}}
     1486. Once you find the device in the scanning list, trust the MAC address and then connect:
     150[bluetooth]# trust XX:XX:XX:XX:XX:XX
     151Changing XX:XX:XX:XX:XX:XX trust succeeded
     152[bluetooth]# connect XX:XX:XX:XX:XX:XX
     153Attempting to connect to XX:XX:XX:XX:XX:XX
     1557. If the connection is successful, run {{{info XX:XX:XX:XX:XX:XX}}} to see information about the device you are connected to.
     1568. {{{quit}}}
     157''Tip: Known MAC addresses can be tab completed in Bluetoothctl.'' Note: To automate bluetoothctl commands try using
     158{{{bluetoothctl -–command}}}
     160'''Using hcitool'''
     1611. Run the init scripts to setup the HCI interface (if you have not already)
     1622. Scan for the desired MAC address
     163{{{hcitool -i hci0 lescan | grep <desired MAC>}}}
     164a. MAC in format XX:XX:XX:XX:XX:XX
     1653. Start the connection
     166{{{hcitool -i hci0 lecc --random <desired MAC>}}}
     167'''Using LE Coded PHY'''
     1681. Run init scripts to setup your HCI UART connection (if you have not already)
     1692. Inactive Connection:
     170 1. Set the default PHY on each board to Coded PHY {{{hcitool cmd 0x08 31 00 04 04}}}
     171 1. See '''Setting Up a Connection'''
     1723. Active Connection:
     173 1. Get the connection handle {{{hcitool -i hci0 leinfo --random <Connected MAC>}}}
     174 1. Change the connection PHY type {{{hcitool cmd 0x08 32 <connection handle> 00 04 04}}}
     175i. Connection Handle: 2 bytes in range 0x0000 to 0x0EFF
     177'''Useful Commands''':
     178* LE Set Default PHY (BCS p.2571): Sets the default PHY for either Tx or Rx on the Bluetooth controller.
     179* OGF = 0x08
     180* OCF = 0x0031
     181* All PHYs (1 byte)
     182* B0: 0 to set a Tx Preference
     183* B1: 0 to set a Rx Preference
     184* TX PHYs (1 byte)
     185* B0: 1Mbbs Tx PHY
     186* B1: 2Mbps Tx PHY
     187* B2: Coded Tx PHY
     188* RX PHYs (1 byte)
     189* B0: 1Mbps Rx PHY
     190* B1: 2Mbps Rx PHY
     191* B2: Coded Rx PHY
     192* LE Set PHY (BCS p.2573): Sets the default PHY for an active connection for either Tx or Rx on the Bluetooth controller.
     193* OGF = 0x08
     194* OCF = 0x0032
     195* Connection Handle (12 bits)
     196* All PHYs (1 byte)
     197* TX PHYs (1 byte)
     198* RX PHYs (1 byte)
     199* Response Values: These commands respond with a Command Complete Event (BCS p.2308) which provides two possible values
     200 * 0x00 = Success
     201 * Other = Controller Error Code (BCS p.361)
     205* Run btmon in the background to monitor HCI communications with the Bluetooth controller. Rerun the commands and view the output.
     207{{{btmon &}}}
     208== Setting up a GATT !Client/Server ==
     209This section talks about setting up a generic Bluetooth GATT
     210client/server model in which a client can connect to a Bluetooth
     211server and relay information to it.
     213'''What is GATT?'''
     215GATT defines a method of communication among BLE devices using
     216services and characteristics.
     218For more information on GATT see:
     221=== GATT Client/Server Example ===
     223An example GATT Client and Server is provided in the Bluez source
     224code, see '''Installing Bluez from Source''' to get the source code.
     225Before starting the server, run the following:
     227sudo btmgmt -i hci0 power off
     228sudo btmgmt -i hci0 le on
     229sudo btmgmt -i hci0 connectable on
     230sudo btmgmt -i hci0 name "some friendly name"
     231sudo btmgmt -i hci0 advertising on
     232sudo btmgmt -i hci0 power on
     235In your Bluez source directory, make the executable and start the
     236server with the following command:
     238{{{tools/btgatt-server -i hci0 -s low -t random -r -v}}}
     240Start the client with the following command:
     242{{{tools/btgatt-client -i hci0 -s low -t random -v -d <Server MAC>}}}
     244''Note: Before starting the client in a Linux environment, you may need to run a scan with hcitool to configure the controller correctly.''
     245{{{hcitool lescan}}}
     247The source code can also be viewed here:
     248* Server:
     249 *
     250* Client:
     251 *
     254= Creating and Connecting to an Azure MySQL Database =
     256'''Setup Azure MySQL Database Server'''
     257Follow the most recent instructions to create a MySQL database with Azure using the web portal (Azure account necessary):
     260'''Connecting to the database server'''
     262The database server can be accessed from any computer with internet connection and a verified IP address. Verified IP addresses can be added to the server under the 'Connection Security' option:
     266To connect the the server using a Gateworks SBC and Ubuntu Linux, run the following command to install MySQL support:
     269apt-get install mysql-server
     272Run the following command to login to the MySQL database server, replacing the server name and username to match the database server created using Azure:
     274mysql --host --user myadmin@mydemoserver -p
     277This will prompt for a password and then start a MySQL command shell.
     279Once connected, use MySQL commands to create and select a database, add tables,
     280and insert data. Example queries can be found here:
     283'''Connecting to the database using Python on SBC with Ubuntu'''
     285Python programs can also connect and query the database.
     287Run the commands below to install python and set up the {{{pymysql}}} library:
     289apt-get install python3
     290pip install pymysql
     293Code from the example shown below can be run in a Python shell or script:
     296import pymysql
     297# Open database connection
     298db = pymysql.connect("",
     299"myadmin@mydemoserver","test123","TESTDB" )
     300# prepare a cursor object using cursor() method
     301cursor = db.cursor()
     302# Drop table if it already exist using execute() method.
     303cursor.execute("DROP TABLE IF EXISTS EMPLOYEE")
     304# Create table as per requirement
     305sql = """CREATE TABLE EMPLOYEE (
     307LAST_NAME CHAR(20),
     308AGE INT,
     309SEX CHAR(1),
     310INCOME FLOAT )"""
     312# disconnect from server
     316More resources for using the pymysql library are given here:
     319'''Connecting to the database using C API:'''
     321To write programs using C which access the MySQL database, install the following packages:
     323apt-get install build-essential mysql-server libmysqlclient-dev
     326Create a C file with the following code example, replacing the database information to match the MySQL server created using Azure:
     328#include "mysqldb.h"
     329#include <stdio.h>
     330#include <stdlib.h>
     331#include <mysql.h>
     332int main() {
     333MYSQL *conn = NULL;
     334MYSQL_RES *res = NULL;
     335MYSQL_ROW row;
     336char *srv = “”;
     337char *usr = “myadmin@mydemoserver”;
     338char *psswrd = “test123”;
     339char *db = “TESTBD”;
     340/* Connect to database */
     341conn = mysql_init(NULL);
     342if (!mysql_real_connect(conn, srv,
     343usr, psswrd, db, 0, NULL, 0)) {
     344fprintf(stderr, "%s\n", mysql_error(conn));
     345return NULL;
     347/* send SQL query */
     348if (mysql_query(conn, "SHOW TABLES;")) {
     349fprintf(stderr, "%s\n", mysql_error(conn));
     352res = mysql_use_result(conn);
     353while ((row = mysql_fetch_row(res)) != NULL)
     354printf("%s \n", row[0]);
     355/* close connection */
     361Compile using the program using:
     363gcc {filename.c} -o {executable} `mysql_config --cflags --libs`
     366Alternatively, run the command below and copy and append the output after the
     369mysql_config --cflags --libs
     373= Web App
     374The web app for this project shows data from a Microsoft Azure MySQL database. It is an ASP.NET application that runs on your browser of choice.
     376'''Download Visual Studio and MySQL:'''
     378To work with this project you will need Visual Studio and and MySQL extension for Visual Studio so the web app can interface with the database.
     380Download Visual Studio\\
     381[ Visual Studio Download]
     383Download MySQL for Visual Studio Extension\\
     384[ MySQL Extension]
     386If you have a Mac, download MySQL\\
     387[ MySQL Download]
     389'''Connect to Github in Visual Studio'''
     391To access the project's web app code, clone it from Github. Visual Studio connects with Github which allows for easy version control.
     393Connect to the Github repository for the project\\
     394[ Web App Repository]
     3971. Fork the project into your own account.
     3982. Open Visual Studio.
     3993. Click Continue without Code.
     4004. From Team Explorer, click the Manage Connections button.
     4015. Under GitHub, click Connect. Complete the process to sign in to your GitHub account.
     4026. Click Clone.
     4037. Select the project cloned earlier and click Clone.
     4051. Fork the project into your own account
     4062. Open Visual Studio
     4073. Click Continue without Code
     4084. In the Menu bar, select Version Control > Checkout:
     4095. Go to Connect to Repository tab
     4106. On the GitHub page of the remote repository, press the Clone or Download button and copy the URL provided
     4117. Replace all the text in the URL entry field in the Connect to Repository tab. This will populate most other fields in this tab for you.
     4128. Enter the directory that you want to clone the repo into and press Checkout.
     414'''Connect to the Database:'''
     416Once the project is running on visual studio connect to your database, using the MySQL extension. This will allow the web app to display the information in your database. Connecting to the database through Server Explorer allows MySQL to establish a connection to the MySQL database, and the Web.Config file establishes the Azure connection.
     4171. Server Explorer
     4182. Add connection (This info comes from the database page on Azure.)
     419 1. Server Name
     420 1. Username
     421 1. Password
     422 1. Database
     4233. Change the connection string in Web.Config to the connection string for your database. The connection string is on the Azure page, under connection strings. Use the Web App connection string.
     424 1. Fill in the database and password in the connection string with the database name and password for your database.
     426'''Running the code:'''
     428Run the code by clicking the play button at the top. You can set up the application to run on a specific browser through Visual Studio. The Web App will run for as long as the page is open, and should update with information from the system in real-time.