source: general/sysutils/bluez.xml@ 32c1b77

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since 32c1b77 was 51259ad7, checked in by Bruce Dubbs <bdubbs@…>, 12 months ago

Update to bluez-5.68.
  • Property mode set to 100644
File size: 16.8 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY bluez-download-http "&kernel-dl;/linux/bluetooth/bluez-&bluez-version;.tar.xz">
8 <!ENTITY bluez-download-ftp " ">
9 <!ENTITY bluez-md5sum "00a72fed12e706b2d8bb40786154d3aa">
10 <!ENTITY bluez-size "2.2 MB">
11 <!ENTITY bluez-buildsize "158 MB (with tests)">
12 <!ENTITY bluez-time "0.4 SBU (using parallelism=4; with tests)">
13]>
14
15<sect1 id="bluez" xreflabel="BlueZ-&bluez-version;">
16 <?dbhtml filename="bluez.html"?>
17
18
19 <title>BlueZ-&bluez-version;</title>
20
21 <indexterm zone="bluez">
22 <primary sortas="a-BlueZ">BlueZ</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to BlueZ</title>
27
28 <para>
29 The <application>BlueZ</application> package contains the
30 Bluetooth protocol stack for Linux.
31 </para>
32
33 &lfs113_checked;
34
35 <bridgehead renderas="sect3">Package Information</bridgehead>
36 <itemizedlist spacing="compact">
37 <listitem>
38 <para>
39 Download (HTTP): <ulink url="&bluez-download-http;"/>
40 </para>
41 </listitem>
42 <listitem>
43 <para>
44 Download (FTP): <ulink url="&bluez-download-ftp;"/>
45 </para>
46 </listitem>
47 <listitem>
48 <para>
49 Download MD5 sum: &bluez-md5sum;
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 Download size: &bluez-size;
55 </para>
56 </listitem>
57 <listitem>
58 <para>
59 Estimated disk space required: &bluez-buildsize;
60 </para>
61 </listitem>
62 <listitem>
63 <para>
64 Estimated build time: &bluez-time;
65 </para>
66 </listitem>
67 </itemizedlist>
68
69 <bridgehead renderas="sect3" revision="sysv">Additional Downloads</bridgehead>
70 <itemizedlist spacing="compact" revision="sysv">
71 <listitem>
72 <para>
73 Required patch:
74 <ulink url="&patch-root;/bluez-&bluez-version;-obexd_without_systemd-1.patch"/>
75 </para>
76 </listitem>
77 </itemizedlist>
78
79 <bridgehead renderas="sect3">BlueZ Dependencies</bridgehead>
80
81 <bridgehead renderas="sect4">Required</bridgehead>
82 <para role="required">
83 <xref linkend="dbus"/>,
84 <xref linkend="glib2"/>, and
85 <xref linkend="libical"/>
86 </para>
87
88 <bridgehead renderas="sect4">Optional</bridgehead>
89 <para role="optional">
90 <xref linkend="docutils"/> (to generate man pages)
91 </para>
92
93 </sect2>
94
95
96 <sect2 role="kernel" id="bluez-kernel">
97 <title>Kernel Configuration</title>
98
99 <para>
100 If you are building this package to use bluetooth devices (rather than as a
101 build dependency), enable the following options in the kernel configuration,
102 also the options in the <quote>Cryptographic API</quote> section if
103 you intend to run the tests, and recompile the kernel if necessary:
104 </para>
105
106<screen><literal>General Setup ---&gt;
107 [ /*] Configure standard kernel features (expert users) [CONFIG_EXPERT]
108 (Note: if CONFIG_EXPERT is disabled, the following options will be
109 hidden and enabled implicitly. We DO NOT recommend to enable
110 CONFIG_EXPERT unless you are really an expert user.)
111 [*] Enable timerfd() system call [CONFIG_TIMERFD]
112 [*] Enable eventfd() system call [CONFIG_EVENTFD]
113
114[*] Networking support ---&gt; [CONFIG_NET]
115 &lt;*/M&gt; Bluetooth subsystem support ---&gt; [CONFIG_BT]
116 &lt;*/M&gt; RFCOMM protocol support [CONFIG_BT_RFCOMM]
117 [*] RFCOMM TTY support [CONFIG_BT_RFCOMM_TTY]
118 &lt;*/M&gt; BNEP protocol support [CONFIG_BT_BNEP]
119 [*] Multicast filter support [CONFIG_BT_BNEP_MC_FILTER]
120 [*] Protocol filter support [CONFIG_BT_BNEP_PROTO_FILTER]
121 &lt;*/M&gt; HIDP protocol support [CONFIG_BT_HIDP]
122 Bluetooth device drivers ---&gt;
123 (Select the appropriate drivers for your Bluetooth hardware)
124
125 &lt;*/M&gt; RF switch subsystem support ---- [CONFIG_RFKILL]
126
127-*- Cryptographic API ---&gt;
128 Crypto core or helper --- &gt;
129 &lt;*/M&gt; User-space cryptographic algorithm configuration [CONFIG_CRYPTO_USER]
130 Block ciphers ---&gt;
131 &lt;*/M&gt; AES (Advanced Encryption Standard) [CONFIG_CRYPTO_AES]
132 AEAD (authenticated encryption with associated data) ciphers ---&gt;
133 &lt;*/M&gt; CCM (Counter with Cipher Block Chaining-MAC) [CONFIG_CRYPTO_CCM]
134 Hashes, digests, and MACs ---&gt;
135 &lt;*/M&gt; CMAC (Cipher-based MAC) [CONFIG_CRYPTO_CMAC]
136 Userspace interface ---&gt;
137 &lt;*/M&gt; Hash algorithms [CONFIG_CRYPTO_USER_API_HASH]
138 &lt;*/M&gt; Symmetric key cipher algorithms [CONFIG_CRYPTO_USER_API_SKCIPHER]
139 &lt;*/M&gt; AEAD cipher algorithms [CONFIG_CRYPTO_USER_API_AEAD]</literal></screen>
140
141<!--
142 <para>
143 If you wish to run the test suite (even if treating this package as a build
144 dependency), you will need to enable the following options in the kernel
145 configuration and recompile the kernel if necessary:
146 </para>
147
148<screen><literal>-*- Cryptographic API - - -&gt; [CONFIG_CRYPTO]
149 &lt;*/M&gt; User-space interface for hash algorithms [CONFIG_CRYPTO_USER_API_HASH]
150 &lt;*/M&gt; User-space interface for symmetric key cipher algorithms [CONFIG_CRYPTO_USER_API_SKCIPHER]</literal></screen>
151-->
152 <indexterm zone="bluez bluez-kernel">
153 <primary sortas="d-bluez">bluez</primary>
154 </indexterm>
155 </sect2>
156
157 <sect2 role="installation">
158 <title>Installation of BlueZ</title>
159
160<!--
161 <para>
162 At first, fix an issue building the package with Glibc-2.34 or later:
163 </para>
164
165<screen><userinput>sed 's/pause(/bluez_&amp;/' -i profiles/audio/media.c</userinput></screen>
166-->
167
168 <para revision="sysv">Now, make some changes needed for SystemV systems:</para>
169
170<screen revision="sysv"><userinput>patch -Np1 -i ../bluez-&bluez-version;-obexd_without_systemd-1.patch</userinput></screen>
171
172 <para>
173 Install <application>BlueZ</application> by running the following
174 commands:
175 </para>
176
177<screen revision="sysv"><userinput>./configure --prefix=/usr \
178 --sysconfdir=/etc \
179 --localstatedir=/var \
180 --enable-library \
181 --disable-manpages \
182 --disable-systemd &amp;&amp;
183make</userinput></screen>
184
185<screen revision="systemd"><userinput>./configure --prefix=/usr \
186 --sysconfdir=/etc \
187 --localstatedir=/var \
188 --disable-manpages \
189 --enable-library &amp;&amp;
190make</userinput></screen>
191
192 <para>
193 To test the results, issue: <userinput>make check</userinput>.
194 </para>
195
196 <para>
197 Now, as the <systemitem class="username">root</systemitem> user:
198 </para>
199
200<screen role="root"><userinput>make install &amp;&amp;
201ln -svf ../libexec/bluetooth/bluetoothd /usr/sbin</userinput></screen>
202
203 <para>
204 Install the main configuration file as the
205 <systemitem class="username">root</systemitem> user:
206 </para>
207
208<screen role="root"><userinput>install -v -dm755 /etc/bluetooth &amp;&amp;
209install -v -m644 src/main.conf /etc/bluetooth/main.conf</userinput></screen>
210
211 <para>
212 If desired, install the API documentation as the
213 <systemitem class="username">root</systemitem> user:
214 </para>
215
216<screen role="root"><userinput>install -v -dm755 /usr/share/doc/bluez-&bluez-version; &amp;&amp;
217install -v -m644 doc/*.txt /usr/share/doc/bluez-&bluez-version;</userinput></screen>
218
219 </sect2>
220
221
222 <sect2 role="commands">
223 <title>Command Explanations</title>
224
225 <para>
226 <parameter>--disable-manpages</parameter>: This switch disables generating
227 the manual pages because of the reliance on 'rst2man' in docutils. Remove
228 this switch if you have <xref role="nodep" linkend="docutils"/> installed
229 and wish to generate the manual pages.
230 </para>
231
232 <para>
233 <parameter>--enable-library</parameter>: This switch enables building the
234 <application>BlueZ</application> 4 compatibility library which is required by
235 some applications.
236 </para>
237
238 <para revision="sysv">
239 <parameter>--disable-systemd</parameter>: This switch is needed because
240 <application>systemd</application> is not part of LFS/BLFS. If you are
241 using systemd, remove this switch.
242 </para>
243
244 <para>
245 <command>ln -svf ../libexec/bluetooth/bluetoothd /usr/sbin</command>:
246 This command makes access to the bluetooth daemon more convenient.
247 </para>
248
249 </sect2>
250
251 <sect2 role="configuration">
252 <title>Configuring BlueZ</title>
253
254 <sect3 id="bluez-config">
255 <title>Configuration Files</title>
256 <para revision="sysv">
257 <filename>/etc/bluetooth/main.conf</filename> is installed automatically
258 during the install. Additionally, there are three supplementary
259 configuration files. /etc/sysconfig/bluetooth is installed as a part
260 of the boot script below. In addition, you optionally can install the
261 following, as the <systemitem class="username">root</systemitem> user:
262 </para>
263
264 <para revision="systemd">
265 <filename>/etc/bluetooth/main.conf</filename> is installed automatically
266 during the installation. Additionally, there are two supplementary
267 configuration files. You can optionally install the following files
268 as the <systemitem class="username">root</systemitem> user:
269 </para>
270
271<screen role="root"><userinput>cat > /etc/bluetooth/rfcomm.conf &lt;&lt; "EOF"</userinput>
272<literal># Start rfcomm.conf
273# Set up the RFCOMM configuration of the Bluetooth subsystem in the Linux kernel.
274# Use one line per command
275# See the rfcomm man page for options
276
277
278# End of rfcomm.conf</literal>
279EOF</screen>
280
281<screen role="root"><userinput>cat > /etc/bluetooth/uart.conf &lt;&lt; "EOF"</userinput>
282<literal># Start uart.conf
283# Attach serial devices via UART HCI to BlueZ stack
284# Use one line per device
285# See the hciattach man page for options
286
287# End of uart.conf</literal>
288EOF</screen>
289
290 <indexterm zone="bluez bluez-config">
291 <primary
292 sortas="e-etc-bluetooth-main.conf">/etc/bluetooth/main.conf</primary>
293 </indexterm>
294
295 </sect3>
296
297 <sect3 id="bluez-init">
298 <title><phrase revision="sysv">Boot Script</phrase>
299 <phrase revision="systemd">Systemd Bluez Services</phrase></title>
300
301 <para revision="sysv">
302 To automatically start the <command>bluetoothd</command> daemon when the
303 system is rebooted, install the
304 <filename>/etc/rc.d/init.d/bluetooth</filename> bootscript from the
305 <xref linkend="bootscripts"/> package.
306 </para>
307
308 <para revision="systemd">
309 To start the <command>bluetoothd</command> daemon at boot,
310 enable the previously installed systemd unit by
311 running the following command as the
312 <systemitem class="username">root</systemitem> user:
313 </para>
314
315<screen role="root" revision="systemd"><userinput>systemctl enable bluetooth</userinput></screen>
316
317 <para revision="systemd">
318 To start the <command>obexd</command> daemon for a user session (to
319 support some Bluetooth programs using it), enable the previously
320 installed systemd unit for all users by running the following command
321 as the <systemitem class="username">root</systemitem> user:
322 </para>
323
324<screen role="root" revision="systemd"><userinput>systemctl enable --global obex</userinput></screen>
325
326 <indexterm zone="bluez bluez-init">
327 <primary sortas="f-bluetooth">bluetooth</primary>
328 </indexterm>
329
330<screen role="root" revision="sysv"><userinput>make install-bluetooth</userinput></screen>
331
332
333 <note revision="systemd">
334 <para>
335 <application>Systemd</application> will start the Bluetooth daemon
336 only when a bluetooth device is detected on the system.
337 </para>
338 </note>
339
340 </sect3>
341
342 </sect2>
343
344 <sect2 role="content">
345 <title>Contents</title>
346
347 <segmentedlist>
348 <segtitle>Installed Programs</segtitle>
349 <segtitle>Installed Library</segtitle>
350 <segtitle>Installed Directories</segtitle>
351
352 <seglistitem>
353 <seg>
354 <!--bccmd, -->
355 bluemoon,
356 bluetoothctl,
357 bluetoothd (symlink),
358 btattach,
359 btmon,
360 hex2hcd,
361 l2ping,
362 l2test,
363 mpris-proxy, and
364 rctest
365 </seg>
366 <seg>
367 libbluetooth.so
368 </seg>
369 <seg>
370 /etc/bluetooth,
371 /usr/{include,libexec}/bluetooth, and
372 /usr/share/doc/bluez-&bluez-version;
373 </seg>
374 </seglistitem>
375 </segmentedlist>
376
377 <variablelist>
378 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
379 <?dbfo list-presentation="list"?>
380 <?dbhtml list-presentation="table"?>
381
382 <!--
383 <varlistentry id="bccmd">
384 <term><command>bccmd</command></term>
385 <listitem>
386 <para>
387 is used to issue BlueCore commands to Cambridge Silicon
388 Radio devices
389 </para>
390 <indexterm zone="bluez bccmd">
391 <primary sortas="b-bccmd">bccmd</primary>
392 </indexterm>
393 </listitem>
394 </varlistentry>
395 -->
396
397 <varlistentry id="bluemoon">
398 <term><command>bluemoon</command></term>
399 <listitem>
400 <para>
401 is a Bluemoon configuration utility
402 </para>
403 <indexterm zone="bluez bluemoon">
404 <primary sortas="b-bluemoon">bluemoon</primary>
405 </indexterm>
406 </listitem>
407 </varlistentry>
408
409 <varlistentry id="bluetoothctl">
410 <term><command>bluetoothctl</command></term>
411 <listitem>
412 <para>
413 is the interactive Bluetooth control program
414 </para>
415 <indexterm zone="bluez bluetoothctl">
416 <primary sortas="b-bluetoothctl">bluetoothctl</primary>
417 </indexterm>
418 </listitem>
419 </varlistentry>
420
421 <varlistentry id="bluetoothd">
422 <term><command>bluetoothd</command></term>
423 <listitem>
424 <para>
425 is the Bluetooth daemon
426 </para>
427 <indexterm zone="bluez bluetoothd">
428 <primary sortas="b-bluetoothd">bluetoothd</primary>
429 </indexterm>
430 </listitem>
431 </varlistentry>
432
433 <varlistentry id="btmon">
434 <term><command>btmon</command></term>
435 <listitem>
436 <para>
437 provides access to the Bluetooth subsystem monitor
438 infrastructure for reading HCI traces
439 </para>
440 <indexterm zone="bluez btmon">
441 <primary sortas="b-btmon">btmon</primary>
442 </indexterm>
443 </listitem>
444 </varlistentry>
445
446
447 <varlistentry id="hex2hcd">
448 <term><command>hex2hcd</command></term>
449 <listitem>
450 <para>
451 is used to convert a file needed by Broadcom devices
452 to hcd (Broadcom bluetooth firmware) format
453 </para>
454 <indexterm zone="bluez hex2hcd">
455 <primary sortas="b-hex2hcd">hex2hcd</primary>
456 </indexterm>
457 </listitem>
458 </varlistentry>
459
460 <varlistentry id="l2ping">
461 <term><command>l2ping</command></term>
462 <listitem>
463 <para>
464 is used to send a L2CAP echo request to the Bluetooth MAC
465 address given in dotted hex notation
466 </para>
467 <indexterm zone="bluez l2ping">
468 <primary sortas="b-l2ping">l2ping</primary>
469 </indexterm>
470 </listitem>
471 </varlistentry>
472
473 <varlistentry id="l2test">
474 <term><command>l2test</command></term>
475 <listitem>
476 <para>
477 is a L2CAP testing program
478 </para>
479 <indexterm zone="bluez l2test">
480 <primary sortas="b-l2test">l2test</primary>
481 </indexterm>
482 </listitem>
483 </varlistentry>
484
485 <varlistentry id="rctest">
486 <term><command>rctest</command></term>
487 <listitem>
488 <para>
489 is used to test RFCOMM communications on the
490 Bluetooth stack
491 </para>
492 <indexterm zone="bluez rctest">
493 <primary sortas="b-rctest">rctest</primary>
494 </indexterm>
495 </listitem>
496 </varlistentry>
497
498 <varlistentry id="libbluetooth">
499 <term><filename class="libraryfile">libbluetooth.so</filename></term>
500 <listitem>
501 <para>
502 contains the <application>BlueZ</application> 4 API functions
503 </para>
504 <indexterm zone="bluez libbluetooth">
505 <primary sortas="c-libbluetooth">libbluetooth.so</primary>
506 </indexterm>
507 </listitem>
508 </varlistentry>
509 </variablelist>
510
511 </sect2>
512
513</sect1>
Note: See TracBrowser for help on using the repository browser.