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

Add support for bluetooth LE beacon service discovery

Browse Source 
based on remarkable work by @connorh315 on getting this working
This commit is contained in:
F. Duncanh
2025-09-15 14:19:05 -04:00
parent ae52b2bd3a
commit 469f385502
6 changed files with 782 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
README.md
View File

@@ -2,6 +2,14 @@
### **Now developed at the GitHub site <https://github.com/FDH2/UxPlay> (where ALL user issues should be posted, and latest versions can be found).**
- **NEW on github**: Support for **service discovery using a Bluetooth LE "beacon"** (as an alternative to Bonjour/Rendezvous DNS-SD
service discovery). The user must set up a Bluetooth LE "beacon", (a USB 4.0 or later "dongle" can be used). See instructions
below. The beacon runs independently of UxPlay and regularly broadcasts a Bluetooth LE ("Low Energy") 44 byte packet informing nearby iOS/macOS devices of
the local IPv4 network address of the UxPlay server, which they can use to contact it on TCP port 7000.
Instructions for manually setting up such a beacon in Linux are [given below](#bluetooth-le-beacon-setup).
__It is hoped that users will submit Pull Requests contributing scripts for automating beacon setup on all platforms.
(Python may be an appropriate language choice)__
- **NEW on github**: (for Linux/*BSD Desktop Environments using D-Bus). New option `-scrsv <n>` provides screensaver inhibition (e.g., to
prevent screensaver function while watching mirrored videos without keyboard or mouse
activity): n = 0 (off) n=1 (on during video activity) n=2 (always on while UxPlay is running).
@@ -201,7 +209,10 @@ necessary that the local network also be of the ".local" mDNS-based
type). On Linux and BSD Unix servers, this is usually provided by
[Avahi](https://www.avahi.org), through the avahi-daemon service, and is
included in most Linux distributions (this service can also be provided
by macOS, iOS or Windows servers).
by macOS, iOS or Windows servers). There is now an alternative Service
discovery method, using a Bluetooth LE "beacon" See below
for [instructions](#bluetooth-le-beacon-setup).
Connections to the UxPlay server by iOS/MacOS clients can be initiated
both in **AirPlay Mirror** mode (which streams lossily-compressed AAC
@@ -532,7 +543,9 @@ as comments and ignored.
**Run uxplay in a terminal window**. On some systems, you can specify
fullscreen mode with the `-fs` option, or toggle into and out of
fullscreen mode with F11 or (held-down left Alt)+Enter keys. Use Ctrl-C
(or close the window) to terminate it when done. If the UxPlay server is
(or close the window) to terminate it when done.
If the UxPlay server is
not seen by the iOS client's drop-down "Screen Mirroring" panel, check
that your DNS-SD server (usually avahi-daemon) is running: do this in a
terminal window with `systemctl status avahi-daemon`. If this shows the
@@ -547,6 +560,10 @@ opened: **if a firewall is active, also open UDP port 5353 (for mDNS
queries) needed by Avahi**. See [Troubleshooting](#troubleshooting)
below for help with this or other problems.
Note that there is now an
alternative Service Discovery method using a Bluetooth LE beacon.
See the instructions on [Bluetooth beacon setup](#bluetooth-le-beacon-setup).
- Unlike an Apple TV, the UxPlay server does not by default require
clients to initially "pair" with it using a pin code displayed by
the server (after which the client "trusts" the server, and does not
@@ -1424,6 +1441,12 @@ that (unlike dumped video) the dumped audio is currently only useful for
debugging, as it is not containerized to make it playable with standard
audio players.*
**-ble *filename***. Enable Bluetooth beacon Service Discovery.
The PID and process name of the UxPlay process is recorded in
*filename*, which must be the full path to a writeable file. (This file is created
when UxPlay starts and deleted when it stops.) __See below for beacon setup
instructions.__
**-d \[n\]** Enable debug output; optional argument n=1 suppresses audio/video
packet data in debug output.
Note: this does not show GStreamer error or
@@ -1433,8 +1456,181 @@ uxplay. To see GStreamer information messages, set GST_DEBUG=4; for
DEBUG messages, GST_DEBUG=5; increase this to see even more of the
GStreamer inner workings.
# Troubleshooting
# Bluetooth LE beacon setup
When uxplay is started with the option `uxplay -ble <path-to-writeable-file>`, it writes a 20 byte data file
containing (4 bytes) the process ID (PID) as a uint32_t 32-bit unsigned integer, and
(16 bytes) up to 15 bytes of the process name (usually "uxplay") as a null-terminated string,
padded with zeroes to fill 16 bytes. The file is deleted if UxPlay is terminated normally (without a segfault),
and could be used to determine if an instance of uxplay is running. **This file is provided for possible future use
in a script for controlling the beacon, and will not be used here**.
You may need to use a cheap USB Bluetooth dongle if your system does not have Bluetooth 4.0 or later,
or will not let you use it for LE (Low Energy) transmissions.
These instructions are tested on Linux using the Bluez Bluetooth stack. They use the `hcitool` and ``hciconfig``
utilities which directly access the HCI stack, and need elevated privileges (use `sudo`). These utilities
have been declared "deprecated" and "obsolete" by BlueZ developers: on Debian-based Linux `sudo apt install bluez`
still provides `hcitool`, but on some other Linux distributions, it is split off from the main BlueZ package into an "extra" package
with a name like "bluez-deprecated". If we get the AirPlay beacon to work using the newer `bluetoothctl` utility, these instructions will be
updated.
* **These manual instructions will hopefully be soon superseded by e.g. python scripts that automate beacon control, probably using D-Bus on Linux. Please
submit any such scripts you get working for possible packaging together with UxPlay**. Note that the Apple Service Discovery beacon is
not a standard "**ibeacon**", and cannot be set up with unmodified "ibeacon"-specific applications.
* For testing Bluetooth beacon Service Discovery on Linux, you will need to suppress the avahi-daemon which
provides DNS-SD Service Discovery on UxPlay's Host system (replace `mask` and ``stop``
below by `unmask` and ``start`` to restore DNS-SD service).;
```
$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon
```
Then verify that uxplay will not start without the `-ble <filename>` option.
Before starting, check that you have a Bluetooth device with "`hcitool dev`"
```
$hcitool dev
Devices:
hci1 E8:EA:6A:7C:3F:CC
hci0 08:BE:AC:40:A9:DC
```
This shows two devices with their MAC addresses. You can use "`hciconfig -i`" to see which version of Bluetooth they
implement: we require Bluetooth v4.0 or later. Choose which to use (we will use hci0), and reset it.
```
$ sudo hciconfig hci0 reset
```
* **Step 1.** First reconfigure the Bluetooth device (hci0):
`hcitool` sends HCI commands as a sequence of 1-byte hexadecimal octets. It echoes the length (here `plen` = 15 bytes) and content
of the sequence it sends to the Bluetooth HCI stack, and of the 4-byte "HCI Event" response it gets.
Only the last byte of the response is important: `00` means the command succeded (other values are error codes).
```
$ sudo hcitool -i hci0 cmd 0x08 0x0006 0xa0 0x00 0xa0 0x00 0x03 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x07 0x00
< HCI Command: ogf 0x08, ocf 0x0006, plen 15
A0 00 A0 00 03 01 00 00 00 00 00 00 00 07 00
> HCI Event: 0x0e plen 4
02 06 20 00
```
The above command configures the beacon: "`cmd 0x08 0x006`" means HCI LE (ogf=0x08) command number 6 (ocf=0x0006) of
the Blutooth LE stack.
The first two message bytes "`0xa0 0x00`" means a 2-byte "unsigned short" value 0x00a0. (uint16_t integers such as 0xabcd are represented as two bytes "`0xcd, 0xab`"). This is the minimum interval AdvMin between
beacon broadcasts, which are essentially simultaneous on all three advertising channels. The next two entries represent the maximum interval AdvMax, also set to 0x00a0,
which means 100 msec (200 msec would be 2 * 0x00a0 = 0x0140 or "`0x40 0x01`"). Setting AdvMin = AdvMax fixes the interval between transmissions.
If AdvMin < AdvMax, the timing of each broadcast event relative to the previous one can be chosen flexibly to not overlap with any other task the bluetooth socket is carrying out.
The allowed range of these parameters is 0x00a0 = 100 msec <= AdvMin <= AdvMax <= 0x4000 = 10.24 sec.
An Apple TV (Gen 3) seems to use a fixed interval of 180 msec = 0x0120 ("`0x20 0x01`").
The sixth byte TxAdd = "`0x01`" says that a random MAC "advertisement address"" AdvAddr for the Bluetooth device will be sent with the advertisement. If you wish to send the true
hardware MAC address of the Bluetooth device, replace this byte by "`0x00`".
__These are the only parameters you might want to vary__. The fifth byte 0x03 is the Advertising PDU type "ADV_NONCONN_IND" (a beacon that transmits without accepting connections)
and the fourteenth byte 0x07 is a flag 0000 0111 that says to use all three Bluetooth LE advertising channels.
* **Step 2.** (**Optional: skip this if you changed byte 6 of the initial configuration message from** "``0x01``" **to** "`0x00`".)
Use HCI LE command 5 (ocf=0x0005) to
set private "advertising address" AdvAddr, which substitutes for the public MAC address of the Bluetooth device.
This uses six random bytes r1,..,r6 and enters them as
` r1 , r2 , r3, r4, r5, r0 = (r6 | 0x03)`, where the 6th byte has been masked with 0x03 = 00000011 so its last two bits are on,
and the value r0 is restricted to 64 values "`0xrs`" where the second
hexadecimal digit ``s`` is one of {3, 7, b, f}, which indicates a "static random" private address that is guaranteed to not
change between device reboots. Note that Apple TV's use random private addresses without applying a mask to r6 to distinguish
between different types.
```
$sudo hcitool -i hci0 cmd 0x08 0x0005 0x52 0xaa 0xaa 0x3a 0xb4 0x2f
< HCI Command: ogf 0x08, ocf 0x0005, plen 6
52 AA AA 3A B4 2F
> HCI Event: 0x0e plen 4
02 05 20 00
```
On a Bluetooth packet sniffer with wireshark, this address displays as: **Advertising Address: 2f:b4:3a:aa:aa:52**
* **Step 3.** Now provide the advertising message, with HCI LE command 8 (ocf=0x0008):
This sends a 32 byte message to the HCI LE stack, where the first byte is the length (here 0x0c = 12 bytes) of the significant part of
the following 31 bytes: 12 significant bytes, padded with 19 zeros to a total message length of 32 bytes. (`hcitool` requires a message padded to the full
32 bytes, but only sends the significant bytes to the Bluetooth LE stack.)
```
$ sudo hcitool -i hci0 cmd 0x08 0x0008 0x0c 0x0b 0xff 0x4c 0x00 0x09 0x06 0x03 0x30 0xc0 0xa8 0x01 0xfd 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
< HCI Command: ogf 0x08, ocf 0x0008, plen 32
0C 0B FF 4C 00 09 06 03 30 C0 A8 01 FD 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00
> HCI Event: 0x0e plen 4
01 08 20 00
```
The only parts of this message that you must change are the four bytes 10,11,12,13, of the IPv4 address, here "` 0xc0 0xa8 0x01 0xfd `", (decimal 192 168 1 253, an IPv4 address 192.168.1.253)
which should be an IPv4 address at which the UxPlay server can receive requests from iOS/macOS clients at TCP port 7000. You need to find what IPv4 address will work
on the computer that hosts UxPlay (use `ifconfig`), convert each of the four numbers from decimal to hexadecimal, and replace bytes 13-16 of the message by them.
* **Step 4.** Start advertising by the beacon with Bluetooth LE command 10 (ocf = 0x000a) and 1-byte message "`0x01`" = "on".
```
$ sudo hcitool -i hci0 cmd 0x08 0x000a 0x01
< HCI Command: ogf 0x08, ocf 0x000a, plen 1
01
> HCI Event: 0x0e plen 4
02 0A 20 00
```
(To stop advertising, use this command to send the 1-byte message "`0x00`" = "off".)
For creating a higher-level script, it might be useful to know that the length 0C = 12 bytes advertisement sent in step 3 has a single "Advertising Protocol Data Unit" (PDU):
* 0B FF 4C 00 09 06 03 30 C0 A8 01 FD: length 0B = 11 bytes, consisting of: FF ( type = manufacturer-specific) 4C 00 (manufacturer code = 0x004c, Apple ) manufacturer data 09 06 03 30 C0 A8 01 FD
The manufacturer data defined by Apple consists of a single Apple data unit: 09 (Apple type = AirPlay), 06 (Apple data length 6 bytes) Apple data 03 30 XX XX XX XX, broken down into 03 (flags: 0000 0011) 30 (a seed)
XX XX XX XX (IPv4 network address, written as four hexadecimal octets in standard order). (Apple TV's use a random private "AdvAddr" address as described above, and periodically update it at about 20 min intervals, each time
increasing the seed by 1.)
Apple TV's also insert a type-1 ("Flags") 2-byte PDU "`02 01 1A`" before the manufacturer-specific PDU, increasing the significant length of the message to 0xf = 15 bytes.
It turns out that the "Flags" PDU is "optional" for advertisements like beacons that do not allow client connections:
in our tests on v4.0 and later dongles, Service Discovery still worked fine after dropping the "Flags" PDU.
Both Linux and Windows have high-level interfaces that support users sending Advertising PDU's, but restricted to
type 0xff "manufacturer-specific-data" only, without any "Flags". These should be used for automating beacon setup, and
are: (Linux) Bluez [LEAdvertisingManager1](https://github.com/bluez/bluez/blob/master/test/example-advertisement)
and (Windows 10/11) [BluetoothLEAdvertisementPublisherClass](https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.advertisement.bluetoothleadvertisementpublisher)
(with an [example](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/uwp/devices-sensors/ble-beacon.md)).
**We don't know if these instructions can be modified to advertise IPv6 addresses: if you know of any verified support for Bluetooth LE IPv6 Service Discovery in newer AppleTV models,
please let us know. Simply replacing the 4-byte IPv4 address with a 16-byte IPv6 address (and adjusting the lengths at bytes 1, 5 and 10) does not seem to work, although perhaps
we did not find the right value for byte 11 ("Apple Flags"). If Apple's Bluetooth LE Service Discovery has IPv6 support, we need to examine the beacon advertisement packet
for IPv6 addresses with a Bluetooth sniffer.**
# Troubleshooting
Note: `uxplay` is run from a terminal command line, and informational
messages are written to the terminal.
@@ -1776,7 +1972,8 @@ what version UxPlay claims to be.
# Changelog
xxxx 2025-08-11 Render Audio cover-art inside UxPlay with -ca option (no file
specified). (D-Bus based) option -scrsv <n> to inhibit screensaver while UxPlay
is running (Linux/*BSD only).
is running (Linux/*BSD only). Add support for Service Discovery using a
Bluetooth LE beacon.
1.72.2 2025-07-07 Fix bug (typo) in DNS_SD advertisement introduced with -pw
option. Update llhttp to v 9.3.0