Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 2 Jan 2019 18:01:55 +0000 (UTC)
From:      Benedict Reuschling <bcr@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r52744 - in head: en_US.ISO8859-1/books/handbook/advanced-networking en_US.ISO8859-1/books/handbook/multimedia share/xml
Message-ID:  <201901021801.x02I1t0O033905@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: bcr
Date: Wed Jan  2 18:01:55 2019
New Revision: 52744
URL: https://svnweb.freebsd.org/changeset/doc/52744

Log:
  Add more information about Bluetooth usage.
  
  The patch shows how to create a remote device connection and
  how to manage devices in /etc/bluetooth/hosts.  The multimedia
  chapter was extended with a description on how to set up and
  connect a Bluetooth audio device as a sound sink.
  It also adds man page references to man-refs.ent for hcsecd(8)
  and virtual_oss(8), respectively.
  
  I cleaned up the patch a bit for consistency and proper markup.
  
  PR:			    228879
  Submitted by:		    nekoxmachina@gmail.com
  Take a look at this PR by:  lme

Modified:
  head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
  head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
  head/share/xml/man-refs.ent

Modified: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml	Mon Dec 31 15:53:36 2018	(r52743)
+++ head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml	Wed Jan  2 18:01:55 2019	(r52744)
@@ -55,6 +55,10 @@
 	<para>How to configure multiple <acronym>VLANs</acronym> on
 	  &os;.</para>
       </listitem>
+
+      <listitem>
+	<para>Configure bluetooth headset.</para>
+      </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
@@ -2365,8 +2369,9 @@ ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x
 
       <para>To start and stop the Bluetooth stack, use its startup
 	script.  It is a good idea to stop the stack before unplugging
-	the device.  When starting the stack, the output should be
-	similar to the following:</para>
+	the device.  Starting the bluetooth stack might require
+	&man.hcsecd.8; to be started.  When starting the stack, the
+	output should be similar to the following:</para>
 
       <screen>&prompt.root; <userinput>service bluetooth start ubt0</userinput>
 BD_ADDR: 00:02:72:00:d4:1a
@@ -2420,9 +2425,9 @@ Inquiry complete. Status: No error [00]</screen>
 	Bluetooth device, similar to the <acronym>MAC</acronym>
 	address of a network card.  This address is needed for further
 	communication with a device and it is possible to assign a
-	human readable name to a BD_ADDR.  Information regarding the
-	known Bluetooth hosts is contained in
-	<filename>/etc/bluetooth/hosts</filename>.  The following
+	human readable name to a <literal>BD_ADDR</literal>.
+	Information regarding the known Bluetooth hosts is contained
+	in <filename>/etc/bluetooth/hosts</filename>.  The following
 	example shows how to obtain the human readable name that was
 	assigned to the remote device:</para>
 
@@ -2435,11 +2440,25 @@ Name: Pav's T39</screen>
 	<quote>your.host.name (ubt0)</quote>.  The name assigned to
 	the local device can be changed at any time.</para>
 
+      <para>Remote devices can be assigned aliases in
+	<filename>/etc/bluetooth/hosts</filename>.  More information
+	about <filename>/etc/bluetooth/hosts</filename> file might be
+	found in &man.bluetooth.hosts.5;.</para>
+
       <para>The Bluetooth system provides a point-to-point connection
 	between two Bluetooth units, or a point-to-multipoint
 	connection which is shared among several Bluetooth devices.
-	The following example shows how to obtain the list of active
-	baseband connections for the local device:</para>
+	The following example shows how to create a connection to a
+	remote device:</para>
+
+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci create_connection <replaceable>BT_ADDR</replaceable></userinput></screen>
+
+      <para><literal>create_connection</literal> accepts
+	<literal>BT_ADDR</literal> as well as host aliases in
+	<filename>/etc/bluetooth/hosts</filename>.</para>
+
+      <para>The following example shows how to obtain the list of
+	active baseband connections for the local device:</para>
 
       <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
 Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State

