hcitool

Monitor & Configure Bluetooth connections

hcitool [-i ] [command [command parameters]]

Monitor & Configure Bluetooth connections and send special commands to Bluetooth devices.

-i hciX The command is applied to hciX, an installed Bluetooth device. Default first available .

COMMANDS

inq Inquire remote devices, address, clock offset and class are outputed. Command times out after 10 seconds.
Inquiring ...
    60:FB:42:83:72:48   clock offset: 0x22ef    class: 0x38010c
     MacBookPro
As seen by hcidump -t -X
19:35:34.767470 < HCI Command: Inquiry (0x01|0x0001) plen 5
    lap 0x9e8b33 len 8 num 0
19:35:34.768011 > HCI Event: Command Status (0x0f) plen 4
    Inquiry (0x01|0x0001) status 0x00 ncmd 1

19:35:45.010964 > HCI Event: Inquiry Complete (0x01) plen 1
    status 0x00

19:35:50.314392 < HCI Command: Inquiry (0x01|0x0001) plen 5
    lap 0x9e8b33 len 8 num 0
19:35:50.314981 > HCI Event: Command Status (0x0f) plen 4
    Inquiry (0x01|0x0001) status 0x00 ncmd 1

19:36:00.557232 > HCI Event: Inquiry Complete (0x01) plen 1
    status 0x00

19:36:04.842860 < HCI Command: Inquiry (0x01|0x0001) plen 5
    lap 0x9e8b33 len 8 num 0
scan
lescan
Inquire remote devices. outputs address and device name .
sudo hcitool scan
Scanning ...
    60:FB:42:83:72:48   smackerpro
As seen by hcidump -t -X
19:36:04.843559 > HCI Event: Command Status (0x0f) plen 4
    Inquiry (0x01|0x0001) status 0x00 ncmd 1
19:36:15.085995 > HCI Event: Inquiry Complete (0x01) plen 1
    status 0x00
    lescan  Start LE scan sudo hcitool lescan & sudo hcidump -t -X
sudo hcitool lescan
LE Scan ...
C4:C1:A5:FB:6D:46 (unknown)
C4:C1:A5:FB:6D:46 RuuviBoot
F2:C0:C6:43:AD:03 (unknown)
F7:FA:74:4A:1E:1A (unknown)
F0:85:49:CD:59:EB (unknown)
F0:85:49:CD:59:EB One
D3:51:78:72:EC:0F (unknown)

tip: export b='60:FB:42:83:72:48' and use $b for other commands

name bdaddr output device name of remote device times out after 5 seconds.
sudo hcitool name 60:FB:42:83:72:48 
smackerpro
info bdaddr output device name, version and supported features of remote device with Bluetooth address bdaddr.
sudo hcitool info $b
Requesting information ...
    BD Address:  60:FB:42:83:72:48 OUI Company: Apple (60-FB-42) Device Name: smackerpro
    LMP Version: 2.1 (0x4) LMP Subversion: 0x21d0
    Manufacturer: Broadcom Corporation (15)
    Features page 0: 0xff 0xff 0x8f 0xfe 0x9b 0xff 0x79 0x83 Following not in order
        <3-slot packets> <5-slot packets> <encryption> <slot offset> 
        <timing accuracy> <role switch> <hold mode> <sniff mode> 
        <park state> <RSSI> <channel quality> <SCO link> <HV2 packets> <HV3 packets> 
        <u-law log> <A-law log> <CVSD> <paging scheme> 
        <power control> <transparent SCO> <broadcast encrypt> 
        <interlaced iscan> <interlaced pscan> <inquiry with RSSI> <enhanced iscan> 
        <extended SCO> <EV4 packets> <EV5 packets>
        <AFH cap. slave> <AFH class. slave> <AFH cap. master> <AFH class. master> 
        <sniff subrating> <pause encryption>
        <EDR eSCO 2 Mbps> <EDR eSCO 3 Mbps> 
        <EDR ACL 2 Mbps> <EDR ACL 3 Mbps> 
        <3-slot EDR ACL> <5-slot EDR ACL> 
        <3-slot EDR eSCO> 
        <extended inquiry> <simple pairing> 
        <encapsulated PDU> <err. data report> <non-flush flag> <LSTO> 
        <inquiry TX power> <extended features> 
    Features page 1: 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00

  BD Address:  4C:32:75:97:3B:AE

    Device Name: smacpro    
    LMP Version:  (0x8) LMP Subversion: 0x2199
    Manufacturer: Broadcom Corporation (15)
    Features page 0: 0xbf 0xfe 0xcf 0xfe 0xdb 0xff 0x7b 0x87  (in addition to those for smackerpro)
        <LE support> 
        <LE and BR/EDR> 
        <EPC> 
    Features page 1: 0x07 0x00 0x00 0x00 0x00 0x00 0x00 0x00
    Features page 2: 0x3f 0x0b 0x00 0x00 0x00 0x00 0x00 0x00

