From 3b4a15f46108549c35d241ca8d11efc99f61f3d7 Mon Sep 17 00:00:00 2001 From: "F. Duncanh" Date: Sun, 22 Mar 2026 00:44:23 -0400 Subject: [PATCH] README updates for beacon --- README.html | 156 ++++++++++++++++++++++++++++------------------------ README.md | 97 +++++++++++++++++--------------- README.txt | 156 ++++++++++++++++++++++++++++------------------------ 3 files changed, 222 insertions(+), 187 deletions(-) diff --git a/README.html b/README.html index 9874fce..485fa77 100644 --- a/README.html +++ b/README.html @@ -1548,44 +1548,42 @@ messages, set GST_DEBUG=4; for DEBUG messages, GST_DEBUG=5; increase this to see even more of the GStreamer inner workings.

Bluetooth LE beacon setup

The python>=3.6 script for running a Bluetooth LE Service -Discovery beacon is uxplay-beacon.py. It provides four possible -Bluetooth LE implementations (loaded as modules):

+Discovery beacon is uxplay-beacon.py. Besides the standard python +libraries, it requires python3-psutils.

+

It provides four possible Bluetooth LE implementations (loaded as +modules uxplay_beacon_module_*.py), which may need +additional libraries:

On Linux, Bluetooth support (using the official Linux Bluetooth stack BlueZ, and D-Bus) must be installed (on Debian-based systems: @@ -1594,18 +1592,18 @@ provide bluez as a snap package). BlueZ tools ‘hcitool’ and ‘hciconfig’ (needed if you use the HCI module on Linux) are declared “deprecated” by the BlueZ developers: some Linux distributions have removed them from the default BleuZ packages, into “extra” packages with names like -“bluez-deprecated”.

-

In addition to standard Python3 libraries, you may need to install -the gi, dbus, and psutil Python libraries used by uxplay-beacon.py. On -Debian-based systems:

-
sudo apt install python3-gi python3-dbus python3-psutil
-

If a python3-gi package is available in your Linux distribution, -install the python3-gobject package which provides it.

-

For Windows support in the MSYS2 UCRT64 environment, use pacman -S to -install mingw-w64-ucrt-x86_64-python, -*-python-gobject, *-python-psutil, and -*-python-pip. Then install winrt bindings -using pip (or pip3):

+“bluez-deprecated”. Also install psutil Python libraries used by +uxplay-beacon.py. On Debian-based systems:

+
sudo apt install  python3-psutil
+

For the BlueZ module (Linux), install python3-gi +(from which GLib is imported) and python3-dbus. If a python3-gi package +is not available in your Linux distribution, use pip to +install PyGObject instead.

+

For the winrt module, with Windows support in the +MSYS2 UCRT64 environment, use pacman -S to install +mingw-w64-ucrt-x86_64-python,*-python-psutil, +and *-python-pip. Then install winrt +bindings using pip (or pip3):

pip install winrt-Windows.Foundation 
 pip install winrt-Windows.Foundation.Collections 
 pip install winrt-Windows.Devices.Bluetooth.Advertisement 
@@ -1617,15 +1615,33 @@ python installations (such as the one provided in MSYS2) should be

 requirement to make users hesitate before adding packages not provided
 by the “external management”: this is unnecessarily scary, as in the
 case of the winrt packages, no breakage can occur.

-
UxPlay must be run with option “uxplay -ble” (so it
-writes data for the Bluetooth beacon in the default BLE data file
-~/.uxplay.ble), just run uxplay-beacon.py in a
-separate terminal. The python script will start Bluetooth LE
-Service-Discovery advertising when it detects that UxPlay is running by
-checking if the BLE data file exists, and stop when it no longer detects
-a running UxPlay plus this file (it will restart advertising if UxPlay
-later reappears). The script will remain active until stopped with
-Ctrl+C in its terminal window (or its terminal window is closed).

+
For the BleuIO module, install pyserial.

