Changes between Initial Version and Version 1 of wireless/bleproject

Timestamp:

07/09/2020 09:07:52 PM (4 years ago)

Author:

Ryan Erbstoesser

Comment:

initial page

wireless/bleproject

@@ +1 @@
+
+= Bluetooth 5 and BLE =
+== Introduction ==
+=== About Bluetooth 5 ===
+Bluetooth 5 offers considerable improvements to its data bandwidth
+and operational range compared to its predecessors. For high data
+bandwidth applications, bluetooth v4.2 was capable of up to 1Mbps
+whereas v5 doubles this speed at a maximum rate of 2Mbps. At reduced
+bandwidth, Bluetooth LE Coded PHY, a new PHY mode offered by
+Bluetooth 5, provides an operational range of around 800ft. This is a
+roughly four times range increase from v4.2. Additional benefits of
+Bluetooth 5, in some cases, will reduce power consumption compared to
+its predecessors.
+
+To read more about Bluetooth 5, view the following link:
+https://www.bluetooth.com/blog/exploring-bluetooth-5-going-the-distan
+ce/
+
+To look further in depth at how Bluetooth 5 accomplishes these
+improvements, look at the following link:
+https://e2e.ti.com/blogs_/b/process/archive/2017/01/30/how-does-bluet
+ooth-5-increase-the-achievable-range-of-a-bluetooth-low-energy-connec
+tion
+
+'''The Bluetooth Core Spec'''
+
+Bluetooth developers may want to familiarize themselves with the
+Bluetooth Core Spec, which can be viewed here:
+https://www.bluetooth.com/specifications/bluetooth-core-specification
+/
+
+This spec details every operation available to Bluetooth developers.
+Some important sections for Bluetooth development using GateWorks
+boards include the following:
+* ''Vol 4, Part E'': Host Controller Interface (HCI) Functional Spec (p.1794) - Describes the command interface to a Bluetooth Controller
+* ''5.4.1'': HCI Command Packet Descriptions (p.1890) – Command descriptions and packet formats to send to the controller
+* ''7.7'': HCI Events (p.2289) – List of events triggered by the controller
+* ''7.8'': LE Controller Commands (p.2473) – Commands for configuring and modifying LE connections
+* ''Vol 1, Part F'': Controller Error Codes – Details the error codes provided by the controller (p.361)
+
+== Bluez ==
+Bluez is the primary Bluetooth library for developing Bluetooth
+applications in C on Linux. It provides several command line tools as
+well as function calls for setting up and managing Bluetooth
+connections.
+
+'''Installation'''
+
+On Ubuntu, the Bluez library can be installed with:
+{{{
+apt-get install bluez
+}}}
+To use the Bluez developer library, compile your code with
+{{{-lbluetooth}}}, which can be installed on ubuntu with:
+{{{
+apt-get install libbluetooth-dev
+}}}
+
+'''Installing Bluez from Source'''
+
+Installing Bluez from source provides access to example code and some
+developer tools.
+
+Install the necessary dependencies:
+{{{ 
+sudo apt-get install libglib2.0-dev libdbus-1-dev libudev-dev
+libical-dev libreadline-dev 
+}}}
+
+Download and install:
+{{{
+wget https://www.kernel.org/pub/linux/bluetooth/bluez-5.53.tar.xz
+tar xvf bluez-5.53.tar.xz
+cd bluez-5.53
+./configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc
+--localstatedir=/var --disable-systemd --enable-experimental
+--enable-maintainer-mode
+make
+sudo make install
+sudo cp attrib/gatttool /usr/bin
+}}}
+
+'''Bluez CLI Tools'''
+
+Here are a few of the provided command line tools:
+* ''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.
+* ''btmgmgt'': Used for Bluez management
+* ''hciconfig'': Sends configuration commands to the Bluetooth controller
+* ''hcitool'': Configures Bluetooth connections and allows sending special or custom commands to the Bluetooth controller
+
+'''Sending HCI Commands with Bluez'''
+
+Bluez allows users to send custom HCI packets to the Bluetooth
+controller using hcitool. Available commands and more information
+about HCI can be found in the Bluetooth Core Spec. The commands can
+be sent with hcitool in the following format:
+
+{{{
+hcitool cmd <OGF> <OCF> <Param1> <Param2> <Param…>
+}}}
+
+i. OGF = OpCode Group Field (6 bits): Specific to a command's group
+ii. OCF = OpCode Command Field (10 bits): Specifies the command within its grouping
+iii. Parameters = Specific the command as defined in the Bluetooth Core Spec
+
+'''Additional Bluez Links'''
+
+Bluetooth C Programming Quickstart:
+http://docs.cubieboard.org/tutorials/common/development/bluez_programming
+
+Navigating the Bluez Source Code:
+https://gbrault.github.io/gattclient/hci__lib_8h.html
+
+== Connecting GW16126 With Devices Using Bluez ==
+'''Initial Setup'''
+Follow the setup instructions for the GW16126 u-blox BLE module to
+setup the module as an available Bluetooth Interface. This can be
+found at:
+http://trac.gateworks.com/wiki/expansion/gw16126#BluetoothHCIGW16126
+
+'''Bluez Configuration'''
+
+Before continuing, you may want to edit your
+{{{
+/etc/bluetooth/main.conf
+}}} 
+file to the desired values. It is recommended that you set the DiscoverableTimeout and PairableTimeout to 0 to disable them for testing purposes.
+
+=== Setting Up a Connection ===
+'''Using bluetoothctl'''
+1. Start {{{bluetoothctl}}}
+If 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]# }}}
+
+2. Run {{{show}}} This should list the configuration information for your Bluetooth controller.
+3. 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.
+4. To enable the controller and prepare for pairing with a device, run the following:
+{{{
+[bluetooth]# power on
+Changing power on succeeded
+[bluetooth]# agent on
+Agent is already registered
+[bluetooth]# discoverable on
+Changing discoverable on succeeded
+[bluetooth]# pairable on
+Changing pairable on succeeded
+}}}
+5. 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}}}
+6. Once you find the device in the scanning list, trust the MAC address and then connect:
+{{{
+[bluetooth]# trust XX:XX:XX:XX:XX:XX
+Changing XX:XX:XX:XX:XX:XX trust succeeded
+[bluetooth]# connect XX:XX:XX:XX:XX:XX
+Attempting to connect to XX:XX:XX:XX:XX:XX
+}}}
+7. If the connection is successful, run {{{info XX:XX:XX:XX:XX:XX}}} to see information about the device you are connected to.
+8. {{{quit}}}
+''Tip: Known MAC addresses can be tab completed in Bluetoothctl.'' Note: To automate bluetoothctl commands try using
+{{{bluetoothctl -–command}}}
+
+'''Using hcitool'''
+1. Run the init scripts to setup the HCI interface (if you have not already)
+2. Scan for the desired MAC address
+{{{hcitool -i hci0 lescan | grep <desired MAC>}}}
+a. MAC in format XX:XX:XX:XX:XX:XX
+3. Start the connection
+{{{hcitool -i hci0 lecc --random <desired MAC>}}}
+'''Using LE Coded PHY'''
+1. Run init scripts to setup your HCI UART connection (if you have not already)
+2. Inactive Connection:
+ 1. Set the default PHY on each board to Coded PHY {{{hcitool cmd 0x08 31 00 04 04}}}
+ 1. See '''Setting Up a Connection'''
+3. Active Connection:
+ 1. Get the connection handle {{{hcitool -i hci0 leinfo --random <Connected MAC>}}}
+ 1. Change the connection PHY type {{{hcitool cmd 0x08 32 <connection handle> 00 04 04}}}
+i. Connection Handle: 2 bytes in range 0x0000 to 0x0EFF
+
+'''Useful Commands''':
+* LE Set Default PHY (BCS p.2571): Sets the default PHY for either Tx or Rx on the Bluetooth controller.
+* OGF = 0x08
+* OCF = 0x0031
+* All PHYs (1 byte)
+* B0: 0 to set a Tx Preference
+* B1: 0 to set a Rx Preference
+* TX PHYs (1 byte)
+* B0: 1Mbbs Tx PHY
+* B1: 2Mbps Tx PHY
+* B2: Coded Tx PHY
+* RX PHYs (1 byte)
+* B0: 1Mbps Rx PHY
+* B1: 2Mbps Rx PHY
+* B2: Coded Rx PHY
+* LE Set PHY (BCS p.2573): Sets the default PHY for an active connection for either Tx or Rx on the Bluetooth controller.
+* OGF = 0x08
+* OCF = 0x0032
+* Connection Handle (12 bits)
+* All PHYs (1 byte)
+* TX PHYs (1 byte)
+* RX PHYs (1 byte)
+* Response Values: These commands respond with a Command Complete Event (BCS p.2308) which provides two possible values
+ * 0x00 = Success
+ * Other = Controller Error Code (BCS p.361)
+
+'''Troubleshooting'''
+
+* Run btmon in the background to monitor HCI communications with the Bluetooth controller. Rerun the commands and view the output.
+
+{{{btmon &}}}
+== Setting up a GATT !Client/Server ==
+This section talks about setting up a generic Bluetooth GATT
+client/server model in which a client can connect to a Bluetooth
+server and relay information to it.
+
+'''What is GATT?'''
+
+GATT defines a method of communication among BLE devices using
+services and characteristics.
+
+For more information on GATT see:
+https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt
+
+=== GATT Client/Server Example ===
+
+An example GATT Client and Server is provided in the Bluez source
+code, see '''Installing Bluez from Source''' to get the source code.
+Before starting the server, run the following:
+{{{
+sudo btmgmt -i hci0 power off
+sudo btmgmt -i hci0 le on
+sudo btmgmt -i hci0 connectable on
+sudo btmgmt -i hci0 name "some friendly name"
+sudo btmgmt -i hci0 advertising on
+sudo btmgmt -i hci0 power on
+}}}
+
+In your Bluez source directory, make the executable and start the
+server with the following command:
+
+{{{tools/btgatt-server -i hci0 -s low -t random -r -v}}}
+
+Start the client with the following command:
+
+{{{tools/btgatt-client -i hci0 -s low -t random -v -d <Server MAC>}}}
+
+''Note: Before starting the client in a Linux environment, you may need to run a scan with hcitool to configure the controller correctly.''
+{{{hcitool lescan}}}
+
+The source code can also be viewed here:
+* Server:
+ * https://github.com/Vudentz/BlueZ/blob/master/tools/btgatt-server.c
+* Client:
+ * https://github.com/Vudentz/BlueZ/blob/master/tools/btgatt-client.c
+
+
+= Creating and Connecting to an Azure MySQL Database =
+
+'''Setup Azure MySQL Database Server'''
+Follow the most recent instructions to create a MySQL database with Azure using the web portal (Azure account necessary):
+https://docs.microsoft.com/en-us/azure/mysql/quickstart-create-mysql-server-database-using-azure-portal
+
+'''Connecting to the database server'''
+
+The 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:
+https://docs.microsoft.com/en-us/azure/sql-database/sql-database-firewall-confi
+gure
+
+To connect the the server using a Gateworks SBC and Ubuntu Linux, run the following command to install MySQL support:
+
+{{{
+apt-get install mysql-server
+}}}
+
+Run the following command to login to the MySQL database server, replacing the server name and username to match the database server created using Azure:
+{{{
+mysql --host mydemoserver.mysql.database.azure.com --user myadmin@mydemoserver -p
+}}}
+
+This will prompt for a password and then start a MySQL command shell.
+
+Once connected, use MySQL commands to create and select a database, add tables,
+and insert data. Example queries can be found here:
+https://dev.mysql.com/doc/refman/8.0/en/creating-database.html
+
+'''Connecting to the database using Python on SBC with Ubuntu'''
+
+Python programs can also connect and query the database.
+
+Run the commands below to install python and set up the {{{pymysql}}} library:
+{{{
+apt-get install python3
+pip install pymysql
+}}}
+
+Code from the example shown below can be run in a Python shell or script:
+{{{
+#!/usr/bin/python3
+import pymysql
+# Open database connection
+db = pymysql.connect("mydemoserver.mysql.database.azure.com",
+"myadmin@mydemoserver","test123","TESTDB" )
+# prepare a cursor object using cursor() method
+cursor = db.cursor()
+# Drop table if it already exist using execute() method.
+cursor.execute("DROP TABLE IF EXISTS EMPLOYEE")
+# Create table as per requirement
+sql = """CREATE TABLE EMPLOYEE (
+FIRST_NAME CHAR(20) NOT NULL,
+LAST_NAME CHAR(20),
+AGE INT,
+SEX CHAR(1),
+INCOME FLOAT )"""
+cursor.execute(sql)
+# disconnect from server
+db.close()
+}}}
+
+More resources for using the pymysql library are given here:
+https://www.tutorialspoint.com/python3/python_database_access.htm
+
+'''Connecting to the database using C API:'''
+
+To write programs using C which access the MySQL database, install the following packages:
+{{{
+apt-get install build-essential mysql-server libmysqlclient-dev
+}}}
+
+Create a C file with the following code example, replacing the database information to match the MySQL server created using Azure:
+{{{
+#include "mysqldb.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <mysql.h>
+int main() {
+MYSQL *conn = NULL;
+MYSQL_RES *res = NULL;
+MYSQL_ROW row;
+char *srv = “mydemoserver.mysql.database.azure.com”;
+char *usr = “myadmin@mydemoserver”;
+char *psswrd = “test123”;
+char *db = “TESTBD”;
+/* Connect to database */
+conn = mysql_init(NULL);
+if (!mysql_real_connect(conn, srv,
+usr, psswrd, db, 0, NULL, 0)) {
+fprintf(stderr, "%s\n", mysql_error(conn));
+return NULL;
+}
+/* send SQL query */
+if (mysql_query(conn, "SHOW TABLES;")) {
+fprintf(stderr, "%s\n", mysql_error(conn));
+exit(1);
+}
+res = mysql_use_result(conn);
+while ((row = mysql_fetch_row(res)) != NULL)
+printf("%s \n", row[0]);
+/* close connection */
+mysql_free_result(res);
+mysql_close(conn);
+}
+}}}
+
+Compile using the program using:
+{{{
+gcc {filename.c} -o {executable} `mysql_config --cflags --libs`
+}}}
+
+Alternatively, run the command below and copy and append the output after the
+executable.
+{{{
+mysql_config --cflags --libs
+}}}
+
+
+= Web App
+The 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.
+
+'''Download Visual Studio and MySQL:'''
+
+To 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.
+
+Download Visual Studio\\
+[https://visualstudio.microsoft.com/downloads/ Visual Studio Download]
+
+Download MySQL for Visual Studio Extension\\
+[https://dev.mysql.com/downloads/windows/visualstudio/ MySQL Extension]
+
+If you have a Mac, download MySQL\\
+[https://dev.mysql.com/downloads/mysql/ MySQL Download]
+
+'''Connect to Github in Visual Studio'''
+
+To access the project's web app code, clone it from Github. Visual Studio connects with Github which allows for easy version control.
+
+Connect to the Github repository for the project\\
+[https://github.com/alexissperalta/ReachWebApp Web App Repository]
+
+Windows:
+1. Fork the project into your own account.
+2. Open Visual Studio.
+3. Click Continue without Code.
+4. From Team Explorer, click the Manage Connections button.
+5. Under GitHub, click Connect. Complete the process to sign in to your GitHub account.
+6. Click Clone.
+7. Select the project cloned earlier and click Clone.
+Mac:
+1. Fork the project into your own account
+2. Open Visual Studio
+3. Click Continue without Code
+4. In the Menu bar, select Version Control > Checkout:
+5. Go to Connect to Repository tab
+6. On the GitHub page of the remote repository, press the Clone or Download button and copy the URL provided
+7. 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.
+8. Enter the directory that you want to clone the repo into and press Checkout.
+
+'''Connect to the Database:'''
+
+Once 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.
+1. Server Explorer
+2. Add connection (This info comes from the database page on Azure.)
+ 1. Server Name
+ 1. Username
+ 1. Password
+ 1. Database
+3. 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.
+ 1. Fill in the database and password in the connection string with the database name and password for your database.
+
+'''Running the code:'''
+
+Run 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.