cc
[--role=m|s]
[--pkt-type=ptypes] bdaddr
Create connection to remote device
m (stay master) or s (allow role switch, become slave if the peer asks to become master). Default is m.
ptype is a comma-separated list DM1, DM3, DM5, DH1, DH3, DH5, HV1, HV2, HV3. Default all
Always returns 0 !
con Display active connections
 Connections:
    < ACL 4C:32:75:97:3B:AE handle 12 state 1 lm SLAVE 
Always returns 0 !
require connection cc $b
sr bdaddr role Switch role
cpt bdaddr ptypes Change packet types comma-separated list of packet types
rssi bdaddr Display received signal strength
sudo hcitool cc $b  && sudo hcitool rssi $b
RSSI return value: -22
lq bdaddr Display link quality
tpl bdaddr [1] Display transmit power level ; 1 for maximum
afh bdaddr Display AFH channel map
sudo hcitool cc $b && sudo hcitool afh $b
AFH map: 0x00000000000000000000
lp bdaddrr [lpol] With no value, displays link policy
If value is given, sets the link policy settings. Possible values are RSWITCH, HOLD, SNIFF and PARK.
sudo hcitool cc $b && sudo hcitool lp  $b
Link policy settings: RSWITCH SNIFF 
Returns 1 if "HCI read_link_policy_settings request failed: Input/output error"
lst bdaddr [slots] With no value, displays link supervision timeout.
is given, sets connection to value slots, or to infinite if value is 0.
sudo hcitool cc $b && sudo hcitool lst $b 
Link supervision timeout: 32000 slots (20 000.00 msec)
auth bdaddr Request authentication
enc bdaddr [encrypt enable] Enable or disable the encryption
key bdaddr Change the connection link key
clkoff bdaddr Display the clock offset
clock [bdaddr] [0] Display the clock 0 for the local clock or 1 for the piconet clock (default).
 sudo hcitool cc $b && sudo hcitool clock  $b 1
Clock:    0xe9c4ba6
Accuracy: 0.00 msec
 sudo hcitool cc $b && sudo hcitool clock  $b 0
Can't create connection: Connection timed out
Clock:    0x24209d6
Accuracy: 0.00 msec
sudo hcitool cc $b && sudo hcitool clock  $b 1 && sudo hcitool clock  $b 0  ; usually fails
Clock:    0xe9ddb45
Accuracy: 0.00 msec
Clock:    0x24bf4e4
Accuracy: 0.00 msec

    
lewladd Add device to LE White List
lewlrm Remove device from LE White List
lewlsz Read size of LE White List
lewlclr Clear LE White list
lecc Create a LE Connection
lecup LE Connection UpdateAccuracy: 0.00 msec
ledc Disconnect a LE Connection
dev Display local devices
sudo hcitool dev                                               
Devices:
    hci0    B8:27:EB:96:64:43
cmd ogf ocf [parameters] Submit an arbitrary command to local device. ogf, ocf and parameters are hexadecimal. Example:
sudo hcitool cmd 0x3f 0x15
< HCI Command: ogf 0x3f, ocf 0x0015, plen 0
> HCI Event: 0x0e plen 6
  01 15 FC 30 14 16
dc bdaddr [reason] Delete connection. reason is a decimal error codes. Default is 19 for user ended connections.
spinq Start periodic inquiry process. No inquiry results are output
epinq Exit periodic inquiry process.
HELP
Commands:
    dev     Display local devices
    inq     Inquire remote devices
    scan    Scan for remote devices
    name    Get name from remote device
    info    Get information from remote device
    spinq   Start periodic inquiry
    epinq   Exit periodic inquiry
    cmd     Submit arbitrary HCI commands
    con     Display active connections
    cc      Create connection to remote device
    dc      Disconnect from remote device
    sr      Switch master/slave role
    cpt     Change connection packet type
    rssi    Display connection RSSI
    lq      Display link quality
    tpl     Display transmit power level
    afh     Display AFH channel map
    lp      Set/display link policy settings
    lst     Set/display link supervision timeout
    auth    Request authentication
    enc     Set connection encryption
    key     Change connection link key
    clkoff  Read clock offset
    clock   Read local or remote clock

    lescan  Start LE scan
    lewladd Add device to LE White List
    lewlrm  Remove device from LE White List
    lewlsz  Read size of LE White List
    lewlclr Clear LE White list
    lecc    Create a LE Connection
    ledc    Disconnect a LE Connection
    lecup   LE Connection Update

Inquiry scan (slave)

An unconnected Bluetooth device that wants to be "discovered" by a master device will periodically enter the inquiry scan state; in this state, the device activates its receiver and listens for inquiries.
It must enter this state at least every 2.56 seconds (4096 slots).
It listens on a channel, for at least 10ms (16 slots).
A different channel is selected every 1.28 seconds (2048 slots).
The channels and the hopping sequence are calculated from the general inquiry address.

Inquiry (master)

When commanded to enter the inquiry state, the master device starts to transmit, using 16 channels used for inquiries.
During every even numbered slot it transmits two ID packets on two channels and
during the following slot it listens on those channels for a slave's response (an FHS packet).
In the next two time slots 1/16th second aka 625ms it uses the next two channels, the hopping sequence (of 16 channels) repeats every 10ms (16 slots).
The 16 slot sequence must be repeated at least 256 times (i.e. for at least 2.56 seconds) before switching to the other set of channels.

