Bifrost

Remote Mouse & Keyboard Gateway for AmigaOS 3.x

Bifrost enables seamless mouse and keyboard forwarding from a PC to a AmigaOs 3.x over TCP/IP. Control your Amiga remotely with smooth, low-latency input using a piecewise-linear acceleration curve and sub-pixel precision. Includes toggle switching to alternate between PC and Amiga input control.

Features

✅ Remote Input Forwarding - Real-time mouse and keyboard events from PC to Amiga
✅ Smooth Mouse Movement - Piecewise-linear acceleration curve (sub-pixel accumulation)
✅ Low-Latency Streaming - TCP_NODELAY for immediate packet delivery
✅ Keyboard Support - Full keyboard forwarding with toggle capability
✅ Input Toggle - Scroll Lock or screen edge trigger to switch PC ↔ Amiga control
✅ Edge Detection - Screen edge/corner switching for focus control
✅ Auto-Discovery - UDP broadcast — no IP configuration needed
✅ JSON Configuration - No code edits — configure via bifrost_config.json
✅ Systray Status Icon - Green icon when Amiga connected, grey when disconnected
✅ Python Server - Cross-platform PC side daemon (Windows/Linux/macOS)

Quick Start

1. PC Side

cd server
./setup_venv.sh          # Windows: pwsh .\setup_venv.ps1
python main.py            # Windows: .venv\Scripts\python main.py

2. Amiga Side

Bifrost

Done! Server auto-discovers and connects. Toggle focus with Scroll Lock.

Installation

PC Requirements

Python 3.8+
Network connectivity to Amiga (Ethernet or USB FTDI)

Amiga Requirements

Any Amiga with a TCP/IP stack (AmiTCP, Roadshow, or ApolloOS networking) — no specific accelerator or chipset required
AmigaOS 3.x
Network connectivity to PC

Setup

1. Set up the Python environment (creates .venv, installs dependencies):

cd server
./setup_venv.sh          # Windows: pwsh .\setup_venv.ps1

2. Start server:

python main.py                    # Default port 7890 (Windows: .venv\Scripts\python main.py)
python main.py --port 9999        # Custom port

2b. (optional) Auto-start at login:

Windows:
```
cd server
pwsh .\install_startup.ps1
```
Adds a shortcut to your Startup folder so Bifrost launches automatically at every login, with no console window (status is shown in the systray). Logs go to server\bifrost.log. Run uninstall_startup.ps1 to remove it.

