pycrestron-cip

pycrestron-cip is a typed asyncio client for CIP (Crestron-over-IP), the protocol that touch panels and XPanel use to talk to a Crestron control processor. Your code connects as a panel IP ID, sees what that panel would see (digital, analog and serial joins) and can press its buttons.

It needs nothing from the processor's program: no SIMPL changes, no extra modules. If a panel IP ID is defined, you can connect to it. That makes it a good base for Home Assistant integrations and other home automation.

Status: alpha. Tested against a Crestron 3-Series processor. The API may still change.

Not affiliated with, endorsed by or supported by Crestron Electronics, Inc. "Crestron" is a trademark of Crestron Electronics, Inc.

Features

• Pure asyncio, no runtime dependencies, fully typed (py.typed)
• Registration, update request / end-of-query sync, heartbeats in both directions
• Correct TCP framing: frames split across reads, several frames per read, several joins per sub-packet (processors pack their initial dump; older clients lose most of it)
• Liveness timeout: a silent, half-open connection is noticed and reconnected
• Automatic reconnect with backoff, and a long retry interval for an undefined IP ID
• Input caches with callbacks; latched outputs are replayed after every reconnect
• Buttons: press / release with auto-repeat, and pulse
• Serial joins in UTF-8 and UTF-16, chunked long strings, short and extended forms, smart objects
• Optional TLS (port 41796) and username/password authentication
• FakeProcessor: a CIP server for your own tests, built from real captures
• pycrestron-cip-probe: a read-only command that records everything a processor sends

Why pycrestron-cip

Most open-source CIP clients stop at "it connects". We read the source of every panel-side CIP client we could find, ran their parsers against a fake processor, and built this library to close the gaps. Then we verified it on a real processor.

¹ Seven XPanel-style CIP clients in Python, Swift, JavaScript and Node, each reviewed at its latest commit in September 2026. Projects that emulate a processor, proxy TLS on the processor, or use a different protocol are not counted. Other projects were tested against a fake processor, not real hardware.

Why it matters

• Correct state from the first second. After connecting, a processor packs several joins into one sub-packet of its initial dump. A client that reads only the first one starts with most values missing, and a paged panel may not resend them until they change. That is how a light ends up shown as off while it is on.
• Connections that heal themselves. A client that never notices a half-open socket can sit "connected" while nothing arrives. This one sends and answers heartbeats, times out when the processor goes quiet, reconnects with backoff and restores its outputs.
• Any text, any language. Room names and labels come through intact: UTF-8, UTF-16 and long chunked strings, with a safe fallback for stray bytes.
• Built to be depended on. Pure asyncio, fully typed, no runtime dependencies, so it drops into Home Assistant and other asyncio apps. FakeProcessor and pycrestron-cip-probe let you test your integration without, and then against, real hardware.

Honest limits: sending to smart objects is not supported yet; TLS and username/password authentication are implemented but not yet verified on hardware (captures welcome); the WebSocket/CH5 transport used by some 4-Series web panels is not covered.

Requirements

• Python 3.13 or newer
• A Crestron processor reachable on TCP 41794 (or 41796 for TLS)
• A panel IP ID defined in the processor's program that nothing else is using (see below)

Installation

pip install pycrestron-cip

For local development:

git clone https://github.com/Antonio112009/pycrestron-cip.git
cd pycrestron-cip
pip install -e ".[dev]"

Quick Start

import asyncio

from pycrestron_cip import CipClient, JoinUpdate


def on_join(update: JoinUpdate) -> None:
    print(f"{update.type}{update.join} = {update.value!r}")


async def main() -> None:
    async with CipClient("192.168.1.10", 0x03) as panel:
        panel.subscribe(on_join)  # everything the processor sends
        await panel.pulse(101)  # tap button d101
        print(panel.get_analog(361))  # last value of a361
        panel.set_serial(10, "hello")  # latched serial output
        await asyncio.sleep(30)


asyncio.run(main())

API

Smart-object joins: pass smart_object= to the getters; JoinUpdate.smart_object tells you where an update came from.

Options

Things to know about processors

• The processor sends a panel only changes relative to what it believes the panel already shows. After a (re)connect, the initial dump contains non-default values only, and a "paged" panel may not resend a value until it changes.
• Button-style digitals are released by the processor unless repeated within about 0.5 s. press() repeats for you until release().
• Two clients on one IP ID share one panel. On paged panels that means one shared page: one client's navigation changes what the other sees. Give automation its own IP ID where you can.
• Directly setting an analog that the program drives (for example a dimmer level) often does nothing: the program expects the panel's raise/lower buttons.

Testing Your Code

FakeProcessor is a small CIP server that behaves like a real processor as far as observed: it greets, registers panels, answers heartbeats, packs its initial dump and ends it with end-of-query. It can also misbehave: wrong IP ID, silence, dropped connections, split or coalesced frames.

from pycrestron_cip import CipClient
from pycrestron_cip.testing import FakeProcessor


async def test_scene_indicator():
    async with FakeProcessor(ipids={0x03}) as proc:
        proc.digital[350] = True
        async with CipClient("127.0.0.1", 0x03, port=proc.port) as panel:
            assert panel.get_digital(350)
            await panel.pulse(101)
        assert [u.join for u in proc.joins_received()] == [101, 101]  # press, release

Probing a Processor

pycrestron-cip-probe (or python -m pycrestron_cip.probe) connects as a panel, records everything the processor sends and disconnects. It sends only what the protocol requires (no button presses, no join values):

pycrestron-cip-probe 192.168.1.10 0x03 --seconds 120 --log probe.log --json probe.json

Stop anything else that uses the same IP ID first. Please do not publish probe logs from a real installation: they contain room names, addresses and whatever the panel shows.

Protocol

docs/protocol.md describes the wire format as implemented, what was verified on hardware, other implementations and the open questions.

Contributing

See CONTRIBUTING.md. Captures from other processors (4-Series, TLS, authentication) are especially welcome.

License

MIT