Modified: head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	Mon Dec 31 15:53:36 2018	(r52743)
+++ head/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	Wed Jan  2 18:01:55 2019	(r52744)
@@ -84,6 +84,10 @@
       <listitem>
 	<para>Configure an image scanner.</para>
       </listitem>
+
+      <listitem>
+	<para>Configure a Bluetooth headset.</para>
+      </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
@@ -284,6 +288,49 @@ pcm2: &lt;Conexant CX20590 (Analog 2.0+HP/2.0)&gt; (pl
 	  do not exist and will not appear in the output of
 	  &man.ls.1;.</para>
       </note>
+    </sect2>
+
+    <sect2 xml:id="bluetooth-headset">
+      <title>Setting up Bluetooth Sound Devices</title>
+
+      <indexterm>
+	<primary>Bluetooth audio</primary>
+      </indexterm>
+
+      <para>Connecting to a Bluetooth device is out of scope for this
+	chapter.  Refer to <xref
+	  linkend="network-bluetooth"/> for more information.</para>
+
+      <para>To get Bluetooth sound sink working with FreeBSD's sound
+	system, users have to install
+	<package>audio/virtual_oss</package> first:</para>
+
+      <screen>&prompt.root; <userinput>pkg install virtual_oss</userinput></screen>
+
+      <para><package>audio/virtual_oss</package> requires
+	<literal>cuse</literal> to be loaded into the kernel:</para>
+
+      <screen>&prompt.root; <userinput>kldload cuse</userinput></screen>
+
+      <para>To load <literal>cuse</literal> during system startup, run
+	this command:</para>
+
+      <screen>&prompt.root; <userinput>sysrc -f /boot/loader.conf cuse_load=yes</userinput></screen>
+
+      <para>To use headphones as a sound sink with
+	<package>audio/virtual_oss</package>, users need to create a
+	virtual device after connecting to a Bluetooth audio
+	device:</para>
+
+      <screen>&prompt.root; <userinput>virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 768 -R /dev/null -P /dev/bluetooth/<replaceable>headphones</replaceable> -d dsp</userinput></screen>
+
+      <note>
+	<para><replaceable>headphones</replaceable> in this example is
+	  a hostname from <filename>/etc/bluetooth/hosts</filename>.
+	  <literal>BT_ADDR</literal> could be used instead.</para>
+      </note>
+
+      <para>Refer to &man.virtual_oss.8; for more information.</para>
     </sect2>
 
     <sect2 xml:id="troubleshooting">

Modified: head/share/xml/man-refs.ent
==============================================================================
--- head/share/xml/man-refs.ent	Mon Dec 31 15:53:36 2018	(r52743)
+++ head/share/xml/man-refs.ent	Wed Jan  2 18:01:55 2019	(r52744)
@@ -303,6 +303,7 @@
 <!ENTITY man.h2xs.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>h2xs</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.hash.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hash</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.hashstat.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hashstat</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
+<!ENTITY man.hcsecd.8 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hcsecd</refentrytitle><manvolnum>8</manvolnum></citerefentry>">;
 <!ENTITY man.hd.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hd</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.head.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>head</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.hesinfo.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hesinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
@@ -812,6 +813,7 @@
 <!ENTITY man.vidfont.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vidfont</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.view.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>view</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.vim.1 "<citerefentry xmlns='http://docbook.org/ns/docbook' vendor='ports'><refentrytitle>vim</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
+<!ENTITY man.virtual_oss.8 "<citerefentry xmlns='http://docbook.org/ns/docbook' vendor='ports'><refentrytitle>virtual_oss</refentrytitle><manvolnum>8</manvolnum></citerefentry>">
 <!ENTITY man.vis.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vis</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.vt220keys.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vt220keys</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;
 <!ENTITY man.vttest.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vttest</refentrytitle><manvolnum>1</manvolnum></citerefentry>">;



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201901021801.x02I1t0O033905>