(macOS/Linux: the zip doesn't preserve the executable bit - run chmod +x server/start_bifrost.sh once after extracting.)
macOS: start_bifrost.sh is a plain launch script - it doesn't register itself anywhere. Open System Settings → General → Login Items, click +, and add server/start_bifrost.sh.
Linux: Same idea - most desktop environments have their own "Startup Applications" setting (e.g. GNOME: Settings → Apps → Startup Applications; KDE: System Settings → Autostart). Point it at server/start_bifrost.sh.

3. Copy Bifrost to Amiga:

Copy Bifrost to SYS:

4. Launch from CLI:

Bifrost [port] [edge]

Auto-discovery: Server is found via UDP broadcast on port 7891 (TCP 7890 + 1). No IP needed.

Usage

Command-Line Arguments (Amiga)

Bifrost                      # Auto-discover, default port (7890)
Bifrost 9999                 # Custom TCP port (PC must also use 9999)
Bifrost 9999 TOPRIGHT        # + Edge trigger (top-right corner)
Bifrost STATUS                # Query the running daemon's connection status
Bifrost STOP                  # Disconnect and quit the running daemon

Edge Options: TOP, BOTTOM, LEFT, RIGHT, TOPLEFT, TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT

STATUS / STOP: Talk to the already-running daemon over a public message port (Bifrost_Port) instead of launching a new one - useful for scripts. Running Bifrost again while an instance is already active is refused (use STOP first, or STATUS to check).

⚠️ Port Limitation: If you change the port on PC, you must also specify it on Amiga CLI. The UDP discovery protocol doesn't currently transmit the TCP port — it's assumed to be UDP port - 1. This will be fixed in Phase 2 (auto-negotiation).

Configuration (PC)

Edit server/bifrost_config.json:

{
  "network": {
    "port": 7890
  },
  "mouse": {
    "hz": 50,
    "hz_drag": 15,
    "speed": 1,
    "delta_max": 80
  },
  "curve": {
    "linear": 2.0,
    "ratio": 0.5
  },
  "keys": {
    "toggle": "scroll_lock",
    "emergency": "pause"
  },
  "debug": {
    "enabled": true
  }
}

For detailed parameter explanations, profiles, and troubleshooting: See docs/CONFIGURATION.md

Toggle Focus (PC ↔ Amiga)

Scroll Lock key - Toggle between PC and Amiga input
Screen corner - Top-right click also triggers toggle (if enabled via edge config)

Systray Status Icon (PC)

When the server runs, a systray icon shows the Amiga connection state:

🟢 Green circle - Amiga is connected and ready to receive input
⚫ Grey circle - Amiga is disconnected (waiting for Amiga to connect)

The systray menu displays:

Current connection status: "Amiga Connected" or "Amiga Disconnected"
Quit button to exit the server gracefully

Updates every 0.5 seconds to reflect connection state changes in real-time.

Note: Systray support requires pystray (installed via pip install -r requirements.txt). If not installed, the server runs normally without systray.

Known Limitations

Ctrl+Alt+Del cannot be captured. While in Amiga focus mode, pressing Ctrl+Alt+Del on the PC keyboard still brings up Windows' secure screen (lock/task manager/sign out). This is Windows' Secure Attention Sequence (SAS): it is intercepted by the OS below any user-mode hook (including the WH_KEYBOARD_LL hook the PC server uses) specifically so that no application - malicious or not - can intercept credential entry. There is no supported way to suppress it from a user-mode process; only a signed kernel-mode keyboard filter driver could, which is out of scope for Bifrost's current architecture.

Architecture

PC Side (Server)

Python daemon captures mouse/keyboard
Applies acceleration curve
Sends 8-byte packets via TCP/IP (50 Hz default)

Amiga Side (Client)

Receives packets over TCP
Injects into input.device stream
Supports edge-triggered focus switching

Technical Details

Network Protocol

Discovery: UDP broadcast (port 7891 default)
- PC broadcasts Bifrost_DISCOVER
- Amiga replies Bifrost_HERE and connects via TCP
- No pre-configured IP needed
Data: TCP/IP with TCP_NODELAY enabled
- Fixed 8-byte packets with big-endian encoding
- Packet types: PKT_MOUSE_MOVE, PKT_MOUSE_BTN, PKT_KEY, PKT_WHEEL, PKT_HELLO, PKT_EDGE_TRIGGER, PKT_FOCUS_ENTER, PKT_CLIENT_STATE, PKT_HEARTBEAT
- Default send rate: 50 Hz (~20ms per event)

Mouse Acceleration (Piecewise-Linear)

|d| ≤ CURVE_LINEAR  →  output = |d|       (1:1 precision)
|d| >  CURVE_LINEAR  →  output = CL + (|d|-CL) × CURVE_RATIO

Example (default: linear=2.0, ratio=0.5):

1px → 1px, 2px → 2px, 3px → 2.5px, 4px → 3px, 10px → 6px

Why MOUSE_HZ_DRAG?

Only relevant for apps using opaque drag (MCP — Move/Copy/Paste window).

If an app uses opaque drag (Workbench, file managers), each mouse event forces a full-screen redraw. Lower send rate during drag prevents overwhelming the Amiga.

If an app uses transparent drag or no drag visual, set hz_drag = hz — no lag, no benefit to lowering.

Testing & Validation

All tests on:

Apollo Computer Vampire V4 (A6000, 68080 SAGA)
A1200 Pistorm
UAE A1200
Configuration: 50 Hz polling, CURVE_LINEAR=2.0, CURVE_RATIO=0.5

Validated:

✅ Smooth mouse movement with sub-pixel accumulation
✅ Keyboard input forwarding
✅ Edge-triggered focus switching
✅ Low-latency auto-discovery
✅ Acceleration curve responsiveness

Note: Other Vampire versions or non-accelerated Amigas may need parameter adjustments. See docs/CONFIGURATION.md for hardware-specific profiles.

Building from Source

# Build for 68020+ (SAGA-compatible)
make CPU=68020 build

# Release build
make MODE=release build

# Clean
make clean

# Upload to Vampire V4
make upload

Version History

v0.5.0

✅ Mouse-tuning config (HZ/HZDRAG/SPEED/DELTAMAX/CURVELINEAR/CURVERATIO) moved from PC config file to Amiga-side CLI args
✅ Live config push to an already-running daemon (edge + mouse-tuning) via a second Bifrost invocation
✅ Fixed several CLI live-update merge bugs

v0.4.3

✅ PKT_HEARTBEAT replaces PKT_PING - liveness independent of packet backlog, carries Amiga cursor position
✅ PC Capslock state sync to Amiga, NOCAPSLOCK CLI toggle
✅ Fixed Left/Right Amiga key qualifiers to track per-side state instead of always setting both
✅ Improved logging and connection status reporting

v0.4.1

✅ Refactor source codes
✅ split the commodity part to another project
Many other things to release the

first fonctionnal Beta release

v0.4

✅ Introduce commodity

v0.3

✅ Piecewise-linear acceleration curve
✅ Sub-pixel float accumulation
✅ TCP_NODELAY for low-latency delivery
✅ Edge detection and boundary handling
✅ UDP auto-discovery
✅ JSON configuration file

v0.2

✅ Smooth mouse movement
✅ Keyboard forwarding
✅ Toggle switching

v0.1

✅ Initial client-server architecture
✅ TCP/IP mouse forwarding
✅ Basic acceleration curve

Documentation

Document	Purpose
ROADMAP.md	Development roadmap (Phases 2-6)
docs/CONFIGURATION.md	Full configuration guide — parameter details, profiles, troubleshooting
MILESTONES.txt	Release history and validation points

License

See LICENSE file for details.

Status: Ready for production.

Next: Per-app profiles, Amiga→PC reverse control, GUI preferences editor — see ROADMAP.md

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.setup		.setup
assets		assets
docs		docs
scripts		scripts
server		server
src		src
.env.ps1		.env.ps1
.gitignore		.gitignore
Bifrost.guide		Bifrost.guide
Bifrost.readme		Bifrost.readme
CHANGELOG.md		CHANGELOG.md
Install		Install
LICENSE		LICENSE
MILESTONES.txt		MILESTONES.txt
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
setup.config.psd1		setup.config.psd1

Folders and files

Latest commit

History

Repository files navigation