pycrestron-cip — asyncio client for Crestron-over-IP

Your code becomes a touch panel. See every digital, analog and serial join a Crestron processor sends,
press any button — without touching the processor's program.

Quick start · Highlights · Why · API · Testing · Probe · Protocol

CIP (Crestron-over-IP) is the protocol that touch panels and XPanel use to talk to a Crestron control processor. pycrestron-cip connects as a panel IP ID, sees what that panel would see 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.

Highlights

Quick start

pip install pycrestron-cip

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())

You need: Python 3.13 or newer · a processor reachable on TCP 41794 (41796 for TLS) · a panel IP ID defined in the processor's program that nothing else is using (see below).

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

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.}

API

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

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().
• 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

Learn more

_{Not affiliated with, endorsed by or supported by Crestron Electronics, Inc. “Crestron” is a trademark of Crestron Electronics, Inc.}