Introduction

Welcome to libcbus!

This is a Python library for interacting with Clipsal C-Bus networks through a PCI or CNI.

This consists of:

• A C-Bus MQTT bridge (cmqttd), which provides a high level API for controlling C-Bus networks with other systems (such as Home Assistant)
• A low-level interface for parsing and producing C-Bus packets, and using a PCI with asyncio
• A library for parsing information from C-Bus Toolkit project backup files, and visualising networks with graphviz
• A “fake PCI” test server for parsing data sent by C-Bus applications.

It is a completely open source implementation (LGPLv3) of the C-Bus PCI/CNI protocol in Python, based on Clipsal’s public documentation of the PCI Serial Interface and some reverse engineering.

Unlike a number of other similar projects, it does not depend on C-Gate or libcbm. This makes the code much more portable between platforms, as well as avoiding the hazards of closed-source software. :)

Warning

Despite using RJ45 connectors and CAT-5 cabling commonly associated with Ethernet networks, C-Bus uses totally different signalling (about 10 kbit/s) and has a 36 volt power feed.

_You cannot patch an ordinary network card into a C-Bus network._

This project requires a PCI or CNI to communicate with a C-Bus network.

What is C-Bus?

C-Bus is a home automation and electrical control system made by Clipsal. It’s also known as Square D in the United States, and sold under other brands worldwide by Schnider Electric.

It uses low voltage (36 volts) wiring for light switches (panels) and other sensors, and centrally-fed dimmer and relay controls for devices (such as lights).

The C-Bus PCI and CNI can interface with a C-Bus network via Serial [1] and TCP/IPv4 respectively. These use a common interface described in the Serial Interface Guide, and other public C-Bus documentation.

[1]	The PCI is also available in a USB variant, which uses an in-built cp210x USB to Serial converter. It is otherwise functionally identical to the Serial version.

Clipsal’s other interfaces

In addition to protocol documentation, Clipsal also provide two systems for interacting with C-Bus, libcbm and C-Gate. Clipsal’s own software (like Toolkit) and hardware (like Wiser) use this to interact with C-Bus networks over serial and IPv4.

libcbm

libcbm supports to C-Bus protocol completely, including conforming to the various “protocol certification levels”.

It is written in C, and distributed as a static library for x86_32 Linux and Windows systems. Clipsal has released its source code under the Boost license, which also includes Delphi bindings and support for ARMv3/4/4T, Hitachi/Renesas H8, PowerPC 405 (on Linux) and TI MSP430 processors.

This hasn’t been updated since 2009, and doesn’t support x86_64 or comparatively-modern ARM CPUs (such as that used in the Raspberry Pi).

C-Gate

C-Gate is a closed source, C-Bus abstraction service written in Java.

It appears to support a subset of the C-Bus protocol, and comparing its interactions with a PCI with the Serial Interface Guide seems to suggest it is using a bunch of commands that are officially deprecated.

It depends on the (closed source) SerialIO library for serial communication, which requires a JNI library that is only available on x86_32 Windows and old versions of Linux.