btctl is the control program to configure kernel-resident Bluetooth interfaces.
If no arguments are given, btctl displays the status of currently active interfaces.
btctl has a device cache. At inquiry or discovery procedure all found devices are added to the device cache. A number is assigned to each entry (according to the order in the cache), which can be used instead of Bluetooth address. btctl searches for the Bluetooth address in the device cache. The content of the cache is shown by "btctl list" command.
The Device cache is also used by btsrv to store link keys.
btctl commands can be divided in several groups:
general commands
device commands
security commands
HCI commands.
UART commands
RFCOMM commands
SDP commands
OBEX commands.
PAN commands.
General commands group includes commands:
help <cmdname>
Shows command description.
list
Shows contents of the device cache (all known devices).
flush
Cleans up device cache.
up
Brings Bluetooth interface up.
down
Brings Bluetooth interface down.
ping <bda> <size>
Sends a L2CAP echo request packet.
debug [+|-][<module>|<type>|<detail>|<all>]
Enables or disables debugging messages for certain module or certain type.
+ or - enables or disables certain features.
module - hcicore|afhci|hcisched|hcimgr|hcilib|hci | pl2cap|afl2cap|l2cap | prfcomm|afrfcomm|bty|rfcomm |usb|uart|drv | allmod
type - init | xmit | xmite | recv | recve | ctrl | ctrle | timer | allerror | alltype
detail - dump | chardump | parse | fname | func | alldetail
Security commands control
security <mode>
Sets security mode for the device.
addpin [<address>|default] <pin>
Adds a PIN code to the Affix control block. This PIN code is used for authentication of a device with address <address>. If "default" is used instead of address then it will be used if no dedicated PIN code found.
rmpin [<address>|default]
Removes a PIN code from Affix control block.
unbond <address>
Removes a paring with device with address <address>. Practically it means that the link key is removed from Affix control block and device cache as well.
pair <address>
Creates a paring with the device. If btsrv is running as "btsrv --managet-keys" then the link is added to device cache as well.
Some devices require to be pared first (like Ericsson T68).
HCI commands are used to manage Bluetooth device.
inquiry [length]
Makes an inquiry during length "length" to find neighbor devices. It shows device address and device class of found devices. If no length provided then default length is used - 8 secs.
Each found device is shown with an order number that later can be use instead of address to identify remote device.
discovery [length]
Makes a discovery during length "length" to find neighbor devices. In addition to "inquiry" it also resolves name of the found device and shows with address and class. If no length provided then default length is used - 8 secs.
Each found device is shown with order number which later can be use instead of address to identify remote device.
remotename <bda>
Resolves a name of the remove device. Probably not really useful because discovery does it as well.
bdaddr
Reads device address from the card. Probably not really useful because btctl shows it.
name [name]
If "name" is given then sets new name for device. Otherwise reads current name.
role <allow|deny> <master|slave>
Sets connection roles. Has two arguments and defines connection roles for incoming and outgoing connections. First argument defines roles for outgoing connections: allow or deny. allow - allow role switching, deny - deny role switching. Second argument defines roles for incoming connections: slave or master. slave - remain slave, master - become the master.
class [<class> | <major> <minor> <service1> ... <servicen>]
Sets the device class. If hexadecimal value is given then it is set as a device class. Otherwise the class is given in textual format and has the following syntax:
Major can be one of: misc, computer, phone, audio, lap, peripheral. It defines what this device actually is.
Computer devices (major - computer) : desktop, server, laptop, handheld, palm.
Phone devices (major - phone): cellular, cordless, smart, modem.
Audio devices (major - audio): headset.
Service Class can be set of following: networking, information, audio, transfer, rendering, capturing, telephony.
If no arguments are given for the command then it shows current device class.
pkt_type [<0xXXX> | <mnemonic>]
Sets packet types, which are used to create connections. It accepts hexadecimal or literal arguments: DM1, DH1, DM3, DH3, DM5, DH5.
scan [+|-][disc|conn]
Sets a scanning mode for the device: disc or/and conn. disc tells that device will be discoverable (visible for remote devices). conn tells that device has to be connectible (allow remote device to connect to local).
UART commands are used to attach and detach HCI interface to Bluetooth device connected to the host via serial cable or device which use legacy UART interface to communicate with it (in fact mostly it is handled by affix_uart_cs.o).
open_uart <tty_device> <type> [speed] [flags]
Attaches HCI interface to UART device "tty_device".
"type" is type of the device and can take following values: h4 - for standard H4 devices, tlp - for Nokia chip based devices, bcsp - for BCSP devices, csr - for CSR H4 devices, ericsson - for Ericsson H4 devices, digi - for Digianswer H4 devices, swave - for Sillicon Wave H4 devices. Device type depends on the protocol which is used by device (H4, BCSP, TLP) or if the device requires special initialization.
"speed" - non-default speed the UART will work on (57600, 115200, 230400, 460800, 921600).
"flags" - non-default UART flags: ctl - hardware flow control, pareven - even parity, parodd - odd parity, stopb - 2 stop bits, low - low UART latency (preferred), ring - enable RI processing (only for Nokia chip based devices)
close_uart <tty_device>
Detaches HCI interface from UART device "tty_device"
RFCOMM commands are used to create, check and destroy RFCOMM connections and bind it to virtual TTY lines /dev/btyXX.
connect <address> [<channel> | [service_type]]
Creates an RFCOMM connection to device with address <address> to service channel <channel> or service <service_type>. service_type can be one of following: serial, dun, lan, headset. If channel or service_type omitted then "serial" is assumed.
After connection is established it's bind to virtual TTY line /dev/btyXX.
status
Shows RFCOMM connections and bound TTY lines.
disconnect <line>
Destroys an RFCOMM connection and releases TTY line.
SDP commands are used to browse services available on the device.
browse <address>
Browses available services on a device with address <address>. It shows information about service: service name, provider name, description, protocol info (access ports), profile info.
Services represented as hierarchy (tree) that is started from the root (BrowseGroupRoot). Browse command does request to get whole service hierarchy. Not all devices support it. (Bluetooth stack for Windows from Digianswer does not).
If "local" is provided instead of <address> then it shows local services.
search <address>
This command does the same as "browse" but it tries to search for all known services instead of requesting whole service hierarchy. This command is used if "browse" does now show any services.
OBEX commands are used for transferring files and objects to/from devices.
ftp
Starts btctl in interactive mode.
open <address> [channel]
Opens OBEX connection to FTP service (File Transfer Profile). If channel is given then use it instead of looking for it in SDP database.
This command works only in interactive mode.
close
Closes existing OBEX connection.
This command works only in interactive mode.
ls [<address> [<channel>]] [dir]
Shows content of the directory on the OBEX server.
In interactive mode connection must be opened by "open" command first and address and channel parameters must not be provided.
put [<address> [<channel>]] <local-file> [remote-file]
Sends a file to the server.
In interactive mode connection must be opened by "open" command first and address and channel parameters must not be provided.
get [<address> [<channel>]] <remote-file> [local-file]
Receives a file from the server.
In interactive mode connection must be opened by "open" command first and address and channel parameters must not be provided.
push <address> [<channel>] <local-file> [remote-file]
Sends a file to the server (using Object Push Profile).
rm [<address> [<channel>]] <remote-file>
Deletes a file on the server.
In interactive mode connection must be opened by "open" command first and address and channel parameters must not be provided.
cd <dir name>
Changes an active directory.
mkdir <dir name>
Creates a new directory on the server.
PAN commands are used to initialize and configure PAN interfaces.
paninit [panu|nap|gn]
Initializes the PAN interface (pan0, pan1, ..) and assign it role: panu, nap or gn.
panstop
Releases the PAN interface.
panctl <interface> [m (start_addr stop_addr)* ] [p (range_start range_stop)* ]
Sets multicast or protocol filters for PAN interface <interface> (pan0, pan1, ...). If now filters are given then shown current filter settings.