XPPANELS

User Guide · v2

XPPanels A32X

Build live X-Plane cockpit panels on iPad. Control, monitor and automate your simulator with drag-and-drop widgets.

SwiftUI · iPadOS Live UDP / RREF Custom JSON Plugin Encrypted Backups Multi-Canvas

1

What is XPPanels?

An iOS/iPadOS app for building interactive X-Plane cockpit panels from modular widgets.

🎛️ What you build

• ✈️Overhead, pedestal, glare-shield & MCDU replica pages
• 📋Training panels with timers, guarded controls & checklists
• ⚡Macro buttons that fire command sequences on a single tap
• 🌦️Weather, pushback & teleport operation support tools
• 📡Live dataref monitors that reflect real simulator state

🔗 How it connects

• 📤Outbound: UDP packets (CMND / DREF) or custom JSON plugin
• 📥Inbound: RREF subscriptions receive live dataref values
• 🔁Two-way flow — widgets both send and display sim state
• 🌐Same host or cross-device on a LAN — flexible deployment
• 🔒AES-GCM encrypted .xppanels packages for sharing

💡

Recommended flow: connect network first → validate one read + one write mapping → then design canvases and duplicate reusable patterns.

2

Getting Started

First launch to first live button — in six steps.

1

Enter your X-Plane host IP

On first launch, the Welcome screen lets you type the IP address of the machine running X-Plane. Hit Save, then Quick Connect to verify the link instantly. You can also edit this later in Settings → Network.

2

Set UDP ports

Default ports: 49000 for sending to X-Plane and receiving RREF data. For the Custom JSON plugin transport, the bridge port 49001 is set automatically when you switch transport mode in Settings.

3

Choose transport mode

Native UDP — uses standard X-Plane CMND/DREF packets. Works out-of-the-box.
Custom JSON — requires the XPPanels bridge plugin; unlocks timed hold / command begin-release modes.

4

Verify the connection

In Settings, use Send Test Command and Send Test DREF buttons. Then add a DataRef path in the Receive Test section and hit Listen — a green dot and live value confirm two-way comms.

5

Create your first canvas tab

Tap the + button in the sidebar → name the tab (e.g. "Overhead") → pick a background color → tap Create. You now have a grid ready for devices.

6

Add devices & lock

In Unlock mode, tap the floating + button to add a device. Configure it and place it. When ready to fly, tap the 🔒 sidebar button — all canvases go live in Lock mode.

🟢 Green — receiving live RREF data

🟡 Yellow — listening, no recent packets

🔴 Red — RREF idle / not connected

3

Canvas Modes

Every canvas is always in one of two modes — edit or live.

🔓 Unlock Mode

Design Mode

Arrange, configure and resize devices. The simulator is not affected while you build.

• ➕Tap floating + to add a new device
• ✏️Long-press or select any device to edit its settings
• ↔️Drag devices around the grid to reposition
• 📋Copy/paste devices or entire canvases
• ↩️Undo any accidental changes
• 🔍Double-tap to zoom/pan the canvas
• 📤Export/import .xppanels panels
• 🎨Rename tabs and change background colors

🔒 Lock Mode

Live Mode

Devices interact with the simulator in real time. Taps send commands; monitors display live values.

• 🚀Tap buttons to fire X-Plane commands instantly
• 📡Datarefs are subscribed and values update live
• 📳Haptic feedback on every interaction
• 🔄Toggle switches prime their last state on lock
• 🌐Background tabs keep syncing (optional setting)
• ⚡Auto-throttle caps background RREF rate
• 🔁Sidebar 🔒 button toggles ALL canvases at once

⚙️

Tip: Keep canvases unlocked while laying out. Switch to lock only when you're ready to fly. The sidebar lock button toggles every tab simultaneously for a clean transition.

4

Floating Canvas Controls

The floating toolbar appears in the canvas when unlocked.

＋

Add Device

Opens the device picker sheet. Choose a device type, configure basic settings and confirm to place it on the grid.

📋

Copy / Paste

Select one or more devices → Copy. Switch tab → Paste to place them. Copy with nothing selected copies the whole canvas.

↩️

Undo

Reverts the last change to the current canvas. Useful when you accidentally move or delete a device.

🔍

Zoom / Pan

