openphast

An open-source bridge from Panja/AMX PHAST home-automation hardware to Home Assistant — keep a 1990s Landmark-era installation alive on modern software, no Windows and no original Landmark controller required.

Status: work in progress. The daemon and HA component are functional against real hardware (MLC dimmers, IMS/DMS keypads, RL8 relays, AS16 audio switchers, IN7 contact inputs, Apex Destiny 6100 security panels, and more), but APIs, entity naming, and the project-overlay format are still settling.

What it does

Panja PHAST is a proprietary binary protocol carried over IPX/Ethernet, used by an MCU to manage keypads, relay modules, dimmers, audio switchers, amplifiers, IR transmitters, and security panels. This project provides:

• src/ — a Linux C++20 daemon (panja-bridge) that speaks PHAST natively using AF_PACKET raw sockets (IPX framing built by hand — no AF_IPX kernel dependency), decodes device state, and serves it over a local TCP socket (default port 4196).
• ha_component/ — a Home Assistant custom component (panja_bridge) that connects to the daemon and exposes every device as native HA entities (light, switch, event, media_player, binary_sensor, cover, alarm_control_panel, text, button, …). HA's HomeKit Bridge then gets you iOS control for free.
• sim/ + Docker — a device simulator so the whole stack runs offline with no Panja hardware on the wire.
• tools/ — Landmark project-file parsers that extract device names, rooms, keypad button maps, and lighting-scene macros from original Landmark .ppj/.ppd project files, and convert them into HA device caches and automations.

Panja hardware ⇄ IPX/Ethernet ⇄ panja-bridge (C++20 daemon) ⇄ TCP ⇄ HA custom component ⇄ HomeKit/iOS

Site data stays out of the repo (project overlays)

Everything installation-specific — device names, rooms, security-zone maps, automation scopes — lives in a separate project overlay directory, typically a private repo cloned under the gitignored projects/ folder:

git clone <your-private-project-repo> projects/myhome
export PANJA_PROJECT_DIR=$PWD/projects/myhome   # optional if only one project is cloned

An overlay can provide any of:

File	Consumed by	Contents
device_cache.json	HA component	device names, areas, contacts/zones/channels
apex_zones.json	binary_sensor	security-panel zone map {"3": ["HallMotion", "motion"]}
rooms.json	tools/parse_landmark.py	site room and keypad-button lexicons
areas.json	tools/merge_device_cache.py	device-name-prefix → HA area table
automation_config.json	tools/generate_automations.py	room light scopes, audio entities

Without an overlay, everything falls back to a bundled fictional example installation (ha_component/panja_bridge/example_device_cache.json), which is also what the test suite runs against.

Deployment settings are environment variables: PANJA_DEPLOY_HOST / PANJA_DEPLOY_USER (tools/deploy.py), PANJA_IFACE / PANJA_MAC / SIM_CONFIG (docker-compose).

Build and test

# C++ daemon (Linux; requires CAP_NET_RAW at runtime)
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
cd build && ctest --output-on-failure

# HA component tests
cd ha_component && python3 -m pytest

# Full offline simulation (daemon + simulator, no hardware)
docker-compose --profile sim up --build

The HA component deploys by copying ha_component/panja_bridge/ to config/custom_components/panja_bridge/ in your Home Assistant instance.

Documentation

• docs/architecture/ — system architecture, ADRs, and an in-depth PHAST protocol analysis (driver-analysis.md)
• docs/panja/ — reverse-engineered protocol notes per device type
• docs/architecture/landmark-file-format.md — Landmark .ppj/.ppd binary format findings

Hardware support

Device	Type	HA entity
MLC multi-level controller (dimmer)	35	light
IMS / DMS keypads	3 / 20	event (+ text for DMS display)
RL8 / RL6 relay modules	5 / 27	switch (garage doors: cover)
AS16 / AS8 audio switchers	2 / 23	media_player
IN7 contact inputs	6	binary_sensor
SB1 / SB2 scene buttons	16 / 17	button
Apex Destiny 6100 security panel	122	binary_sensor + alarm_control_panel
IROUT / TCC IR transmitters	8 / 24	remote (in progress)

Acknowledgements

Protocol understanding builds on packet captures from live hardware and on George Shaw's Premise SYS driver as a reference implementation of PHAST.