Don't bother using a null address

 hcitool info 00:00:00:00:00:00
Requesting information ...
    BD Address:  00:00:00:00:00:00
    OUI Company: XEROX CORPORATION (00-00-00)
    Features: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
see notes

hci0: Type: BR/EDR Bus: UART BD Address: B8:27:EB:96:64:43 ACL MTU: 1021:8 SCO MTU: 64:1 UP RUNNING RX bytes:3405617 acl:720 sco:0 events:100851 errors:0 TX bytes:33782 acl:720 sco:0 commands:1749 errors:0 Features: 0xbf 0xfe 0xcf 0xfe 0xdb 0xff 0x7b 0x87 Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 Link policy: RSWITCH SNIFF Link mode: SLAVE ACCEPT Name: 'piw' Class: 0x0c0000 Service Classes: Rendering, Capturing Device Class: Miscellaneous, HCI Version: 4.1 (0x7) Revision: 0x145 LMP Version: 4.1 (0x7) Subversion: 0x2209 Manufacturer: Broadcom Corporation (15) piw:/home/dgerman > man hciconfig

hciconfig - configure Bluetooth devices

hciconfig [-a] [hciX] [command [command parameters]]

hciX is the name of a Bluetooth device Without device lists all devices. If no command is given, outputs basic information on device hciX only. i.e. interface type, BD address, ACL MTU, SCO MTU, flags (up, init, running, raw, page scan enabled, inquiry scan enabled, inquiry, authentication enabled, encryption enabled). -a, --all Other than the basic info, print features, packet type, link policy, link mode, name, class, version. COMMANDS

up Open and initialize HCI device.
down Close HCI device.
reset Reset HCI device.
rstat Reset statistic counters.
[no]auth Enable authentication (sets device to security mode 3).
[no]encrypt Enable encryption (sets device to security mode 3).
[no]secmgr Enable security manager (current kernel support is limited).
[no]piscan Enable page and inquiry scan.
iscan Enable inquiry scan, disable page scan.
pscan Enable page scan, disable inquiry scan.
ptype [type] With no type , displays the current packet types.
Otherwise, all the packet types specified by type are set.
type is a comma-separated list of packet types, DM1, DM3, DM5, DH1, DH3, DH5, HV1, HV2, HV3
name [name] With no name, outputs local name. Otherwise, sets local name to name.
class [class] With no class, outputs class of device. Otherwise, sets class of device to class. class is a 24-bit hex number describing the class of device, as specified in section 1.2 of the Bluetooth Assigned Numers document.
voice [voice] With no voice, outputs voice setting. Otherwise, sets voice setting to voice. voice is a 16-bit hex number describing the voice setting.
iac [iac] With no iac, outputs the current IAC setting. Otherwise, sets
inqtpl [level] With no level, outputs out the current inquiry transmit power level. Otherwise, sets
inqmode [mode]
inqdata [data]
inqtype [type]
inqparams [win:int]
pageparms [win:int]
pageto [to] With no to, prints page timeout. Otherwise, sets page timeout to .I to slots.
afhmode [mode]
sspmode [mode]
aclmtu mtu:pkt Sets ACL MTU to mtu bytes and buffer size to pkt
scomtu mtu:pkt Sets SCO MTU to mtu bytes and buffer size to pkt
delkey deletes the stored link key for bdaddr from the device.
oobdata Get local OOB data (invalidates previously read data).
commands Display supported commands.
features Display device features.
version
revision
lm [mode] With no mode , outputs link mode.
MASTER or SLAVE mean, respectively, to ask to become master or to remain slave when a connection request comes in.
mode is NONE or a comma-separated list MASTER and ACCEPT .
NONE sets link policy to the default behaviour of remaining slave and not accepting baseband connections when there are no listening AF_BLUETOOTH sockets.
ACCEPT accept baseband connections even when there are no listening AF_BLUETOOTH sockets.
MASTER ask to become master if a connection request comes in.
dmesg|grep -i blue|more
[    9.521389] Bluetooth: Core ver 2.22
[    9.521475] Bluetooth: HCI device and connection manager initialized
[    9.521494] Bluetooth: HCI socket layer initialized
[    9.521506] Bluetooth: L2CAP socket layer initialized
[    9.521540] Bluetooth: SCO socket layer initialized
[    9.550942] Bluetooth: HCI UART driver ver 2.3
[    9.550954] Bluetooth: HCI UART protocol H4 registered
[    9.550959] Bluetooth: HCI UART protocol Three-wire (H5) registered
[    9.551122] Bluetooth: HCI UART protocol Broadcom registered
[    9.831008] Bluetooth: BNEP (Ethernet Emulation) ver 1.3
[    9.831014] Bluetooth: BNEP filters: protocol multicast
[    9.831025] Bluetooth: BNEP socket layer initialized
hcidump
Continuous Bluetooth Device Discovery "Inquisition"

github