+
For the HCI module, create a group
+hciusers to give group members the privilege of using
+passwordless sudo -n hci* (hci* is
+hcitool and hciconfig (Linux), or
+hccontrol (FreeBSD), and add users of the module to this
+group (security implications should be considered). In Linux,
+use “sudo visudo /etc/sudoers.d/hciusers” (in FreeBSD, file
+is /usr/local/etc/sudoers.d/hciusers) to create a file
+containing one of the lines

+
%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig       (Linux)
+%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol                        (FreeBSD)

+
UxPlay must be run with option
+“uxplay -ble [path_to_file]” (so it writes data for the
+Bluetooth beacon to the default BLE data file
+~/.uxplay.ble, or optionally to the file specifed by its
+path), then run
+uxplay-beacon.py [HCI, BleuIO] [--path path_to_file] in a
+separate terminal. If options HCI or BleuIO are not given, the default
+module for the operating system will be used (BlueZ for Linux, winrt for
+Windows, BleuIO for all others).

+
The python script will start Bluetooth LE Service-Discovery
+advertising when it detects that UxPlay is running by checking if the
+BLE data file exists, and stop when it no longer detects a running
+UxPlay (it will restart advertising if UxPlay later reappears). The
+script will remain active until stopped with Ctrl+C in its terminal
+window (or its terminal window is closed).

 
The beacon script can be more finely controlled using certain
 options: these can be given on the command line, or read from a
 configuration file ~/.uxplay.beacon, if it exists.
@@ -1637,7 +1653,7 @@ or uxplay-beacon.py --help.

 
Options are

 
    
 
  • <module> where “module” is BleuIO or HCI (no
-intital --) . Without this option, the default module used
+initial --) . Without this option, the default module used
 will be BlueZ (Linux), winrt
 (Windows), BleuIO (all other operating
 systems).
    • 
@@ -1666,7 +1682,7 @@ with other tasks the Bluetooth device is carrying out. The default
 values are advmin = advmax = 100. The advertisement is broadcast on all
 three Bluetooth LE advertising channels: 37,38,39.
 

-
On a Windows system, the values of these paramaters are set by the
+
On a Windows system, the values of these parameters are set by the
 operating system, and cannot be set by users.

 
The BlueZ module (Linux) also accepts

 
    
@@ -1683,25 +1699,23 @@ needed.
 accept
    
 
      
 
    • --device x which allows overiding automatically-made
-choices of serial ports (BleuIO) or hci device nodes
+choices of serial ports (BleuIO) or hci devices
 (HCI). This is probably only useful if the host system
 has multiple devices that could be used.
      • 
 
    
-
    The native macOS Bluetooth stack has no documented way for users to
+
    The native macOS Bluetooth stack does not allow unprivileged users to
 send “manufacturer-specific” Bluetooth LE advertisements (such that sent
-for AirPlay Service Discovery), and the only support of uxplay-beacon.py
-on macOS uses a BleuIO USB serial device. However macOS provides a
-low-level utility BlueTool (found at /usr/sbin/bluetool)
-that can send HCI commands, so possibly could be used to adapt the
-python3 HCI module to support macOS as well
-(working implementations welcome!). The recommended and
-working method on macOS is to use a BleuIO dongle.
    
