What the Desktop Service Bridge Does

RailScanPro is a cloud-first web application. That means your inventory, operations sessions, and layout configuration all live in the cloud and sync to every device you own. But DCC hardware (command stations, LocoNet devices, block detectors) plugs into a USB or serial port on a physical machine in your train room. Web browsers cannot open USB or serial connections directly, so there is a gap between the web interface and your hardware.

The Desktop Service Bridge closes that gap. It runs as a background service (a Windows Service, macOS LaunchAgent, or Linux systemd unit) on the computer next to your layout. It holds a persistent encrypted connection to the RailScanPro cloud over standard HTTPS/WebSocket, and a direct connection to your JMRI installation or native hardware drivers on localhost. Commands flow from the cloud to your hardware; events and sensor feedback flow the other way.

Architecture at a glance

Browser / Mobile → (HTTPS) RailScanPro Cloud

→ (encrypted WebSocket) Desktop Service

→ (localhost) JMRI / Native Drivers

→ (USB / LocoNet / XpressNet) Command Station

Only the Desktop Service makes outbound connections, one to the cloud, one to localhost. Nothing on the internet can reach your hardware directly. You do not need to open firewall ports, configure NAT rules, or set up a VPN. If your layout PC can browse the web, the Desktop Service will work.

Installation

Download the Desktop Service installer for your operating system from the Downloads page. The installer bundles the .NET 10 runtime, so you do not need to install any additional software on the host machine.

Windows 10 / 11

1. Run RailScanPro-DesktopService-Setup.exe. Windows may show a SmartScreen prompt, click More info then Run anyway. The installer is digitally signed with an Authenticode certificate.
2. Choose an install path (default: C:\Program Files\RailScanPro\DesktopService) and click Install.
3. The installer registers a Windows Service named RailScanProDesktopService and sets it to start automatically. The service starts immediately after installation completes.
4. A system-tray icon appears in the notification area. Right-click it to view connection status, open the local dashboard, or access the pairing code.

macOS 12+ (Apple Silicon)

1. Open RailScanPro-DesktopService.pkg. macOS Gatekeeper will verify the package signature. If a quarantine warning appears, right-click the file and choose Open.
2. Follow the installer wizard. The package installs to /Applications/RailScanPro and installs a LaunchAgent at ~/Library/LaunchAgents/com.railscanpro.desktopservice.plist.
3. The LaunchAgent starts on login. A menu-bar icon appears in the top-right corner of the screen once the service is running.
4. If your DCC command station connects via USB serial, you may need to grant the Terminal or RailScanPro app access to USB accessories in System Settings → Privacy & Security → Accessories.

Linux (Ubuntu 22.04+ / Fedora 38+, x64)

1. Extract the archive: tar -xzf RailScanPro-DesktopService-linux-x64.tar.gz
2. Run the included install script as root: sudo ./install.sh. The script copies the binary to /opt/railscanpro/desktop-service and installs a systemd unit.
3. Enable and start the service: sudo systemctl enable --now railscanpro-desktop
4. If your command station connects over USB serial, add your user to the dialout group: sudo usermod -aG dialout $USER. Log out and back in for the group to take effect.

Pairing Flow

After installation, the Desktop Service knows how to connect to the RailScanPro cloud, but it does not yet know which account or organisation it belongs to. Pairing associates the service with your organisation in a single step. You only need to do this once per machine.

1

Open the Desktop Service local dashboard

On Windows and macOS, right-click the system tray / menu-bar icon and choose Open Dashboard. This opens a local web page at http://localhost:5555. On Linux, navigate to that address directly in a browser on the same machine.
2

Locate the pairing code

The local dashboard displays a pairing code in the format XXXX-1234. This code is valid for 15 minutes. If it expires before you complete the next step, click Generate new code.
3

Enter the code in your account settings

In RailScanPro, navigate to Settings → Desktop Services → Authorize. Paste or type the pairing code and click Authorize. The web app sends a signed token back to the Desktop Service via the cloud.
4

Confirm the connection

The Desktop Service status changes to Connected in the local dashboard and in your account settings. The machine name (e.g., "Layout Room PC") appears in your Desktop Services list with a green status dot.
5

Connect your hardware

If you are using JMRI, start JMRI and enable the JSON WebSocket server (Preferences → Web Server, port 12080). The Desktop Service will detect JMRI automatically and report its connection status. For native DCC-EX or NCE USB connections, the service detects the connected command station and displays it in the hardware list.

One pairing per machine: Once paired, the Desktop Service maintains its connection automatically, including across reboots, JMRI restarts, and temporary internet outages. You do not need to re-pair unless you uninstall the service or revoke it from your account settings.

What the Desktop Service Enables

Local hardware integration

Turnouts, signals, block detectors, and throttles controlled from the RailScanPro web UI or mobile app respond in real time. Commands reach hardware in under 100 ms on a typical home network. Hardware feedback (block occupancy, turnout confirmation, sensor triggers) flows back to the cloud and updates every connected client simultaneously.

