BlueZ
This chapter covers the BlueZ stack on IoT Yocto and its common instructions. The Bluetooth stack depends on the module in use. BlueZ is compatible with the MT7921 module and other 3rd party modules support the Linux standard API.
Genio platforms support the BlueZ stack starting from v22.1. IoT Yocto currently supports GATT, HID, and HoGP profiles which are tested. While other profiles may be supported, MediaTek has not conducted full function tests for other profiles. However, you can still try the available commands for these profiles http://www.bluez.org/profiles. You can also read bluez how-to from other Linux distros, like https://ubuntu.com/core/docs/bluez/how-to
Bluetooth service
Ensure that bluetooth.service and bluetoothd are running
First, make sure bluetooth.service and bluetoothd is running.
Check bluetooth.service by systemctl.
systemctl status bluetooth.service
Check bluetoothd by ps.
ps -aux | grep bluetoothd
You should see 2 output lines correspond to each command respectively:
Active: active (running)
root 329 0.0 0.1 6952 4144 ? Ss 10:44 0:00 /usr/libexec/bluetooth/bluetoothd
If not, launch bluetooth.service when you see the following output:
The following output means bluetooth.service has been stopped.
* bluetooth.service - Bluetooth service
Loaded: loaded (/lib/systemd/system/bluetooth.service; disabled; vendor pr>
Active: inactive (dead)
Docs: man:bluetoothd(8)
Use systemctl to enable bluetooth.service.
systemctl enable bluetooth.service
Systemctl should register dbus-org.bluez.service and bluetooth.service to systemd and here’s the output.
Created symlink /etc/systemd/system/dbus-org.bluez.service -> /lib/systemd/system/bluetooth.service.
Created symlink /etc/systemd/system/bluetooth.target.wants/bluetooth.service -> /lib/systemd/system/bluetooth.service.
Then, don’t forget use systemctl to start bluetooth.service, and then check if it is running again.
systemctl start bluetooth.service
systemctl status bluetooth.service
Make Sure the hciX Controller Exists
Use hciconfig to check if the bluetooth controller exists.
hciconfig
A valid BD Address (MAC address of the bluetooth controller) should be existed as the output instead of value 00:00:00:00:00:00.
Note
The Bus type of hciX will be different depends on the module and the platform are used. It could be SDIO or USB usually.
hci0: Type: Primary Bus: USB
BD Address: 90:E8:68:D4:39:84 ACL MTU: 1021:6 SCO MTU: 244:4
DOWN
RX bytes:14464 acl:0 sco:0 events:1167 errors:0
TX bytes:293798 acl:0 sco:0 commands:1167 errors:0
Prepare test application for paired phone
Install the nRF Connect for Mobile application on your Android phone or iPhone.
Please note that the configuration and usage may differ between these two operating systems.
Basic operation
Scan some advertising bluetooth device nearby
Bluetooth device will be shown after scan on.
Bluetooth device will not be shown after scan off.
Start bluetoothctl to control the bluetooth interface interactively.
bluetoothctl
bluetoothctl will report the controller if there existed one.
Agent registered
[CHG] Controller 90:E8:68:D4:39:84 Pairable: yes
You’ll also find the prompt has been changed to [bluetooth]#, which means we are under the interactive interface and menu in bluetoothctl.
(waiting for bluetooth commands)
Before using bluetooth, we need to power on the device.
power on
If it is success, you’ll see the valid BD’s address in log with message Powered: yes.
The bluetooth controller is able to scan the neighbor devices now. Put the bluetooth speaker into pairing mode, then simply run:
scan on
Enable advertising on your device to make it discoverable during Bluetooth scanning
Start bluetoothctl to control the bluetooth interface interactively.
bluetoothctl
bluetoothctl will report the controller if there existed one.
Agent registered
[CHG] Controller 90:E8:68:D4:39:84 Pairable: yes
You’ll also find the prompt has been changed to [bluetooth]#, which means we are under the interactive interface and menu in bluetoothctl.
menu advertise
You’ll enter advertise menu and device will show available commands.
name bluetoothAdv
back
Set the advertise name of your device. Then leave advertise menu. back to menu main.
advertise peripheral
The device will advertise itself by bluetooth. You’ll see the result as follows.
[CHG] Controller 2C:3B:70:EB:14:82 SupportedInstances: 0x13 (19)
[CHG] Controller 2C:3B:70:EB:14:82 ActiveInstances: 0x01 (1)
Advertising object registered
Tx Power: off
LocalName: bluetoothdAdv
Appearance: off
Discoverable: on
Now launch the nRF Connect for Mobile on your phone, select SCANNER and then clock scan,
You’ll see the phone with name bluetoothAdv will appear on your phone.
HID and HOGP
Initiate connect to HID/HOGP device, and check data-input
Start bluetoothctl to control the bluetooth interface interactively.
bluetoothctl
bluetoothctl will report the controller if there existed one.
Agent registered
[CHG] Controller 90:E8:68:D4:39:84 Pairable: yes
You’ll also find the prompt has been changed to [bluetooth]#, which means we are under the interactive interface and menu in bluetoothctl.
(waiting for bluetooth commands)
Before using bluetooth, we need to power on the device.
power on
If it is success, you’ll see the valid BD’s address in log with message Powered: yes.
The bluetooth controller is able to scan the neighbor devices now. Put the bluetooth speaker into pairing mode, then simply run:
scan on
pair xx:xx:xx:xx:xx
connect xx:xx:xx:xx:xx
exit
Pair and connect EVK with the HID/HOGP device, while xx:xx:xx:xx:xx is the address of HID/HOGP Device.
After the device has been connected, leave bluetoothctl.
cd /dev/input
evtest eventX
Check every eventX(event0, event1…) from the HID or HOGP Device.
Initiate disconnect & unpair to HID/HOGP device
If you has exited the bluetootctl, please execute the bluetoothctl again.
devices
Command devices will show the Address of connected device.
disconnect xx:xx:xx:xx:xx (Address Of HID/HOGP Device)
remove xx:xx:xx:xx:xx (Address Of HID/HOGP Device)
Simply disconnet and remove the HID/HOGP device,
while xx:xx:xx:xx:xx is the address of HID/HOGP Device.
GATT
Initiate connect to GATT device, and check data-input
Start bluetoothctl to control the bluetooth interface interactively.
bluetoothctl
bluetoothctl will report the controller if there existed one.
Agent registered
[CHG] Controller 90:E8:68:D4:39:84 Pairable: yes
You’ll also find the prompt has been changed to [bluetooth]#, which means we are under the interactive interface and menu in bluetoothctl.
(waiting for bluetooth commands)
Before using bluetooth, we need to power on the device.
power on
If it is success, you’ll see the valid BD’s address in log with message Powered: yes.
The bluetooth controller is able to scan the neighbor devices now. Put the bluetooth speaker into pairing mode, then simply run:
scan on
Start Advertise
After completing the following procedures, the remote device will be able to discover the advertisement named ‘bluetoothAdv’.
Before you begin, ensure that you have a smartphone with the nRFConnect application installed.
For Android phones, use the nRFConnect.apk application.
For iPhones, use the nRFConnect application..
On the Genio platforms, enter the advertise menu to set the advertise name for the Genio EVK.
We set bluetoothAdv for the Genio platform.
On Genio platform:
menu advertise
name bluetoothAdv
back
advertise peripheral
On smartphone:
launch nRFConnect application
select "SACNNER"
click "scan"
Genio platform with name bluetoothAdv should appear on smartphone.
Set Advertisement Data for Device
On the Genio platforms, enter the advertise menu to set the advertise data for the Genio EVK.
The following example should be available on smartphone:
uuids:
0x181C,0x2a8aservice:
UUID:2a90 Data: 0x55data:
(0x33): 44tx-power:
TxPower Level: XX dBm
On Genio platform:
menu advertise
uuids 0000181c-0000-1000-8000-00805f9b34fb 00002a8a-0000-1000-8000-00805f9b34fb
service 00002a90-0000-1000-8000-00805f9b34fb 0x55
data 0x33 0x44
tx-power on
On smartphone:
launch nRFConnect application
select "SACNNER"
click "scan"
find & click the "bluetoothdAdv"
check advertised data
Connect and Disconnect with GATT server
To prepare testing environment on your smartphone, follow these steps.
On smartphone (Preparation):
Launch the nRFConnect app and start a connectable advertisement.
1. Launch nRFConnect application.
2. Select "ADVERTISER"
3. If you haven't created an advertiser before, select "+" to add one. If you have, skip this step.
Configure the advertiser:
1.a Select "Display name" and input a name.
1.b Select "ADD RECORD" and then "Complete Local Name".
This will be the advertisement name.
1.c Enable/Select "Connectable".
1.d Confirm by selecting "OK".
1.f Select the "Pen Symbol" in the upper right corner, input an easily recognizable name, and select "RENAME".
This step changes the "Complete Local Name" into an easily recognizable broadcast name.
4. Select the "adv open button", begain to start adv
On Genio platform:
Note
The Address from the command line prompt needs to be formatted as 5c:68:2e:3f:48:27.
If you cannot locate the device, use the devices command to find it.
Please note that the format of the address in the command line prompt (e.g., 5c-68-2e-3f-48-27) should be changed to 5c:68:2e:3f:48:27.
scan on
pair Address
On smartphone:
Click the "PAIR & CONNECTR " in phone, then click "PAIR".
On Genio platform, input “yes” to agree.
yes
On Genio platform, enter the advertise menu and show device’s address.
menu gatt
list-attributes
back
devices
disconnect Address
remove Address
After executing the “pair address” command, the console prompt name will be updated to reflect the device’s name. Once the “list-attributes address” command is run, the GATT service attribute list will be displayed. The console prompt name will revert back to “bluetooth” after the “disconnect address” command is executed.
Read Data from GATT Server
To prepare testing environment on your smartphone, follow these steps.
On smartphone (Preparation):
Configure the GATT service in the nRF app. If this has already been done, skip this step.
1. Launch nRFConnect application.
2. Select "Ξ".
3. Choose "Configure GATT server".
4. Click on "ADD SERVICE". If there is no "ADD SERVICE" option, select the "Triangle", then click on "+" to add a service.
To configure the service:
1. Click on "ADD SERVICE".
2. Select "Select server configuration", then choose "Custom service".
3. Fill in the "Name" (e.g., Myservice1) and "UUID" (e.g., 1234, must be 4 digits), then click "OK".
4. Click on "Myservice1", then select "ADD CHARACTERISTIC".
5. Fill in the "Name" (e.g., Myservice1-char1), "UUID" (e.g., 1235), select all options for Properties and Permissions,
select and fill in the "Text" for Initial value (e.g., Myservice3-char1 say hello!!), then click "OK".
6. Click on "ADD DESCRIPTOR".
7. Fill in the "Name" (e.g., Myservice1-char1-des1), "UUID" (e.g., 1236), select all options for Permissions,
select and fill in the "Text" for Initial value (e.g., Myservice1-char1-des1 say hello!!), then click "OK".
(If you want to configure more services/characteristics/descriptors, please repeat the above steps.)
On Genio platform:
Start a connectable advertisement. Please refer to section Start Advertise in this chapter for more details. After this step has been completed, execute the following steps.
Navigate to the
gattmenu.List the attributes using the
list-attributescommand.Select the attribute using the
select-attribute uuidcommand. Use the characteristic UUID (e.g., xxxx1235-xxxx-xxxx-xxxxx-xxxxxxxxxxx) or descriptor UUID (e.g., xxxx1235-xxxx-xxxx-xxxxx-xxxxxxxxxxx) that you created.Operate the characteristic or descriptor that you created.
Use the
attribute-infocommand to display the permissions. The characteristic or descriptor must supportreadto be readable by us. Since all permissions were selected when we created it, the characteristic or descriptor is readable. If the required permissions were not selected when creating it, you would need to add the corresponding permissions in the service editor.Use the
read 0command to read the attribute. ‘0’ is the offset.
menu gatt
list-attributes
select-attribute UUID
attribute-info
read 0
Note
Please note that the characteristic or descriptor must have ‘read’ permission to be readable. When we created the characteristic or descriptor, we selected all permissions, which includes ‘read’. Therefore, it is readable. If the required permissions were not selected during creation, you would need to add the corresponding permissions in the service editor.
Pair a Bluetooth Speaker then Play Sound
Bluetooth software stack in rity-demo-image supports hciconfig tool and BlueZ stack.
Bluetooth service is registered as a systemd service. We cannot make bluetooth connections without these userspace services.
Let’s check if the bluetooth service is running in the beginning.
Create a New User Account
We could use pulseaudio, pactl, and paplay to play a wave sound to a paired bluetooth speaker.
However, a non-root user account is required for accessing these tools.
Please follow the following steps to create a non-root user..
First, add a new user.
useradd mtk
Assign /run/user/0/ to the new user.
chown -R mtk /run/user/0/
Switch to the user account mtk.
su mtk
Pair a Bluetooth Speaker
Start bluetoothctl to control the bluetooth interface interactively.
bluetoothctl
bluetoothctl will report the controller if there existed one.
Agent registered
[CHG] Controller 90:E8:68:D4:39:84 Pairable: yes
You’ll also find the prompt has been changed to [bluetooth]#, which means we are under the interactive interface and menu in bluetoothctl.
(waiting for bluetooth commands)
Before using bluetooth, we need to power on the device.
power on
If it is success, you’ll see the valid BD’s address in log with message Powered: yes.
The bluetooth controller is able to scan the neighbor devices now. Put the bluetooth speaker into pairing mode, then simply run:
scan on
bluetoothctl should dumps the BD address of each neighbor bluetooth device.
Please wait until the BD address of the bluetooth speaker appeared (scanned by i350-EVK).
For example, if the <BD address> of the speaker is FC:58:FA:34:46:06:
[NEW] Device FC:58:FA:34:46:06 AXLOIE Mega
After the speaker has been scanned by bluetoothctl, it should be trusted before the connection.
trust <BD address>
The device should be trusted by i350-EVK immediately.
Changing <BD address> trust succeeded.
Finally, we can pair the speaker with i350-EVK.
pair <BD address>
After a while, it should be paired successfully. Sometimes you need to repeat and enter the key for pairing, or, simply type yes in interactive interface.
[CHG] Device <BD address> Paired: yes
Pairing successful
After the devices has been paired, we could exit bluetoothctl and prepare audio tools for playing sound.
exit
Play Sound
If the previous steps worked fine, pulseaudio could be run as a daemon for dealing with audio data.
Launch pulseaudio in daemon mode. Note: Please run as the user mtk.
pulseaudio -D --exit-idle-time -1
Now, we connect the bluetooth device.
bluetoothctl connect <BD address>
Wait for a while, it should be connected successfully.
[CHG] Device FC:58:FA:34:46:06 Connected: yes
Connection successful
Use pactl to list all BlueZ a2dp sink.
pactl list sinks | grep Name
You’ll find a line in outputs as below.
Name: bluez_sink.FC_58_FA_34_46_06.a2dp_sink
Finally, the music could be played to the bluetooth speaker.
paplay /usr/share/sounds/alsa/Front_Right.wav -d <sink Name>
You can hear voice Front Right form the connected speaker.
Turn off Bluetooth Service
If you don’t need bluetooth and want to turn it off, simply run following command.
systemctl disable bluetooth.service
Then the logs show as below.
Removed /etc/systemd/system/dbus-org.bluez.service.
Removed /etc/systemd/system/bluetooth.target.wants/bluetooth.service.
It deregisters the dbus-org.bluez.service and bluetooth.service from systemd.
If you tried to use bluetoothctl after they’ve been deregistered, bluetoothctl will keep waiting for the bluetoothd is ready.
It show the bluetooth service has been turned off.
Reference Boards
Genio platforms support combo modules that provide both WIFI and Bluetooth functionalities. For hardware installation, please refer to the section on wireless installation. The installation method usage, performance, and software of Bluetooth may vary depending on the platform and module used. Please refer to the corresponding documentation for more information on these differences.