Double-tap to toggle zoom focus. Use two-finger pan to navigate dense panels. Zoom state is saved per canvas.

📤

Export Canvas

Exports the current canvas as an encrypted .xppanels file or compatible JSON for sharing or backup.

📥

Import

Import a .xppanels or JSON file. Devices are placed and offset into the current canvas automatically.

📡

Connection Ping

Sends a probe to X-Plane and checks live RREF traffic to validate the current network link before flying.

🖼️

Edit Tabs

Rename, reorder (drag handles) or delete canvas tabs. Also lets you change each tab's background color inline.

5

Device Reference

Every widget on a canvas is a "device". Tap + to add one from these categories.

Send-only — these send commands to X-Plane

🔘

Command Button

Send commands, datarefs, or sequences

Tap to fire a command, write a dataref value, or run a timed sequence of steps. Each step can have an individual delay (e.g. Step 1 now → Step 2 after 2 s → Step 3 after 5 s). Perfect for cockpit initialization macros.

Send-only

🔁

Toggle Switch

2–6 position multi-state switch

Map each position to a command or a specific dataref value. Works as a 2-state on/off, a 3-state OFF/AUTO/ON, or up to 6 positions. Syncs its last position on canvas lock. Can optionally monitor a dataref for true state indication.

Send-only

🚀

Teleport Button

Instantly reposition the aircraft

Saves a local position (lat/lon/alt, heading/pitch/bank, speed) and writes it to X-Plane position datarefs on tap. Useful for quick scenario setups — runway threshold, final approach, etc.

Send-only

Receive-only — these display simulator data

📊

DataRef Monitor

Live single dataref readout

Subscribes to one RREF at a chosen frequency (Hz) and renders the value with optional threshold coloring. Supports float and int datarefs. Great for parking brake state, fuel quantity, altitude, etc.

Receive-only

📈

Computed Monitor

Multi-dataref expression display

Reads multiple datarefs and evaluates a user-defined expression (e.g. value1 + value2 + value3) to display a derived value. Powered by JavaScriptCore — expression correctness is user responsibility.

Receive-only

🏷️

Text Label

Static text or live dataref value

Displays a configurable static string, or subscribes to a float/int dataref and renders its value. Useful for panel section headers, live wind speed, or any numeric readout. Supports multiple font sizes.

Receive-only

📐

Lines & Arrows

Visual dividers and markers

Purely visual decoration — draw fuel-flow lines, section dividers, arrows between controls. No command or dataref behavior. Used to group and organize complex panels visually.

Visual only

Hybrid — send commands AND monitor state

🔲

Push Monitored

Button with live state face

Sends a command on tap and monitors a dataref to change its face color/label (e.g. turns green when the bleed valve is open). Requires a reliable monitor dataref for accurate visual state.

Hybrid

🔳

Large Push Monitored

Bigger footprint, same behavior

Identical logic to Push Monitored but with a larger face area for prominent controls — e.g. guarded-style light/valve indicators. Consumes more grid cells.

Hybrid

🎛️

Rotating Knob

Drag/tap to increment a dataref

Drag or tap ±1 to increment/decrement a dataref value. Set min/max bounds and step size. Optionally reads back the current sim value to stay in sync — great for heading bug, altitude selector, speed, etc.

Hybrid

🎚️

Dial Slider

Analog range control

A vertical or horizontal slider that maps its range to a dataref's numeric range. Ideal for cabin lights, trim, flap-style controls. Detents are UI-only — aircraft physics may differ.

Hybrid

⚙️

Trim Wheel

Scrollable trim control

Simulates a trim wheel scroll gesture that writes pitch/roll/yaw trim datarefs. Monitors trim position for visual feedback and supports fine-grained step control.

Hybrid

🛡️

Guard Cover

Safety cover visual layer

A visual safety cover overlay that reads a dataref to show open/closed state. Primarily decorative — place it over an engine fire button or other guarded control to replicate the real panel look.

Hybrid

Special — composite operational tools

🚌

Pushback Controller

Automated ground pushback

Configure distance, turn angle, radius and speed. Arms the pushback sequence — when brakes/chocks conditions are met it drives control datarefs kinematically. Works with compatible aircraft ground physics.

Special

🌦️

Weather Control Pad

XP12 regional weather editor