-
    If you wish to test Bluetooth LE Service Discovery on Linux/*BSD, you
-can disable DNS_SD Service discovery by the avahi-daemon with
    
+for AirPlay Service Discovery), and the only current support of
+uxplay-beacon.py on macOS uses a BleuIO USB serial device.
    
+
    For testing Bluetooth LE Service Discovery you might wish to disable
+DNS_SD Service discovery (although the Bluetooth LE Service seems to
+work if DNS_SD is enabled). On Linux, disable the the avahi-daemon that
+provides DNS_SD with
    
 
    $ sudo systemctl mask avahi-daemon.socket
 $ sudo systemctl stop avahi-daemon
    
-
    To restore DNS_SD Service discovery, replace “mask” by “unmask”, and
-“stop” by “start”.
    
+
    (On FreeBSD, “service avahi-daemon stop”). To restore
+DNS_SD Service discovery, replace “mask” by “unmask”, and “stop” by
+“start”.
    
 
    On Windows, the Bonjour Service is controlled using Services
 Management: press “Windows + R” to open the Run dialog, run
 services.msc, and click on Bonjour Service
diff --git a/README.md b/README.md
index 9447c15..e0a48af 100644
--- a/README.md
+++ b/README.md
@@ -1559,49 +1559,47 @@ GStreamer inner workings.
 # Bluetooth LE beacon setup
 
 The python>=3.6 script for running a Bluetooth LE Service Discovery beacon is uxplay-beacon.py.
-It provides four possible Bluetooth LE implementations (loaded as modules):
+Besides the standard python libraries, it requires python3-psutils.
 
-* **BlueZ** for Linux systems with D-Bus;
+It provides four possible Bluetooth LE implementations (loaded as modules `uxplay_beacon_module_*.py`), which may need additional libraries:
 
-* **winrt**  for Windows;
+* **BlueZ** for Linux systems with D-Bus: needs **GLib** (from python3-gi or PyGObject) and **python-dbus**.
 
-* **BleuIO** for the [BleuIO (or BleuIO Pro) USB dongle](https://www.bleuio.com)  with its own on-board Bluetooth-LE Stack that
-    does not use the host operating system Bluetooth (the host sees the device as a USB serial modem).   This is needed for macOS where the
-    native operating system Bluetooth stack does not allow users to send  Bluetooth-LE advertising data
-    of the "manufacturer-specific" type `AdvData=0xFF`.  If a BleuIO dongle (currently costs about USD25) is
-    available, the BleuIO version of the python script can be used on many operating systems including macOS, Windows, Linux, FreeBSD,
-    and probably other BSD variants (not tested): it requires python library `python3-pyserial` to be installed.  On Linux, users must be members of
-    group `dialout` or sometimes ``uucp`` (```dialer``` on FreeBSD).
+* **winrt**  for Windows: requires some **winrt-Windows-\*** libraries.
 
-* **HCI**  for Linux without D-Bus (uses utiities `hcitool` and ``hciconfig``)  or FreeBSD (uses
-    `hccontrol`) and  requires elevated privileges to access the Host Controller  Interface.   These privileges can be  granted by adding users
-    to a new group "hciusers" that are given permission to call "`sudo -n hci*`" (``hci*`` = hcitool, hciconfig or hccontrol) without entering a password:
-    this can be configured by the system administrator using `visudo` (_security implications should be considered_).   Use visudo to create a file `hciusers`
-    in `/etc/sudoers.d/` (Linux)
-    or `/usr/local/etc/sudoers.d` (FreeBSD), containing the
-    line "`%hciusers ALL=(ALL) NOPASSWD: `" (where  ```` is replaced
-    by "`/usr/bin/hcitool, /usr/bin/hciconfig`" (Linux) or "``/usr/sbin/hccontrol``" (FreeBSD).  In
+* **BleuIO** for all operating systems: requires **pyserial**.   This also requires the  [BleuIO (or BleuIO Pro) USB dongle](https://www.bleuio.com) which is a USB  serial device
+    with its own on-board Bluetooth LE Stack that does not use the host operating system's stack (the host sees the device as a USB serial modem). This
+    works on all operating systems that provide access to serial devices, including macOS and \*BSD.    On some  Linux, users need to be added to the
+    `dialout` group, on others ``uucp``; on FreeBSD this is the ```dialer``` group, on other \*BSD, it 
+    may be `uucp`. 
+
+* **HCI** For Linux and FreeBSD: no extra libraries, but requires root access to the HCI (Host Controller Interface) for Bluetooth devices, using utilities
+    `hcitool` and ``hciconfig`` (Linux) or ```hccontrol``` (FreeBSD).   See below on how to provide such access.      In
     addition, FreeBSD's `hccontrol` needs a patch to allow generic LE Advertising Data to be input.   We have submitted it to FreeBSD as a Pull Request,
-    and you can find it on the [UxPlay Wiki] (https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)
-
+    and you can find it on the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0). _Note that macOS
+    has a utility `/usr/sbin/bluetool` that is similar to ``hcitool``, and might allow the HCI module
+    to be extended to support macOS, but since  the BleuIO module is a working solution for macOS, this has not been attempted (Pull Requests with
+    working implementations are welcome!)._
 
 On Linux, Bluetooth support (using the official Linux Bluetooth stack BlueZ, and D-Bus) must be installed (on Debian-based systems: `sudo apt install bluez bluez-tools`;
 recent Ubuntu releases provide bluez as a snap package).   BlueZ tools 'hcitool' and 'hciconfig' (needed if you use the HCI module
 on Linux) are declared  "deprecated" by the BlueZ developers: some Linux distributions
 have removed them from the  default BleuZ packages, into  "extra" packages with names like "bluez-deprecated".
-
-In addition to standard Python3 libraries, you may need to install the gi, dbus, and psutil Python libraries used by
-uxplay-beacon.py.  On Debian-based systems:
+Also install  psutil Python libraries used by
+uxplay-beacon.py.
+On Debian-based systems:
 
 ```
-sudo apt install python3-gi python3-dbus python3-psutil
+sudo apt install  python3-psutil
 ```
-If a python3-gi package is available in your Linux distribution, install the python3-gobject package which provides it.
 
-For Windows support in the  MSYS2 UCRT64 environment, use pacman -S to
-install `mingw-w64-ucrt-x86_64-python`, ``*-python-gobject``,
-`*-python-psutil`, and ``*-python-pip``.   Then install **winrt**
-bindings using pip (or pip3):
+
+For the **BlueZ** module (Linux), install python3-gi (from which GLib is imported)  and python3-dbus.
+If a python3-gi package is not available in your Linux distribution, use `pip` to install PyGObject instead.
+
+For the **winrt** module, with Windows support in the  MSYS2 UCRT64 environment, use pacman -S to
+install `mingw-w64-ucrt-x86_64-python`,`*-python-psutil`, and ``*-python-pip``.  Then
+install **winrt** bindings using pip (or pip3):
 
 ```
 pip install winrt-Windows.Foundation 
@@ -1614,15 +1612,29 @@ For python >= 3.11, the pip commands on "externally-managed" python installation
 ```
 pip install ....  --break-system-packages
 ```
-
 The option `--break-system-packages` was added as a requirement to make users hesitate before 
 adding packages not provided by  the "external management":
 _this is unnecessarily scary, as in the case of the winrt packages, no breakage can occur_.
 
-UxPlay must  be  run with option "`uxplay -ble`" (so it writes data for the Bluetooth beacon in the default BLE 
-data file `~/.uxplay.ble`), just run ``uxplay-beacon.py`` in a separate terminal.    The python script will start
+For the **BleuIO** module, install pyserial.
+
+For the **HCI** module, create a group `hciusers` to give group members the privilege of using  passwordless ``sudo -n hci*`` (```hci*``` is
+`hcitool` and ``hciconfig`` (Linux), or ```hccontrol``` (FreeBSD), and add users of the module  to this group
+(_security implications should be considered_).   In Linux, use  "`sudo visudo /etc/sudoers.d/hciusers`" (in FreeBSD, 
+file is `/usr/local/etc/sudoers.d/hciusers`) to create a file containing one of the lines
+
+```
+%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig       (Linux)
+%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol                        (FreeBSD)
+```
+
+UxPlay must  be  run with option "`uxplay -ble [path_to_file]`" (so it writes data for the Bluetooth beacon to the default BLE 
+data file `~/.uxplay.ble`, or optionally to the file specifed by its path), then run ``uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]`` in a separate terminal.
+If options HCI or BleuIO are not given, the default module for the operating system will be used (BlueZ for Linux, winrt for Windows, BleuIO for all others).
+
+The python script will start
 Bluetooth LE Service-Discovery advertising when it detects that UxPlay is running by checking if the BLE data file exists, and stop when it no longer detects
-a running UxPlay plus this file (it will restart advertising if UxPlay later reappears).   The script will remain active until stopped with Ctrl+C in its
+a running UxPlay (it will restart advertising if UxPlay later reappears).   The script will remain active until stopped with Ctrl+C in its
 terminal window (or its terminal window is closed).
 
 The beacon script can be more finely controlled using certain options:  these can be given on the command line, or read from
@@ -1633,7 +1645,7 @@ options.   Get help with `man uxplay-beacon` or ``uxplay-beacon.py --help``.
 
 Options are
 
-* `````` where "module" is BleuIO or HCI (no intital ``--``) .   Without this option, the default module used will be **BlueZ** (Linux), **winrt** (Windows), **BleuIO** (all other operating systems).
+* `````` where "module" is BleuIO or HCI (no initial ``--``) .   Without this option, the default module used will be **BlueZ** (Linux), **winrt** (Windows), **BleuIO** (all other operating systems).
 
 
 * `--file ` read beacon options from ```` instead of
@@ -1652,7 +1664,7 @@ These are the only options accepted by the **winrt** module on Windows.   The ot
 it is chosen flexibly in this range to avoid interfering with other tasks the Bluetooth device is carrying out.   The default values are
 advmin = advmax = 100.   The advertisement is broadcast on all three Bluetooth LE advertising channels: 37,38,39.
 
-On a Windows system, the values of these paramaters are set by the operating system, and cannot be set by users.
+On a Windows system, the values of these parameters are set by the operating system, and cannot be set by users.
 
 The **BlueZ** module (Linux) also accepts
 
@@ -1663,28 +1675,27 @@ on the same host has not been tested, and this option might not be useful or nee
 
 The **BleuIO** and **HCI** modules accept
 
-* `--device x` which allows overiding automatically-made choices of serial ports (**BleuIO**) or hci device nodes (**HCI**). This 
+* `--device x` which allows overiding automatically-made choices of serial ports (**BleuIO**) or hci devices (**HCI**). This 
 is probably only useful if the host system has multiple devices that could be used.
 
 
-The native macOS  Bluetooth stack has no documented way for users to send "manufacturer-specific" Bluetooth LE advertisements (such
-that sent for  AirPlay Service Discovery), and  the only support of uxplay-beacon.py on macOS uses a BleuIO USB serial device.
-However macOS provides a low-level utility BlueTool (found at `/usr/sbin/bluetool`) that can send HCI commands, so
-possibly could be used to adapt the python3  **HCI** module to support macOS as well (_working implementations welcome!_).
-__The recommended and working method on macOS is to use a  BleuIO dongle.__ 
+The native macOS  Bluetooth stack does not allow unprivileged users to send "manufacturer-specific" Bluetooth LE advertisements (such
+that sent for  AirPlay Service Discovery), and  the only current support of uxplay-beacon.py on macOS uses a BleuIO USB serial device.
 
 
 
-
-If you wish to test Bluetooth LE Service Discovery on Linux/*BSD, you can disable DNS_SD Service discovery by the avahi-daemon with
+For testing Bluetooth LE Service Discovery  you might wish to disable DNS_SD Service discovery (although the Bluetooth LE Service seems to work if DNS_SD
+is enabled). On Linux, disable the the avahi-daemon that provides DNS_SD with
 
 ```
 $ sudo systemctl mask avahi-daemon.socket
 $ sudo systemctl stop avahi-daemon
 ```
 
+(On FreeBSD,  "`service avahi-daemon stop`"). 
 To restore DNS_SD Service discovery, replace "mask" by "unmask", and "stop" by "start".
 
+
 On Windows, the Bonjour Service is controlled  using **Services Management**: press "Windows + R" to open the Run dialog, 
 run `services.msc`, and click on  **Bonjour Service** in the alphabetic list. This
 will show links for it to be stopped and restarted.
diff --git a/README.txt b/README.txt
index c8d0b63..643576e 100644
--- a/README.txt
+++ b/README.txt
@@ -1594,44 +1594,41 @@ this to see even more of the GStreamer inner workings.
 # Bluetooth LE beacon setup
 
 The python\>=3.6 script for running a Bluetooth LE Service Discovery
-beacon is uxplay-beacon.py. It provides four possible Bluetooth LE
-implementations (loaded as modules):
+beacon is uxplay-beacon.py. Besides the standard python libraries, it
+requires python3-psutils.
 
--   **BlueZ** for Linux systems with D-Bus;
+It provides four possible Bluetooth LE implementations (loaded as
+modules `uxplay_beacon_module_*.py`), which may need additional
+libraries:
 
--   **winrt** for Windows;
+-   **BlueZ** for Linux systems with D-Bus: needs **GLib** (from
+    python3-gi or PyGObject) and **python-dbus**.
 
--   **BleuIO** for the [BleuIO (or BleuIO Pro) USB
-    dongle](https://www.bleuio.com) with its own on-board Bluetooth-LE
-    Stack that does not use the host operating system Bluetooth (the
-    host sees the device as a USB serial modem). This is needed for
-    macOS where the native operating system Bluetooth stack does not
-    allow users to send Bluetooth-LE advertising data of the
-    "manufacturer-specific" type `AdvData=0xFF`. If a BleuIO dongle
-    (currently costs about USD25) is available, the BleuIO version of
-    the python script can be used on many operating systems including
-    macOS, Windows, Linux, FreeBSD, and probably other BSD variants (not
-    tested): it requires python library `python3-pyserial` to be
-    installed. On Linux, users must be members of group `dialout` or
-    sometimes `uucp` (`dialer` on FreeBSD).
+-   **winrt** for Windows: requires some **winrt-Windows-\*** libraries.
 
--   **HCI** for Linux without D-Bus (uses utiities `hcitool` and
-    `hciconfig`) or FreeBSD (uses `hccontrol`) and requires elevated
-    privileges to access the Host Controller Interface. These privileges
-    can be granted by adding users to a new group "hciusers" that are
-    given permission to call "`sudo -n hci*`" (`hci*` = hcitool,
-    hciconfig or hccontrol) without entering a password: this can be
-    configured by the system administrator using `visudo` (*security
-    implications should be considered*). Use visudo to create a file
-    `hciusers` in `/etc/sudoers.d/` (Linux) or
-    `/usr/local/etc/sudoers.d` (FreeBSD), containing the line
-    "`%hciusers ALL=(ALL) NOPASSWD: `" (where `` is
-    replaced by "`/usr/bin/hcitool, /usr/bin/hciconfig`" (Linux) or
-    "`/usr/sbin/hccontrol`" (FreeBSD). In addition, FreeBSD's
-    `hccontrol` needs a patch to allow generic LE Advertising Data to be
-    input. We have submitted it to FreeBSD as a Pull Request, and you
-    can find it on the \[UxPlay Wiki\]
-    (https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)
+-   **BleuIO** for all operating systems: requires **pyserial**. This
+    also requires the [BleuIO (or BleuIO Pro) USB
+    dongle](https://www.bleuio.com) which is a USB serial device with
+    its own on-board Bluetooth LE Stack that does not use the host
+    operating system's stack (the host sees the device as a USB serial
+    modem). This works on all operating systems that provide access to
+    serial devices, including macOS and \*BSD. On some Linux, users need
+    to be added to the `dialout` group, on others `uucp`; on FreeBSD
+    this is the `dialer` group, on other \*BSD, it may be `uucp`.
+
+-   **HCI** For Linux and FreeBSD: no extra libraries, but requires root
+    access to the HCI (Host Controller Interface) for Bluetooth devices,
+    using utilities `hcitool` and `hciconfig` (Linux) or `hccontrol`
+    (FreeBSD). See below on how to provide such access. In addition,
+    FreeBSD's `hccontrol` needs a patch to allow generic LE Advertising
+    Data to be input. We have submitted it to FreeBSD as a Pull Request,
+    and you can find it on the [UxPlay
+    Wiki](https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0).
+    *Note that macOS has a utility `/usr/sbin/bluetool` that is similar
+    to `hcitool`, and might allow the HCI module to be extended to
+    support macOS, but since the BleuIO module is a working solution for
+    macOS, this has not been attempted (Pull Requests with working
+    implementations are welcome!).*
 
 On Linux, Bluetooth support (using the official Linux Bluetooth stack
 BlueZ, and D-Bus) must be installed (on Debian-based systems:
@@ -1640,21 +1637,19 @@ bluez as a snap package). BlueZ tools 'hcitool' and 'hciconfig' (needed
 if you use the HCI module on Linux) are declared "deprecated" by the
 BlueZ developers: some Linux distributions have removed them from the
 default BleuZ packages, into "extra" packages with names like
-"bluez-deprecated".
+"bluez-deprecated". Also install psutil Python libraries used by
+uxplay-beacon.py. On Debian-based systems:
 
-In addition to standard Python3 libraries, you may need to install the
-gi, dbus, and psutil Python libraries used by uxplay-beacon.py. On
-Debian-based systems:
+    sudo apt install  python3-psutil
 
-    sudo apt install python3-gi python3-dbus python3-psutil
+For the **BlueZ** module (Linux), install python3-gi (from which GLib is
+imported) and python3-dbus. If a python3-gi package is not available in
+your Linux distribution, use `pip` to install PyGObject instead.
 
-If a python3-gi package is available in your Linux distribution, install
-the python3-gobject package which provides it.
-
-For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
-install `mingw-w64-ucrt-x86_64-python`, `*-python-gobject`,
-`*-python-psutil`, and `*-python-pip`. Then install **winrt** bindings
-using pip (or pip3):
+For the **winrt** module, with Windows support in the MSYS2 UCRT64
+environment, use pacman -S to install
+`mingw-w64-ucrt-x86_64-python`,`*-python-psutil`, and `*-python-pip`.
+Then install **winrt** bindings using pip (or pip3):
 
     pip install winrt-Windows.Foundation 
     pip install winrt-Windows.Foundation.Collections 
@@ -1671,15 +1666,33 @@ users hesitate before adding packages not provided by the "external
 management": *this is unnecessarily scary, as in the case of the winrt
 packages, no breakage can occur*.
 
-UxPlay must be run with option "`uxplay -ble`" (so it writes data for
-the Bluetooth beacon in the default BLE data file `~/.uxplay.ble`), just
-run `uxplay-beacon.py` in a separate terminal. The python script will
-start Bluetooth LE Service-Discovery advertising when it detects that
-UxPlay is running by checking if the BLE data file exists, and stop when
-it no longer detects a running UxPlay plus this file (it will restart
-advertising if UxPlay later reappears). The script will remain active
-until stopped with Ctrl+C in its terminal window (or its terminal window
-is closed).
+For the **BleuIO** module, install pyserial.
+
+For the **HCI** module, create a group `hciusers` to give group members
+the privilege of using passwordless `sudo -n hci*` (`hci*` is `hcitool`
+and `hciconfig` (Linux), or `hccontrol` (FreeBSD), and add users of the
+module to this group (*security implications should be considered*). In
+Linux, use "`sudo visudo /etc/sudoers.d/hciusers`" (in FreeBSD, file is
+`/usr/local/etc/sudoers.d/hciusers`) to create a file containing one of
+the lines
+
+    %hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig       (Linux)
+    %hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol                        (FreeBSD)
+
+UxPlay must be run with option "`uxplay -ble [path_to_file]`" (so it
+writes data for the Bluetooth beacon to the default BLE data file
+`~/.uxplay.ble`, or optionally to the file specifed by its path), then
+run `uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]` in a separate
+terminal. If options HCI or BleuIO are not given, the default module for
+the operating system will be used (BlueZ for Linux, winrt for Windows,
+BleuIO for all others).
+
+The python script will start Bluetooth LE Service-Discovery advertising
+when it detects that UxPlay is running by checking if the BLE data file
+exists, and stop when it no longer detects a running UxPlay (it will
+restart advertising if UxPlay later reappears). The script will remain
+active until stopped with Ctrl+C in its terminal window (or its terminal
+window is closed).
 
 The beacon script can be more finely controlled using certain options:
 these can be given on the command line, or read from a configuration
@@ -1691,7 +1704,7 @@ Get help with `man uxplay-beacon` or `uxplay-beacon.py --help`.
 
 Options are
 
--   `` where "module" is BleuIO or HCI (no intital `--`) .
+-   `` where "module" is BleuIO or HCI (no initial `--`) .
     Without this option, the default module used will be **BlueZ**
     (Linux), **winrt** (Windows), **BleuIO** (all other operating
     systems).
@@ -1722,7 +1735,7 @@ The other modules accept
     are advmin = advmax = 100. The advertisement is broadcast on all
     three Bluetooth LE advertising channels: 37,38,39.
 
-On a Windows system, the values of these paramaters are set by the
+On a Windows system, the values of these parameters are set by the
 operating system, and cannot be set by users.
 
 The **BlueZ** module (Linux) also accepts
@@ -1738,28 +1751,25 @@ The **BlueZ** module (Linux) also accepts
 The **BleuIO** and **HCI** modules accept
 
 -   `--device x` which allows overiding automatically-made choices of
-    serial ports (**BleuIO**) or hci device nodes (**HCI**). This is
-    probably only useful if the host system has multiple devices that
-    could be used.
+    serial ports (**BleuIO**) or hci devices (**HCI**). This is probably
+    only useful if the host system has multiple devices that could be
+    used.
 
-The native macOS Bluetooth stack has no documented way for users to send
-"manufacturer-specific" Bluetooth LE advertisements (such that sent for
-AirPlay Service Discovery), and the only support of uxplay-beacon.py on
-macOS uses a BleuIO USB serial device. However macOS provides a
-low-level utility BlueTool (found at `/usr/sbin/bluetool`) that can send
-HCI commands, so possibly could be used to adapt the python3 **HCI**
-module to support macOS as well (*working implementations welcome!*).
-**The recommended and working method on macOS is to use a BleuIO
-dongle.**
+The native macOS Bluetooth stack does not allow unprivileged users to
+send "manufacturer-specific" Bluetooth LE advertisements (such that sent
+for AirPlay Service Discovery), and the only current support of
+uxplay-beacon.py on macOS uses a BleuIO USB serial device.
 
-If you wish to test Bluetooth LE Service Discovery on Linux/\*BSD, you
-can disable DNS_SD Service discovery by the avahi-daemon with
+For testing Bluetooth LE Service Discovery you might wish to disable
+DNS_SD Service discovery (although the Bluetooth LE Service seems to
+work if DNS_SD is enabled). On Linux, disable the the avahi-daemon that
+provides DNS_SD with
 
     $ sudo systemctl mask avahi-daemon.socket
     $ sudo systemctl stop avahi-daemon
 
-To restore DNS_SD Service discovery, replace "mask" by "unmask", and
-"stop" by "start".
+(On FreeBSD, "`service avahi-daemon stop`"). To restore DNS_SD Service
+discovery, replace "mask" by "unmask", and "stop" by "start".
 
 On Windows, the Bonjour Service is controlled using **Services
 Management**: press "Windows + R" to open the Run dialog, run