Changes between Initial Version and Version 1 of wireless/bleproject


Ignore:
Timestamp:
07/09/2020 09:07:52 PM (2 years ago)
Author:
Ryan Erbstoesser
Comment:

initial page

Legend:

Unmodified
Added
Removed
Modified
  • wireless/bleproject

    v1 v1  
     1
     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.
     14
     15To read more about Bluetooth 5, view the following link:
     16https://www.bluetooth.com/blog/exploring-bluetooth-5-going-the-distan
     17ce/
     18
     19To look further in depth at how Bluetooth 5 accomplishes these
     20improvements, look at the following link:
     21https://e2e.ti.com/blogs_/b/process/archive/2017/01/30/how-does-bluet
     22ooth-5-increase-the-achievable-range-of-a-bluetooth-low-energy-connec
     23tion
     24
     25'''The Bluetooth Core Spec'''
     26
     27Bluetooth developers may want to familiarize themselves with the
     28Bluetooth Core Spec, which can be viewed here:
     29https://www.bluetooth.com/specifications/bluetooth-core-specification
     30/
     31
     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)
     40
     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
     45connections.
     46
     47'''Installation'''
     48
     49On Ubuntu, the Bluez library can be installed with:
     50{{{
     51apt-get install bluez
     52}}}
     53To use the Bluez developer library, compile your code with
     54{{{-lbluetooth}}}, which can be installed on ubuntu with:
     55{{{
     56apt-get install libbluetooth-dev
     57}}}
     58
     59'''Installing Bluez from Source'''
     60
     61Installing Bluez from source provides access to example code and some
     62developer tools.
     63
     64Install the necessary dependencies:
     65{{{
     66sudo apt-get install libglib2.0-dev libdbus-1-dev libudev-dev
     67libical-dev libreadline-dev
     68}}}
     69
     70Download and install:
     71{{{
     72wget https://www.kernel.org/pub/linux/bluetooth/bluez-5.53.tar.xz
     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
     77--enable-maintainer-mode
     78make
     79sudo make install
     80sudo cp attrib/gatttool /usr/bin
     81}}}
     82
     83'''Bluez CLI Tools'''
     84
     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
     90
     91'''Sending HCI Commands with Bluez'''
     92
     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:
     97
     98{{{
     99hcitool cmd <OGF> <OCF> <Param1> <Param2> <Param…>
     100}}}
     101
     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
     105
     106'''Additional Bluez Links'''
     107
     108Bluetooth C Programming Quickstart:
     109http://docs.cubieboard.org/tutorials/common/development/bluez_programming
     110
     111Navigating the Bluez Source Code:
     112https://gbrault.github.io/gattclient/hci__lib_8h.html
     113
     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:
     119http://trac.gateworks.com/wiki/expansion/gw16126#BluetoothHCIGW16126
     120
     121'''Bluez Configuration'''
     122
     123Before continuing, you may want to edit your
     124{{{
     125/etc/bluetooth/main.conf
     126}}}
     127file to the desired values. It is recommended that you set the DiscoverableTimeout and PairableTimeout to 0 to disable them for testing purposes.
     128
     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]# }}}
     133
     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:
     137{{{
     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
     146}}}
     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:
     149{{{
     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
     154}}}
     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}}}
     159
     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
     176
     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)
     202
     203'''Troubleshooting'''
     204
     205* Run btmon in the background to monitor HCI communications with the Bluetooth controller. Rerun the commands and view the output.
     206
     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.
     212
     213'''What is GATT?'''
     214
     215GATT defines a method of communication among BLE devices using
     216services and characteristics.
     217
     218For more information on GATT see:
     219https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt
     220
     221=== GATT Client/Server Example ===
     222
     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:
     226{{{
     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
     233}}}
     234
     235In your Bluez source directory, make the executable and start the
     236server with the following command:
     237
     238{{{tools/btgatt-server -i hci0 -s low -t random -r -v}}}
     239
     240Start the client with the following command:
     241
     242{{{tools/btgatt-client -i hci0 -s low -t random -v -d <Server MAC>}}}
     243
     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}}}
     246
     247The source code can also be viewed here:
     248* Server:
     249 * https://github.com/Vudentz/BlueZ/blob/master/tools/btgatt-server.c
     250* Client:
     251 * https://github.com/Vudentz/BlueZ/blob/master/tools/btgatt-client.c
     252
     253
     254= Creating and Connecting to an Azure MySQL Database =
     255
     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):
     258https://docs.microsoft.com/en-us/azure/mysql/quickstart-create-mysql-server-database-using-azure-portal
     259
     260'''Connecting to the database server'''
     261
     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:
     263https://docs.microsoft.com/en-us/azure/sql-database/sql-database-firewall-confi
     264gure
     265
     266To connect the the server using a Gateworks SBC and Ubuntu Linux, run the following command to install MySQL support:
     267
     268{{{
     269apt-get install mysql-server
     270}}}
     271
     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:
     273{{{
     274mysql --host mydemoserver.mysql.database.azure.com --user myadmin@mydemoserver -p
     275}}}
     276
     277This will prompt for a password and then start a MySQL command shell.
     278
     279Once connected, use MySQL commands to create and select a database, add tables,
     280and insert data. Example queries can be found here:
     281https://dev.mysql.com/doc/refman/8.0/en/creating-database.html
     282
     283'''Connecting to the database using Python on SBC with Ubuntu'''
     284
     285Python programs can also connect and query the database.
     286
     287Run the commands below to install python and set up the {{{pymysql}}} library:
     288{{{
     289apt-get install python3
     290pip install pymysql
     291}}}
     292
     293Code from the example shown below can be run in a Python shell or script:
     294{{{
     295#!/usr/bin/python3
     296import pymysql
     297# Open database connection
     298db = pymysql.connect("mydemoserver.mysql.database.azure.com",
     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 (
     306FIRST_NAME CHAR(20) NOT NULL,
     307LAST_NAME CHAR(20),
     308AGE INT,
     309SEX CHAR(1),
     310INCOME FLOAT )"""
     311cursor.execute(sql)
     312# disconnect from server
     313db.close()
     314}}}
     315
     316More resources for using the pymysql library are given here:
     317https://www.tutorialspoint.com/python3/python_database_access.htm
     318
     319'''Connecting to the database using C API:'''
     320
     321To write programs using C which access the MySQL database, install the following packages:
     322{{{
     323apt-get install build-essential mysql-server libmysqlclient-dev
     324}}}
     325
     326Create a C file with the following code example, replacing the database information to match the MySQL server created using Azure:
     327{{{
     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 = “mydemoserver.mysql.database.azure.com”;
     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;
     346}
     347/* send SQL query */
     348if (mysql_query(conn, "SHOW TABLES;")) {
     349fprintf(stderr, "%s\n", mysql_error(conn));
     350exit(1);
     351}
     352res = mysql_use_result(conn);
     353while ((row = mysql_fetch_row(res)) != NULL)
     354printf("%s \n", row[0]);
     355/* close connection */
     356mysql_free_result(res);
     357mysql_close(conn);
     358}
     359}}}
     360
     361Compile using the program using:
     362{{{
     363gcc {filename.c} -o {executable} `mysql_config --cflags --libs`
     364}}}
     365
     366Alternatively, run the command below and copy and append the output after the
     367executable.
     368{{{
     369mysql_config --cflags --libs
     370}}}
     371
     372
     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.
     375
     376'''Download Visual Studio and MySQL:'''
     377
     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.
     379
     380Download Visual Studio\\
     381[https://visualstudio.microsoft.com/downloads/ Visual Studio Download]
     382
     383Download MySQL for Visual Studio Extension\\
     384[https://dev.mysql.com/downloads/windows/visualstudio/ MySQL Extension]
     385
     386If you have a Mac, download MySQL\\
     387[https://dev.mysql.com/downloads/mysql/ MySQL Download]
     388
     389'''Connect to Github in Visual Studio'''
     390
     391To access the project's web app code, clone it from Github. Visual Studio connects with Github which allows for easy version control.
     392
     393Connect to the Github repository for the project\\
     394[https://github.com/alexissperalta/ReachWebApp Web App Repository]
     395
     396Windows:
     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.
     404Mac:
     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.
     413
     414'''Connect to the Database:'''
     415
     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.
     425
     426'''Running the code:'''
     427
     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.