morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-15 00:34:05 +09:00
Code Issues Packages Projects Releases Wiki Activity

README updates for beacon

Browse Source
This commit is contained in:
F. Duncanh
2026-03-22 00:44:23 -04:00
parent f54d561389
commit 3b4a15f461
3 changed files with 222 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
README.html
View File

@@ -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.</p>
<h1 id="bluetooth-le-beacon-setup">Bluetooth LE beacon setup</h1>
<p>The python&gt;=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):</p>
Discovery beacon is uxplay-beacon.py. Besides the standard python
libraries, it requires python3-psutils.</p>
<p>It provides four possible Bluetooth LE implementations (loaded as
modules <code>uxplay_beacon_module_*.py</code>), which may need
additional libraries:</p>
<ul>
<li><p><strong>BlueZ</strong> for Linux systems with D-Bus;</p></li>
<li><p><strong>winrt</strong> for Windows;</p></li>
<li><p><strong>BleuIO</strong> for the <a
href="https://www.bleuio.com">BleuIO (or BleuIO Pro) USB dongle</a> 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 <code>AdvData=0xFF</code>. 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 <code>python3-pyserial</code> to be
installed. On Linux, users must be members of group <code>dialout</code>
or sometimes <code>uucp</code> (<code>dialer</code> on
FreeBSD).</p></li>
<li><p><strong>HCI</strong> for Linux without D-Bus (uses utiities
<code>hcitool</code> and <code>hciconfig</code>) or FreeBSD (uses
<code>hccontrol</code>) 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
“<code>sudo -n hci*</code>” (<code>hci*</code> = hcitool, hciconfig or
hccontrol) without entering a password: this can be configured by the
system administrator using <code>visudo</code> (<em>security
implications should be considered</em>). Use visudo to create a file
<code>hciusers</code> in <code>/etc/sudoers.d/</code> (Linux) or
<code>/usr/local/etc/sudoers.d</code> (FreeBSD), containing the line
“<code>%hciusers ALL=(ALL) NOPASSWD: &lt;hcitools&gt;</code>” (where
<code>&lt;hcitools&gt;</code> is replaced by
“<code>/usr/bin/hcitool, /usr/bin/hciconfig</code>” (Linux) or
“<code>/usr/sbin/hccontrol</code>” (FreeBSD). In addition, FreeBSD’s
<li><p><strong>BlueZ</strong> for Linux systems with D-Bus: needs
<strong>GLib</strong> (from python3-gi or PyGObject) and
<strong>python-dbus</strong>.</p></li>
<li><p><strong>winrt</strong> for Windows: requires some
<strong>winrt-Windows-*</strong> libraries.</p></li>
<li><p><strong>BleuIO</strong> for all operating systems: requires
<strong>pyserial</strong>. This also requires the <a
href="https://www.bleuio.com">BleuIO (or BleuIO Pro) USB dongle</a>
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 <code>dialout</code> group, on
others <code>uucp</code>; on FreeBSD this is the <code>dialer</code>
group, on other *BSD, it may be <code>uucp</code>.</p></li>
<li><p><strong>HCI</strong> For Linux and FreeBSD: no extra libraries,
but requires root access to the HCI (Host Controller Interface) for
Bluetooth devices, using utilities <code>hcitool</code> and
<code>hciconfig</code> (Linux) or <code>hccontrol</code> (FreeBSD). See
below on how to provide such access. In addition, FreeBSD’s
<code>hccontrol</code> 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)</p></li>
you can find it on the <a
href="https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0">UxPlay
Wiki</a>. <em>Note that macOS has a utility
<code>/usr/sbin/bluetool</code> that is similar to <code>hcitool</code>,
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!).</em></p></li>
</ul>
<p>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”.</p>
<p>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:</p>
<pre><code>sudo apt install python3-gi python3-dbus python3-psutil</code></pre>
<p>If a python3-gi package is available in your Linux distribution,
install the python3-gobject package which provides it.</p>
<p>For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install <code>mingw-w64-ucrt-x86_64-python</code>,
<code>*-python-gobject</code>, <code>*-python-psutil</code>, and
<code>*-python-pip</code>. Then install <strong>winrt</strong> bindings
using pip (or pip3):</p>
“bluez-deprecated”. Also install psutil Python libraries used by
uxplay-beacon.py. On Debian-based systems:</p>
<pre><code>sudo apt install python3-psutil</code></pre>
<p>For the <strong>BlueZ</strong> 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 <code>pip</code> to
install PyGObject instead.</p>
<p>For the <strong>winrt</strong> module, with Windows support in the
MSYS2 UCRT64 environment, use pacman -S to install
<code>mingw-w64-ucrt-x86_64-python</code>,<code>*-python-psutil</code>,
and <code>*-python-pip</code>. Then install <strong>winrt</strong>
bindings using pip (or pip3):</p>
<pre><code>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</p>
requirement to make users hesitate before adding packages not provided
by the “external management”: <em>this is unnecessarily scary, as in the
case of the winrt packages, no breakage can occur</em>.</p>
<p>UxPlay must be run with option “<code>uxplay -ble</code>” (so it
writes data for the Bluetooth beacon in the default BLE data file
<code>~/.uxplay.ble</code>), just run <code>uxplay-beacon.py</code> 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).</p>
<p>For the <strong>BleuIO</strong> module, install pyserial.</p>
<p>For the <strong>HCI</strong> module, create a group
<code>hciusers</code> to give group members the privilege of using
passwordless <code>sudo -n hci*</code> (<code>hci*</code> is
<code>hcitool</code> and <code>hciconfig</code> (Linux), or
<code>hccontrol</code> (FreeBSD), and add users of the module to this
group (<em>security implications should be considered</em>). In Linux,
use “<code>sudo visudo /etc/sudoers.d/hciusers</code>” (in FreeBSD, file
is <code>/usr/local/etc/sudoers.d/hciusers</code>) to create a file
containing one of the lines</p>
<pre><code>%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig (Linux)
%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol (FreeBSD)</code></pre>
<p>UxPlay must be run with option
“<code>uxplay -ble [path_to_file]</code>” (so it writes data for the
Bluetooth beacon to the default BLE data file
<code>~/.uxplay.ble</code>, or optionally to the file specifed by its
path), then run
<code>uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]</code> 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).</p>
<p>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).</p>
<p>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 <code>~/.uxplay.beacon</code>, if it exists.
@@ -1637,7 +1653,7 @@ or <code>uxplay-beacon.py --help</code>.</p>
<p>Options are</p>
<ul>
<li><p><code>&lt;module&gt;</code> where “module” is BleuIO or HCI (no
intital <code>--</code>) . Without this option, the default module used
initial <code>--</code>) . Without this option, the default module used
will be <strong>BlueZ</strong> (Linux), <strong>winrt</strong>
(Windows), <strong>BleuIO</strong> (all other operating
systems).</p></li>
@@ -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.</li>
</ul>
<p>On a Windows system, the values of these paramaters are set by the
<p>On a Windows system, the values of these parameters are set by the
operating system, and cannot be set by users.</p>
<p>The <strong>BlueZ</strong> module (Linux) also accepts</p>
<ul>
@@ -1683,25 +1699,23 @@ needed.</em></li>
accept</p>
<ul>
<li><code>--device x</code> which allows overiding automatically-made
choices of serial ports (<strong>BleuIO</strong>) or hci device nodes
choices of serial ports (<strong>BleuIO</strong>) or hci devices
(<strong>HCI</strong>). This is probably only useful if the host system
has multiple devices that could be used.</li>
</ul>
<p>The native macOS Bluetooth stack has no documented way for users to
<p>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 <code>/usr/sbin/bluetool</code>)
that can send HCI commands, so possibly could be used to adapt the
python3 <strong>HCI</strong> module to support macOS as well
(<em>working implementations welcome!</em>). <strong>The recommended and
working method on macOS is to use a BleuIO dongle.</strong></p>
<p>If you wish to test Bluetooth LE Service Discovery on Linux/*BSD, you
can disable DNS_SD Service discovery by the avahi-daemon with</p>
for AirPlay Service Discovery), and the only current support of
uxplay-beacon.py on macOS uses a BleuIO USB serial device.</p>
<p>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</p>
<pre><code>$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon</code></pre>
<p>To restore DNS_SD Service discovery, replace “mask” by “unmask”, and
“stop” by “start”.</p>
<p>(On FreeBSD, “<code>service avahi-daemon stop</code>”). To restore
DNS_SD Service discovery, replace “mask” by “unmask”, and “stop” by
“start”.</p>
<p>On Windows, the Bonjour Service is controlled using <strong>Services
Management</strong>: press “Windows + R” to open the Run dialog, run
<code>services.msc</code>, and click on <strong>Bonjour Service</strong>