Bluetooth Low Energy is a standard for Low Power Wireless Networks introduced in the Bluetooth specification 4.0. Its target application domains include medical, sports & fitness, home automation and others. The adoption and development rates of this technology are growing fast helped by the wide availability of hardware support in most modern mobile phones and mobile operating systems.
The purpose of this application note is to show how the Freescale FRDM-KW40Z can board with BLE Controller software can be used with the hcitool from the Linux Bluetooth stack over the HCI interface.
1. Introduction
The Bluetooth specification has a very well defined interface between the Controller and the Host called the HCI (Host Controller Interface). This interface is defined for and can be used with various transport layers including an asynchronous serial transport layer.
A typical scenario of Bluetooth Low Energy hardware use is a development board which has a BLE Controller accessible via serial transport HCI connected to a device on which the BLE Host runs. The device which runs the BLE Host can be any type of embedded device or a PC. PCs running a Linux type OS can use the hcitool from the Linux Bluetooth Stack to interact with a BLE Controller via the HCI interface. The particular use case of FRDM-KW40Z board with a serial transport HCI interface running over USB CDC and connected to a PC running the Linux Bluetooth stack is shown in the diagram below and will be detailed din the following sections.
Figure 1FRDM-KW40Z (BLE Controller) connected to Linux PC (Bluetooth Host Stack) via HCI Serial Transport
2. Loading the HCI Application onto the FRDM-KW40Z
First load the hci_app on the FRDM-KW40Z board.
The hci_app aplication can be found in the <ConnectivitySwInstallationPath>\ConnSw\examples\bluetooth\hci_app folder.
3. Connecting the FRDM-KW40Z to the Computer via a Serial Port
After the app is downloaded to the board plug the board into a free USB port of your Linux computer.
The following instructions, commands and their output is typical to a Debian based Linux OS.
After the board is plugged in run the following command to list the serial ports available.
>> dmesg | grep tty
[ 0.000000] console [tty0] enabled
[ 2374.118201] cdc_acm 1-2:1.1: ttyACM0: USB ACM device
In our example the FRDM-KW40Z board serial port is ttyACM0.
To test the connection some HCI commands can be sent in hex format from any terminal application to the serial HCI on the FRDM-KW40Z board.
In the figure below an HCI_Read_BD_ADDR command and its corresponding Command Complete Event are shown as they were sent and received in hexadecimal format from the moserial serial terminal GUI application.
Figure 2: HCI command and response event in hexadecimal format (HCI UART Transport)
4. Connecting the HCI Serial Interface to the Bluetooth Stack
To connect the Linux Bluetooth stack to a serial HCI interface the hciattach command must be run as shown below.
>> hciattach /dev/ttyACM0 any 115200 noflow nosleep
Device setup complete
If the the HCI serial interface is successfully attached to the Bluetooth stack then the "Device setup complete" message is shown.
The any parameter specifies a generic Bluetooth device. The 115200 parameter is the UART baudrate. The noflow parameter diasables serial flow control. The nosleep parameter disables hardware specific power managment.
Run the hciconfig command with no parameters to check the HCI interface id of the newly attached HCI serial device.
>> hciconfig
hci1: Type: BR/EDR Bus: UART
BD Address: 00:04:9F:00:00:15 ACL MTU: 27:4 SCO MTU: 0:0
UP RUNNING
RX bytes:205 acl:0 sco:0 events:14 errors:0
TX bytes:112 acl:0 sco:0 commands:14 errors:0
hci0: Type: BR/EDR Bus: USB
BD Address: 90:00:4E:A4:70:97 ACL MTU: 310:10 SCO MTU: 64:8
UP RUNNING
RX bytes:595 acl:0 sco:0 events:37 errors:0
TX bytes:2564 acl:0 sco:0 commands:36 errors:0
In this example the FRDM-KW40Z is assigned the hci1 interface as can be seen from the bus type (Type: BR/EDR Bus: UART). The hci0 interface is the example shown corresponds to the on-board Bluetooth module from the machine.
On some systems the interface might need to be manually started by using the hciconfig interfaceId up command.
hciconfig hci1 up
5. Configuring the Bluetooth Device and Listing its Capabilities
The hciconfig command offers the possibility of configuring the device and listing the device capabilities.
To find all commands supported by the hciconfig tool type the following command.
>> hciconfig –h
...display supported commands...
Each individual hciconfig command must be addressed to the correct HCI interface as reported above. In our example we use the hci1 interface. Some hciconfig commands require root privileges and must be run with sudo (the "Operation not permitted(1)" error will be returned if a command needs to be run with root privileges).
Some useful hci config commands:
>> hciconfig hci1 version -> lists hci device verison information
>> hciconfig hci1 revision -> lists hci device revision information
>> hciconfig hci1 features -> lists the features supported by the device
>> hciconfig hci1 commands -> lists the hci commands supported by the device
>> sudo hciconfig hci1 lestates -> lists the BLE states supported by the device
>> sudo hciconfig hci1 lerandaddr 11:22:33:44:55:66 -> set a random address on the device
>> sudo hciconfig hci1 leadv 3 -> enable LE advertising of the specified type
>> sudo hciconfig hci1 noleadv -> disable LE advertising
Now the newly connected board with a serial HCI is attached to a HCI interface of the Bluetooth stack and is ready to use.
6. Controlling the Bluetooth Device using the hcitool
The hcitool can be used to send HCI commands to the Bluetooth device.
A command is available which lists all available hcitool actions.
>> hcitool -h
...display supported commands...
To target a specific HCI interface use the -i hciX option for an hcitool command. We will use -i hci1 in our examples.
The hcitool supports commands for common BLE HCI operations some of which are shown below and also supports sending generic HCI commands using a dedicated option which uses hexadecimal numbers for the OGF (Command Group), OCF (Command Code) and the parameters. The 6 bit OGF and the 10 bit OCF compose the 16 bit HCI Command Opcode. The command parameters are specific to each command.
6.1. Listing Devices Available to the hcitool
An hcitool command can list all available device interfaces.
>> hcitool dev
Devices:
hci1 00:04:9F:00:00:15
hci0 90:00:4E:A4:70:97
The device we are working with is connected to the hci1 interface as seen from the output of the hciconfig command used above.
6.2. Scanning for Advertising LE Devices
The hcitool can be used to perform a LE Device scan. This command requires root privileges.
Press Ctrl+C to stop the scan at any time.
>> sudo hcitool -i hci1 lescan
LE Scan ...
00:04:9F:00:00:13 (FSL_OTAC)
^C
A list of addresses and device names will be shown if advertised (<<Shortened Local Name>> or <<Complete Local Name>> as define din the specification).
6.3. Obtaining Remote LE Device Information Using the hcitool
To obtain information about a remote LE device a special hcitool command can be used. The hcitool leinfo command creates a connection, extracts information from the remote device and then disconnects. The remote device information is shown at the command prompt.
>> sudo hcitool -i hci1 leinfo 00:04:9F:00:00:13
Requesting information ...
Handle: 32 (0x0020)
LMP Version: 4.1 (0x7) LMP Subversion: 0x113
Manufacturer: Freescale Semiconductor, Inc. (511)
Features: 0x1f 0x00 0x00 0x00 0x00 0x00 0x00 0x00
In this example information about a device previously discovered using the hcitool lescan command is shown.
6.4. Connecting and Disconnecting from a Remote LE Device
Connecting to a remote LE device is done using the hcitool lecc command.
>> sudo hcitool -i hci1 lecc 00:04:9F:00:00:13
Connection handle 32
As before a previously discovered device address is used. If the connection is successful then the Connection Handle is returned and in our case the Connection Handle is 32.
The hcitool con command shows active connections information: address, connection handle, role, etc.
>> hcitool con
Connections:
< LE 00:04:9F:00:00:13 handle 32 state 1 lm MASTER
To end a LE connection the hcitool ledc command can be used. It must be provided with the Connection Handle to be terminated, and optionally the reason. The device handle obtained after the connection and shown in the connected devices list is used.
>> hcitool –I hci1 ledc 32
>>
Listing the connections after all connections are terminated will show an empty connection list.
>> hcitool con
Connections:
>>
6.5. Sending Arbitrary HCI Commands
To send arbitrary HCI commands to a device using the Command CopCode (OGF and OCF) the hcitool cmd command can be used.
As an example the HCI_Read_BD_ADDR command is used which has the 0x1009 OpCode (OGF=0x04, OCF=0x009) and no parameters. It is the same command shown in the direct serial port to HCI communication example above.
hcitool -i hci0 cmd 0x04 0x0009
< HCI Command: ogf 0x04, ocf 0x0009, plen 0
> HCI Event: 0x0e plen 10
01 09 10 00 15 00 00 9F 04 00
The OpCode OGF (0x04) and OCF (0x009) and no parameters are passed to the hcitool cmd command all in hexadecimal format. The parameters length (plen) is 0 for the command.
The response is a Command Complete event (0x03) with the parameters length (plen) 10. The parameters are 01 09 10 00 15 00 00 9F 04 00:
- 01 is the Num_HCI_Command_Packets parameter
- 09 10 is the Command OpCode for which this Command Complete Event is returned (in little endian format)
- 00 is the status – Success in this case
- 15 00 00 9F 04 00 is the BD_ADDR of the device as listed by the hcitool dev command
