PX Emulator 2026.28.0

PX Amplifier Virtual Device Emulator

Virtual device emulator for PX professional audio amplifiers. Enables API integration testing and development without requiring physical hardware.

Overview

The emulator provides a software-only implementation of the PX Control API v2.0.0, running the same firmware code as production devices but with mock hardware abstraction layer (HAL). It responds to all JSON-RPC API commands and maintains configuration state, making it ideal for:

• Integration testing - Validate client applications against the API
• Development - Build control interfaces without hardware access
• Training - Learn API workflows and commands
• CI/CD - Automated testing in pipelines

Limitations: No real DSP processing, no audio I/O, simulated meters and status values.

Platform Support

Platform	Architecture	Binary	Tested OS
macOS	ARM64 (Apple Silicon)	px-emulator-release-2026.28.0-aarch64-apple-darwin.tar.gz	macOS 12+ (Monterey)
Windows	x86_64	px-emulator-release-2026.28.0-x86_64-pc-windows-gnu.tar.gz	Windows 10/11
Linux	x86_64	px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu.tar.gz	Ubuntu 20.04+, Debian 11+

System Requirements:

• macOS: 10.15+ (Catalina or later), 50MB disk space
• Windows: Windows 10 (1809+) or 11, Visual C++ Redistributable, 50MB disk space
• Linux: glibc 2.31+, 50MB disk space

Quick Start

1. Download and Extract

Download the appropriate binary for your platform from the GitHub release:

Note: Replace x with the patch number of the published 2026.28 release.

# macOS ARM64
wget https://github.com/pascal-audio/px-api/releases/download/v2026.28.0/px-emulator-release-2026.28.0-aarch64-apple-darwin.tar.gz
tar -xzf px-emulator-release-2026.28.0-aarch64-apple-darwin.tar.gz
cd px-emulator-release-2026.28.0-aarch64-apple-darwin/

# Linux x86_64
wget https://github.com/pascal-audio/px-api/releases/download/v2026.28.0/px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu.tar.gz
tar -xzf px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu.tar.gz
cd px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu/

# Windows (PowerShell)
# Download from releases page, extract ZIP, navigate to folder

2. Run the Emulator

macOS/Linux:

./px-emulator --http-port 8080

Windows (PowerShell):

.\px-emulator.exe --http-port 8080

Output:

[INFO] Starting PX Control API v2.0.0 (emulator mode)
[INFO] WebSocket server listening on 0.0.0.0:8080
[INFO] Device ID: emulator-12345678
[INFO] Configuration file: ./device_setup.bin
[INFO] Ready for connections at ws://localhost:8080/ws

3. Test Connection

Using japi_cli (Python CLI tool):

# Install CLI (requires Python 3.12+) from the px-api clone (package: japi-cli)
cd tools/japi_cli
uv pip install -e .

# Test connection
japi_cli -t localhost -p 8080 api ping
# Expected output: "pong"

# Get device information
japi_cli -t localhost -p 8080 status get info

Using wscat (Node.js WebSocket CLI):

npm install -g wscat
wscat -c ws://localhost:8080/ws

# Send JSON-RPC request:
{"jsonrpc":"2.0","method":"api_ping","params":{},"id":1}

# Expected response:
{"jsonrpc":"2.0","result":"pong","id":1}

Command Line Options

px-emulator [OPTIONS]

OPTIONS:
    -p, --http-port <PORT>     HTTP listener port  [default: 8080 emulator, 80 hardware]
        --no-http              Disable the HTTP listener
        --https-port <PORT>    HTTPS listener port [default: 8443 emulator, 443 hardware]
        --no-https             Disable the HTTPS listener (skip dev-cert generation)
        --aes70-port <PORT>    AES70/OCA legacy TCP port [default: 0 = disabled; pass 65000 to enable]
        --config <FILE>        Config file path [default: ./config.json]
    -h, --help                 Print help
    -V, --version              Print version

At least one of HTTP / HTTPS must remain enabled; the two listener ports must differ.
JAPI `/ws`, AES70 `/oca`, and (with the admin SPA) `/admin/` are all served on whichever listener is active.

Examples

Custom port:

./px-emulator --http-port 8090

Persistent configuration:

# First run - creates device_setup.bin in the working directory
./px-emulator --http-port 8080 --workdir ./my_config

# Make changes via API (e.g., set speaker channel 1 user-layer gain)
japi_cli -t localhost -p 8080 setup set user 1 -g -3.0

