Skip to content

PX Emulator 2026.28.0

Choose a tag to compare

View all tags
@mam-pascal mam-pascal released this 10 Jul 15:35
v2026.28.0
0674cb3

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-NetFirewallRule -DisplayName "PX Emulator" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

Configuration not persisting

Problem: Changes disappear after restart.

Check:

# Verify setup file exists and is writable
ls -l device_setup.bin

# Check emulator logs for save errors
./px-emulator --http-port 8080 2>&1 | grep -i "save\|setup"

Solution: Ensure write permissions in current directory:

chmod u+w device_setup.bin

WebSocket connection fails

Problem: japi_cli reports Connection refused or timeout.

Debug steps:

  1. Verify emulator is running: ps aux | grep px-emulator
  2. Check port is listening: netstat -an | grep 8080 (or lsof -i :8080 on macOS/Linux)
  3. Test with curl: 
    curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: test" \
  http://localhost:8080/ws
    Expected: 101 Switching Protocols

Differences from Physical Devices

Feature Physical Device Emulator
WebSocket API Full support Full support
Configuration storage /data/device_setup.bin ./device_setup.bin
Default port 80 8080 (recommended)
mDNS discovery Yes (_px._sub._pasconnect._tcp; AES70 on _ocaws._tcp/_oca._tcp) Yes (same responder; japi_cli device discover)
DSP processing Real SHARC DSP Mock (no audio)
Meters Real signal levels Fixed simulated values
Temperature sensors Real ADC readings Fixed 45°C
Power control Real amplifier rails Simulated state
Firmware updates RAUC system Not supported
Secure boot TPM-based Not supported
Network interfaces eth0, wlan0 Host system passthrough

Integration with CI/CD

GitHub Actions Example

name: Test Client

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Download PX Emulator
        run: |
          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/
          chmod +x px-emulator
      
      - name: Start Emulator
        run: |
          ./px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu/px-emulator --http-port 8080 &
          sleep 2
          
      - name: Run Tests
        run: |
          # Your client tests here
          npm test

Docker Container

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y wget ca-certificates

WORKDIR /app
RUN 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 && \
    chmod +x px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu/px-emulator

EXPOSE 8080

CMD ["./px-emulator-release-2026.28.0-x86_64-unknown-linux-gnu/px-emulator", "--http-port", "8080"]

Build and run:

docker build -t px-emulator .
docker run -p 8080:8080 px-emulator

Performance Characteristics

  • Memory: ~10MB RSS (virtual mode, no DSP buffers)
  • CPU: <1% idle, <5% under load (WebSocket I/O)
  • Startup time: <200ms
  • WebSocket latency: <10ms localhost, typical network latency over LAN
  • Concurrent connections: Tested up to 50 simultaneous clients

Additional Resources

  • API Documentation: See docs/01-api-reference.md in repository
  • CLI Tool Guide: See tools/japi_cli/README.md
  • JSON Schemas: See build/schemas/ directory
  • AsyncAPI Spec: See build/asyncapi-docs/px-api.yaml
  • Example Code: See examples/ directory

Support

Bug Reports: https://github.com/pascal-audio/th-firmware/issues
Questions: support@pascal-audio.com
Documentation: https://github.com/pascal-audio/th-firmware/tree/main/docs

Version

Emulator Version: Matches firmware release version
API Version: 2.0.0 (API Level 2)
Build Info: Check with ./px-emulator --version

License

Proprietary License - Emulator binaries are proprietary software.

Copyright © 2025 Pascal Audio. All rights reserved.

PERMITTED USE:

  • Development and testing of PX device integrations
  • CI/CD and automated testing environments
  • Training and learning the PX Control API

RESTRICTIONS:

  • NO redistribution of emulator binaries
  • NO reverse engineering, decompilation, or disassembly
  • NO commercial redistribution or resale
  • Testing use only - not for production deployment as device replacement

Note: API documentation, schemas, CLI tool, and examples are MIT licensed.
See LICENSE file in repository root for complete terms.

Assets 5
Loading