Offline / air-gapped mode

When internet connectivity is unavailable, the Desktop Service switches to air-gapped mode automatically. Your last synced layout data (track plan, roster, operating sessions) is available locally. Hardware control continues uninterrupted. When connectivity restores, the service synchronises any changes made during the offline period.

USB DCC command station support

The native driver stack supports DCC-EX (over USB serial), Digitrax LocoNet (via PR3/PR4 USB), NCE (USB and serial), and ESU ECoS (Ethernet). JMRI's JSON WebSocket interface provides a compatibility layer for any of the 100+ JMRI-supported command stations not covered by native drivers.

Multi-protocol native drivers

Native drivers are faster and more feature-complete than JMRI mediation. DCC-EX native gives direct access to the EX-RAIL automation engine; Digitrax native exposes LocoNet slots and switch feedback reports; NCE native supports consist programming and macro recall. Protocol selection is automatic based on the detected hardware.

Security Model

The Desktop Service is designed to be safe to run on a home network without any firewall changes. Here is exactly what it does and does not do:

LAN-only by default

The local dashboard at localhost:5555 binds to the loopback interface only. It is not accessible from other machines on your network, and is never exposed to the internet.

Encrypted pairing, one-time code

Pairing codes are single-use and expire after 15 minutes. The signed token returned by the cloud is stored encrypted on disk using the operating system's credential manager (Windows DPAPI, macOS Keychain, Linux Secret Service). It is never written in plaintext.

No inbound ports required

The Desktop Service makes one outbound HTTPS/WebSocket connection to the RailScanPro cloud endpoint. Your router's NAT is not modified, and no ports are opened. If your PC can reach app.railscanpro.com over port 443, the service will work.

Organisation-scoped access

The service token is scoped to a single organisation. Commands from the cloud that target a different organisation are rejected at the service level before reaching hardware. Members of your organisation can control your hardware only if you have granted them operator access in your account settings.

All commands are audited

Every hardware command that passes through the Desktop Service is logged to the cloud audit log with the authenticated user ID, timestamp, and command content. Logs are retained for 90 days and available in your account settings under Activity.

Troubleshooting

Firewall blocking the outbound connection

Windows Defender Firewall or a third-party security suite may block the Desktop Service from making outbound WebSocket connections on port 443.

Fix: In Windows Defender Firewall, add an outbound rule allowing RailScanPro.DesktopService.exe on TCP port 443. On most home routers and firewalls, outbound port 443 is already permitted and this step is not needed.

To verify: open the local dashboard at localhost:5555. If it shows Cloud: Connecting… for more than 30 seconds, the outbound connection is being blocked.

Pairing code expired before I could enter it

Pairing codes expire after 15 minutes for security. If you see Code expired in the account settings page or the local dashboard:

Open the local dashboard at localhost:5555, click Generate new code, and return to Settings → Desktop Services → Authorize in a second browser tab or window to complete pairing without navigating away.

Machine shows as Offline in account settings

The cloud marks a Desktop Service as offline if it has not received a heartbeat in the last 60 seconds. This means the service process has stopped, the machine is asleep, or the internet connection was interrupted.

Fix: Check that the service is running. On Windows, open Task Manager → Services and look for RailScanProDesktopService in the Running state. On macOS, check Activity Monitor for RailScanPro.DesktopService. On Linux, run systemctl status railscanpro-desktop.

If the service is running but still shows offline, check that the machine can reach the internet and that the local dashboard shows Cloud: Connected.

Hardware not detected after pairing

The Desktop Service scans for connected hardware after pairing completes. If no hardware appears in the hardware list on the local dashboard:

For JMRI: confirm JMRI is running and the JSON WebSocket server is enabled at port 12080. Open http://localhost:12080/json/ in a browser, you should see a JSON response. If the page does not load, the JMRI JSON server is not running.
For USB devices: confirm the command station is powered on and the USB cable is connected before starting the Desktop Service. Some command stations require a driver installation on the host PC (check the manufacturer documentation).
On Linux: confirm your user is in the dialout group and that you have logged out and back in since making that change.

Service fails to start after a Windows Update

Occasionally a Windows Update modifies the service user account permissions, preventing the service from starting. The Windows Event Viewer will show an error under Windows Logs → Application from source RailScanProDesktopService.

Fix: Open Services (run services.msc), right-click RailScanProDesktopService, choose Properties → Log On, and ensure the account is set to Local System. Click Start to restart the service. If the problem persists, reinstalling the Desktop Service from the latest installer resolves most permission-related issues.

If none of the above resolves your issue, contact support and include your Desktop Service log file. On Windows it is at %PROGRAMDATA%\RailScanPro\DesktopService\logs\service.log; on macOS at ~/Library/Logs/RailScanPro/DesktopService/service.log; on Linux at journalctl -u railscanpro-desktop -n 200.

Desktop Service Bridge