# Stop emulator (Ctrl+C)
# Restart with same config (reads device_setup.bin from the same working directory)
./px-emulator --http-port 8080 --workdir ./my_config

Default Configuration

The emulator starts with factory default configuration:

• 4 Speaker Channels (1-4)
• 4 Analog Inputs (analog/1–4)
• 4 Digital Inputs (digital/1–4)
• No network (Dante) audio channels — the emulator models a non-Dante
  PX4000.4, so /audio/input/network and /audio/output/network are empty and
  network/* sources are rejected, exactly like a physical amp without Dante. To
  emulate the Dante variant (PX4000.4D), set "hardware_id": 50003 in the
  factory_config section of the emulator's config.json — network channels 1–4
  then appear.
• Network: DHCP enabled, mDNS name: px-emulator-XXXXXX.local
• Power: Auto-on mode enabled
• Audio Processing:
  • User layer: Flat EQ (10 bands), no FIR, no crossover
  • Array layer: Disabled
  • Preset layer: Flat preset loaded

API Coverage

The emulator supports all JSON-RPC API methods documented in the API reference:

Fully Functional

• ✅ API Domain - api_ping, api_version
• ✅ Device Domain - device_reboot, device_get_time/device_set_time, logs_get (device information via status_get/status_get_all)
• ✅ Setup Domain - setup_get, setup_set, setup_get_all
• ✅ Preset Domain - preset_apply, preset_create, preset_show, preset_clear
• ✅ Subscriptions - setup_update, metrics_update notifications

Simulated (Mock Data)

• 🔶 Status Domain - status_get returns simulated values:
  • Meters: Fixed -20dBFS input/output levels
  • Temperature: Fixed 45°C
  • Network: Mock IP addresses
  • Protection: Always OK (no thermal/overcurrent)
• 🔶 Power Control - Commands accepted but no real power state changes
• 🔶 DSP Operations - Parameters stored but no audio processing

Not Available

• ❌ Hardware diagnostics (real voltages, real temperatures)
• ❌ Firmware updates (use real device)
• ❌ TPM operations (secure boot, attestation)

Configuration Persistence

The emulator saves setup changes to device_setup.bin in the working directory (set the directory with --workdir <DIR>; the file is always named device_setup.bin within it):

• Format: CBOR binary with CRC32 validation
• Auto-save: 5-second debounce after changes
• Size: ~20KB typical
• Location: Current working directory (or specified path)

Backup/restore:

# Backup current config
cp device_setup.bin config_backup_$(date +%Y%m%d).bin

# Restore config
cp config_backup_20250117.bin device_setup.bin
./px-emulator --http-port 8080

Reset to factory defaults:

# Delete setup file
rm device_setup.bin

# Restart emulator (will create fresh config)
./px-emulator --http-port 8080

Example Workflows

1. Test Speaker EQ Configuration

# Start emulator
./px-emulator --http-port 8080

# In another terminal:
# Set user EQ band 3 on channel 1
japi_cli -t localhost -p 8080 setup set user-eq-band 1 3 \
  -k parametric -f 1000 -g 3.0 -q 1.41

# Read back configuration
japi_cli -t localhost -p 8080 setup get user-eq-band 1 3

2. Load Channel Preset

# Apply factory preset
japi_cli -t localhost -p 8080 preset apply 1 -f presets/M1206_LF.pxp

# Verify preset loaded
japi_cli -t localhost -p 8080 preset show 1

3. Batch Configuration

# Export current config to JSON
japi_cli -t localhost -p 8080 setup batch create -f device_config.json

# Edit JSON file (e.g., change network settings)
nano device_config.json

# Apply modified config
japi_cli -t localhost -p 8080 setup batch apply -f device_config.json

4. Real-time Monitoring

# Subscribe to setup changes
japi_cli -t localhost -p 8080 setup subscribe

# In another terminal, make changes (mute is on the user layer)
japi_cli -t localhost -p 8080 setup set user 1 -m true

# First terminal shows notification:
# {"jsonrpc":"2.0","method":"setup_update","params":{"path":"/audio/output/speaker/1/user/mute","value":true}}

Troubleshooting

Emulator won't start

Error: Address already in use

[ERROR] Failed to bind to 0.0.0.0:8080: address already in use

Solution: Port 8080 is occupied. Use different port:

./px-emulator --http-port 8090

Error: Permission denied (macOS)

"px-emulator" cannot be opened because the developer cannot be verified

Solution: Allow in System Settings:

# Remove quarantine attribute
xattr -d com.apple.quarantine px-emulator

# Or via System Settings > Privacy & Security > Allow

Error: Permission denied (Linux, port 80)

[ERROR] Permission denied (os error 13)

Solution: Use non-privileged port (>1024) or run with sudo:

./px-emulator --http-port 8080  # No sudo needed

Cannot connect from remote machine

Problem: Connection works from localhost but not from other machines on network.

Solution: Emulator binds to 0.0.0.0 (all interfaces), but firewall may block:

macOS:

# Allow incoming connections
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add px-emulator
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp px-emulator

Linux (ufw):

sudo ufw allow 8080/tcp

Windows (PowerShell, run as Administrator):

New-...

PX API v2.0.0

🖥️ Emulator downloads: the PX emulator binaries for this API version (Linux / Windows / macOS) are attached to the PX Emulator 2026.28.0 release.

Changelog

For detailed API status and roadmap, see docs/README.md

v2.0.0 (juli 2026)

Release of PX JSON-RPC API (JAPI) for third-party integration.

API Status

API Status & Roadmap

📋 Version History

v2.0.0 (June 2026) - Firmware 2026.24.0 — Breaking

• metrics_update notification paths dropped the /metrics prefix. Metric blocks are now published at topic-relative paths — /vu, /clip, /gain_reduction, /temperatures, /fan, /system, /impedance, /current_rms — matching the status_update convention (/state, /audio, /firmware, /network/lan1, /network/lan2, /gpio), which was never prefixed. Earlier firmware emitted /metrics/vu, /metrics/temperatures, … (a known defect). Clients that subscribe to the whole metrics topic (no path filter) and dispatch on params.path must update their path checks; clients that pass a path filter to metrics_subscribe must use the block-relative path (/vu, not /metrics/vu). See metrics_subscribe in 01-api-reference.md.
• device_find_me is now a latched on/off toggle: it takes identifying (boolean) instead of timeout (number), and its response returns identifying instead of timeout/status. Identification stays on until turned off (or until reboot / factory reset / restore) — there is no longer a timed countdown.
• find_me_timeout_seconds removed from the device status (/state). Use find_me_active to read the latched identify state.

v1.4.0 (May 2026) - Firmware 2026.22.0

• storage.user_data in setup_get_all / setup_update now carries last_modified (RFC 3339 timestamp, or null if never written) instead of sha256. The sha256 field is still returned by storage_get for integrity checking.

v1.3.0 (May 2026) - Firmware 2026.22.0 (first shipped together with v1.4.0)

• last_power_state removed from the /power read response and setup_set patch — the field was device-internal bookkeeping excluded from schemas and documentation

v1.2.0 (January 2026) - Firmware 2026.4.0

• HTTPS support - Secure WebSocket (WSS) connections with automatic fallback to HTTP
• metrics_get / metrics_get_all - Poll metrics without subscription
• Display configuration (dimming) in setup API
• TPM object locking support
• SoM bootloader version in firmware info
• Screenshot commands moved to diagnostics group

v1.1.0 (December 2025) - Firmware 2025.50.1

• device_get_time - RTC time endpoint
• Screenshot capture and download endpoints
• Per-path frequency throttling for metrics subscriptions
• DanteStatus moved from /network/dante to /dante
• device_standby removed (merged into device_power_off)
• setup_subscribe parameter renamed: paths → path
• set-x-eq split into set-x-eq and set-x-eq-band

v1.0.0 (November 2025) - Firmware 2025.48.1

• Initial release
• Setup API (3-layer audio processing)
• Device API (power, reboot, time sync)
• Preset API (with vendor locking)
• Metrics API (real-time VU, clipping, gain reduction)
• Status API (device state, network, firmware versions)

---

Package Contents

Documentation:

• 6 comprehensive markdown files
• Complete API reference with examples
• Configuration path reference
• Best practices guide

Tooling:

• Virtual device emulators (3 platforms, via GitHub Releases)
• Python CLI tool (japi_cli)
• TypeScript/Python client libraries
• JSON schemas for every method, notification and wire type

Audio Features:

• 3-layer processing (User → Array → Preset)
• 10-band parametric EQ per channel
• FIR filters, crossovers, limiters
• Channel preset save/recall
• Real-time metrics and notifications

v1.1.0

docs: release v1.1.0