1.\" Copyright (c) 2019 Dirk Engling
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd January 7, 2019
28.Dt BLUETOOTH-CONFIG 8
29.Os
30.Sh NAME
31.Nm bluetooth-config
32.Nd a script to manage config files for the bluetooth sub system
33.Sh SYNOPSIS
34.Nm
35.Ar scan
36.Op Fl d Ar device
37.Op Fl n Ar node
38.Sh DESCRIPTION
39The
40.Nm
41utility is an interactive script to provide a frontend to the complex bluetooth sub system daemons.
42.Pp
43The following options are available:
44.Bl -tag -width indent+
45.It Fl d
46Scan for a specific bluetooth device address.
47.It Fl n
48Limit scan to a specific host controller. Hint: List all netgraph nodes with
49.Ql /usr/sbin/ngctl list .
50.El
51.Pp
52.Nm
53will help finding and setting up bluetooth controllers, scan for nearby bluetooth devices in
54pairing mode, lookup their names, allow mapping to friendly names in
55.Pa /etc/bluetooth/hosts ,
56ask for the paring PIN, instrument
57.Xr hcsecd 8
58to securely pair with new devices and, if the device offers HID endpoints such as mice or
59keyboards, configure and restart
60.Xr bthidd 8 .
61.Pp
62.Nm
63can bring up any interface and daemon necessary for operation and, if a node is provided on
64command line, will do so automatically for that interface.
65.Sh CAVEATS
66.Nm
67can not parse entries in
68.Xr hcsecd 8
69config file and thus will ask the user to manually modify existing pairing PIN entries.
70.Sh FILES
71.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
72.It Pa /etc/bluetooth/hosts
73.It Pa sysrc -n bthidd_config
74.It Pa sysrc -n hcsecd_config
75.El
76.Sh EXAMPLES
77.Nm
78scan -n ubt0 -a 00:26:bb:7a:58:95
79.Bd -ragged -offset indent
80This will scan the bluetooth controller ubt0hci for a bluetooth device with the address
8100:26:bb:7a:58:95, set up ubt0 if necessary and enter an interactive dialog to pair the
82new device. Since in this example a mouse is paired,
83.Nm
84will interact with
85.Xr bthidd 8 ,
86enabling it if necessary and then write an HID descriptor to its config.
87.Ed
88.Pp
89.Nm
90scan
91.Bd -ragged -offset indent
92This will scan all bluetooth controllers on the systems for bluetooth devices, prompting
93to bring up controllers or daemons along the way.
94.Ed
95.Sh SEE ALSO
96.Xr bthidcontrol 8 ,
97.Xr bthidd 8 ,
98.Xr bthost 1 ,
99.Xr hccontrol 8 ,
100.Xr hcsecd 8 ,
101.Xr sdpcontrol 8 ,
102.Xr sysrc 8
103.Sh HISTORY
104A
105.Nm
106utility first appeared in
107.Fx 12.1 .
108.Sh AUTHORS
109.An Dirk Engling Aq Mt erdgeist@erdgeist.org
110.Sh THANKS TO
111Lars Engels and Warren Block for suggestions, help, and testing.
112