Platform Notes

The same pipeline runs on Windows, macOS and Linux, but each operating system guards the hardware in its own way – and most of the guards fail silently, in a way that looks exactly like a device that is switched off. This page lists what each platform needs.

For

Windows

macOS

Linux

Bluetooth amplifiers (BCI Core, Unicorn)

one Bluetooth radio enabled at a time

Bluetooth permission for the application that runs Python

raw-socket capabilities on the Python interpreter

Keyboard

nothing

Input Monitoring permission for that application

a graphical session

UDPReceiver on its default port, 1000

works, unless the port lies in a reserved range

refused: ports below 1024 need administrator rights

refused: ports below 1024 need root

GDS amplifiers (g.USBamp, g.HIamp, g.Nautilus)

the GDS service

the gdsd service

the gdsd service

Unicorn driver (gtec-unicorn)

x64

Apple silicon

x86_64

ParadigmPresenter

yes

no

no

macOS

Permissions belong to the application that runs Python – Terminal, VS Code, or whatever launched the script – and are granted under System Settings > Privacy & Security. A Bluetooth amplifier needs Bluetooth: without it a scan returns an empty list, with no error, and reads exactly like an amplifier that is off. The Keyboard needs Input Monitoring: without it no key reaches the pipeline. The keyboard library may still log that the process “is not trusted”; that message is about Accessibility, which key capture does not need. macOS checks permissions when an application starts, so quit and reopen it after granting one.

Pick a UDP port from 1024 to 49151. A UDPReceiver left on its default port 1000 cannot listen, the pipeline’s condition turns to Error, and the message says why: “Could not listen on 127.0.0.1:1000 – [Errno 13] Permission denied. … Ports below 1024 are privileged on macOS and Linux, so 1000 needs root. Choose one from 1024 to 49151, and point the sender at the same port.” Pass port= on the receiver and on whatever sends to it.

The Unicorn needs the main thread’s run loop. macOS delivers every Bluetooth callback of the Unicorn’s driver (gtec-unicorn 0.1.1 or later, which the devices extra installs) on the main thread’s run loop, and only the main thread can run it. app.run() does. A script without a window, whose main thread waits in time.sleep, receives nothing: the first read fails with “… the main run loop is not being serviced, and IOBluetooth delivers RFCOMM data there”, and after three failed reads the node ends the run.

The GDS amplifiers go through the gdsd service, a launchd daemon (com.gtec.gdsd). Install it from g.tec’s release package, which includes the FTDI driver a g.Nautilus base station needs. If an amplifier stops opening after a cable was pulled or a process was killed, restart the service with sudo launchctl kickstart -k system/com.gtec.gdsd; its log is /usr/local/var/log/gdsd.log, readable with administrator rights. GDS 1.24.0 answered every request about 2 s late on macOS – listing the devices took 2.0 s, and a g.HIamp’s first samples arrived about 9 s after start() – and 1.24.1 removes the wait: the same listing takes 0.03 s.

Linux

A Bluetooth amplifier needs raw-socket capabilities on the Python interpreter. Without them the scan fails at the operating system and reports no adapter. Grant them to the interpreter’s real binary:

sudo setcap 'cap_net_raw,cap_net_admin+eip' "$(readlink -f "$(which python)")"

The grant applies to processes started afterwards, and to every script run with that interpreter.

The Keyboard needs a graphical session. On a machine with no display the keyboard library cannot even be imported, which is why Keyboard loads it only when the pipeline starts.

GDS runs as the systemd service gdsd. The package installs it without starting it: sudo systemctl enable --now gdsd, and sudo systemctl restart gdsd after a device stops opening.

x86_64 only. g.Pype publishes no Linux wheel for aarch64, so it does not install on an ARM Linux machine.

Windows

One Bluetooth radio at a time. With a computer’s internal radio enabled, a second one – the g.tec USB dongle, say – sits in Device Manager with problem code 31 and cannot be used. Disable the one you do not want.

A UDP port can be reserved. WinError 10013 on a receiver means access denied, not a port in use: the port lies in a range Windows keeps for itself. netsh interface ipv4 show excludedportrange protocol=udp lists them; choose a port outside every range.

A server without a screen is Deployment Scenarios.