hcitool Command in Linux
The hcitool command is a robust utility you can use to configure connections and send special commands to Bluetooth devices. This command provides a range of functionalities that allow you to interact with Bluetooth devices in various ways.
This command is part of the BlueZ package, which is the official Linux Bluetooth protocol stack. You may also need superuser or root privileges to run some hcitool commands, especially those that modify device states.
Table of Contents
Here is a comprehensive guide to the options available with the hcitool command −
- Syntax for the hcitool command
- Options Available for the hcitool Command
- Examples of hcitool Command in Linux
Syntax for the hcitool Command
The following is the general syntax for the hcitool command −
hcitool [options] [command] [command parameters]
Options Available for the hcitool Command
The following is a list of options and commands for the hcitool command, along with their descriptions −
Options
| Tag | Description |
|---|---|
| -h | Gives a list of possible commands. |
| -i <hciX> | The command is applied to device hciX, which must be the name of an installed Bluetooth device. If not specified, the command will be sent to the first available Bluetooth device. |
Commands
| Tag | Description |
|---|---|
| dev | Display local devices. |
| inq | Inquire remote devices. For each discovered device, Bluetooth device address, clock offset, and class are printed. |
| scan | Inquire remote devices. For each discovered device, device name is printed. |
| name <bdaddr> | Print the device name of the remote device with Bluetooth address bdaddr. |
| info <bdaddr> | Print the device name, version, and supported features of the remote device with Bluetooth address bdaddr. |
| spinq | Start periodic inquiry process. No inquiry results are printed. |
| epinq | Exit periodic inquiry process. |
| cmd <ogf> <ocf> [parameters] | Submit an arbitrary HCI command to the local device. ogf, ocf, and parameters are hexadecimal bytes. |
| con | Display active baseband connections. |
| cc [--role=m|s] [--pkt-type=<ptype>] <bdaddr> | Create a baseband connection to the remote device with Bluetooth address bdaddr. Option --pkt-type specifies a list of allowed packet types. <ptype> is a comma-separated list of packet types, where the possible packet types are DM1, DM3, DM5, DH1, DH3, DH5, HV1, HV2, HV3. Default is to allow all packet types. Option --role can have value m (do not allow role switch, stay master) or s (allow role switch, become slave if the peer asks to become master). Default is m. |
| dc <bdaddr> | Delete baseband connection from the remote device with Bluetooth address bdaddr. |
| sr <bdaddr> <role> | Switch role for the baseband connection from the remote device to master or slave. |
| cpt <bdaddr> <packet types> | Change packet types for the baseband connection to the device with Bluetooth address bdaddr. Packet types is a comma-separated list of packet types, where the possible packet types are DM1, DM3, DM5, DH1, DH3, DH5, HV1, HV2, HV3. |
| rssi <bdaddr> | Display received signal strength information for the connection to the device with Bluetooth address bdaddr. |
| lq <bdaddr> | Display link quality for the connection to the device with Bluetooth address bdaddr. |
| tpl <bdaddr> [type] | Display transmit power level for the connection to the device with Bluetooth address bdaddr. The type can be 0 for the current transmit power level (which is default) or 1 for the maximum transmit power level. |
| afh <bdaddr> | Display AFH channel map for the connection to the device with Bluetooth address bdaddr. |
| lst <bdaddr> [value] | With no value, displays link supervision timeout for the connection to the device with Bluetooth address bdaddr. If value is given, sets the link supervision timeout for that connection to value slots, or to infinite if value is 0. |
| auth <bdaddr> | Request authentication for the device with Bluetooth address bdaddr. |
| enc <bdaddr> [encrypt enable] | Enable or disable the encryption for the device with Bluetooth address bdaddr. |
| key <bdaddr> | Change the connection link key for the device with Bluetooth address bdaddr. |
| clkoff <bdaddr> | Read the clock offset for the device with Bluetooth address bdaddr. |
| clock [bdaddr] [which clock] | Read the clock for the device with Bluetooth address bdaddr. The clock can be 0 for the local clock or 1 for the piconet clock (which is default). |
Examples of hcitool Command in Linux
In this section, we'll look at various practical examples of the hcitool command using the options and commands we've discussed above −
Scan for Bluetooth Devices
If you want to discover nearby Bluetooth devices and establish connections, you simply run the following command −
hcitool scan
This command scans for nearby Bluetooth devices and returns a list of discovered devices along with their MAC addresses.
Output the Name of a Device, Returning its MAC Address
If you know the MAC address of a Bluetooth device, you can retrieve its name using the following syntax −
hcitool name 90:61:AE:3F:4C:CD
Fetch Device Information
To gather detailed information about a remote Bluetooth device, such as its supported features and services, you can simply use the following command −
hcitool info 90:61:AE:3F:4C:CD
Replace 90:61:AE:3F:4C:CD with your actual MAC address.
Check Link Quality
To assess the link quality of a Bluetooth device, you can simply use the hcitool command with the â-lqâ option and provide the MAC address of the Bluetooth device −
hcitool lq 41:42:47:65:41:37
This command returns the link quality score, ranging from 0 to 255; a higher value indicates a better connection quality.
Check Transmit Power Level
To check the transmit power level of a Bluetooth device, you can use the following syntax −
hcitool tpl 41:42:47:65:41:37
Display Local Devices
To check a list of Bluetooth devices and their availability or configurations, you can simply run the following command −
hcitool dev
This command returns a list of Bluetooth devices available on the system, including their names and addresses.
Request Authentication
To request authentication of a specific Bluetooth device, you can use the following syntax −
sudo hcitool auth 41:42:47:65:41:37
Enable Encryption
To enable encryption for a Bluetooth device using the hcitool command, you can use the following syntax −
hcitool enc 41:42:47:65:41:37
This command initiates encryption on the specified Bluetooth connection, enhancing the security of the data transmitted between your device and the Bluetooth device.
Conclusion
The hcitool command offers extensive capabilities for overseeing, configuring connections, and sending specific commands to Bluetooth devices.
By exploring the different practical examples outlined in this tutorial, you can efficiently engage with Bluetooth devices and adjust their settings to suit your needs.