Set wind (dir/speed), cloud cover, ceiling/tops, visibility, RVR, precipitation, temp, QNH and runway condition. Writes XP12 regional weather datarefs on APPLY. Auto-apply and cloud regeneration options available.

Special

⏱️

Timer

HH:MM:SS local session timer

A standalone tap-to-start/stop/reset timer displayed on the panel. Not linked to the sim clock. Useful for checklist timing, hold timing or procedure elapsed tracking.

Special

🖥️

WebFMC MCDU

Embedded FMC browser

Embeds the WebFMC plugin's web interface for Left or Right MCDU directly inside XPPanels. Requires the WebFMC plugin running and reachable. Enter the host IP and port (default :9090).

Special

🎹

ToLiss MCDU Recorder

Full key matrix + macro recording

Renders the full ToLiss MCDU key matrix, sending AirbusFBW commands on each key press. Record a key sequence and generate a timed macro button automatically. Specific to ToLiss A320-family aircraft.

Special

6

Data Flow

Understand how data travels between your panel and X-Plane.

📤 Outbound (Sending)

User Gesture

→

UDPClient

→

X-Plane

• CMND — fires a named command (e.g. sim/autopilot/autothrottle_toggle)
• DREF — writes a float value to a named dataref directly
• Sequence — steps executed with configurable delays
• Custom JSON — plugin transport for hold/begin/release modes

📥 Inbound (Receiving)

X-Plane RREF

→

RREFClient

→

Device UI

• Devices subscribe to a dataref path at a chosen Hz rate
• X-Plane streams RREF\0 frames back over UDP
• Values are parsed as Float32, dispatched on main thread
• RREF client handles backoff/restart automatically on loss

7

Import & Export

Share, back up and migrate your panel designs.

🔒

.xppanels

Encrypted AES-GCM package. The default export format. Safe to share publicly — your simulator config stays private.

📄

JSON

Plain-text Codable payload. Useful for migration between versions or inspection. Legacy/deprecated devices are filtered on import.

📋

In-app Clipboard

Copy selected devices (or full canvas) and paste into another tab instantly — no file needed. Devices are offset automatically.

8

FlyWithLua Integration (Optional)

Extend XPPanels with Lua scripts for advanced command behaviors like timed holds.

⚙️ Setup

• Install FlyWithLua NG into X-Plane/Resources/plugins/FlyWithLua/
• Place your .lua scripts in the Scripts/ subfolder
• Reload via X-Plane → Plugins menu, or restart the simulator
• Map a Command Button in XPPanels to your custom command (e.g. xppanels/hold_brakes)

💡 Use-case: Timed Hold

When a command needs a press-and-hold behavior (begin + delay + end), use a Lua script to bridge it:

-- xpp_hold.lua local HOLD_MS = 400 local TARGET_CMD = "sim/flight_controls/brakes_toggle_max" local function start_hold() command_begin(TARGET_CMD) hold_until = os.clock() + (HOLD_MS / 1000) holding = true end create_command("xppanels/hold_brakes", "Hold target command", "start_hold()", "", "")

9

Tips & Best Practices

🧪

Validate before building: test one read dataref and one write command before adding many devices. This catches network misconfiguration early.

⚡

Manage RREF rates: high-frequency monitors on many devices increase CPU and network load. Use the minimum Hz that gives acceptable response for each device type.

🔤

Dataref path accuracy: copy paths directly from X-Plane DataRefTool or PlaneMaker. A single typo will silently fail — no error is shown.

📦

Tag stable releases: after building a known-good panel, export a .xppanels backup. Easy to roll back if you break something later.

🌐

Background tabs: enable Keep background tabs live in Settings so non-active canvases keep their RREF subscriptions active. Use auto-throttle to cap their rate.

✈️

Aircraft differences: ToLiss, FlyJSim, Zibo etc. all have different dataref and command paths. Always validate per-aircraft — a button that works on one may need reconfiguration on another.

---

⚠️ Legal & Safety Notice

• XPPanels is for simulation use only — not for real-world flight operations or safety-critical use.
• No warranty: behavior depends on network, simulator version, aircraft plugins and dataref availability.
• X-Plane, ToLiss and WebFMC are external products with independent licensing.
• Protect your network settings and panel exports when sharing publicly.

XPPanels A32X — Proudly built by AldoApps

View on the App Store