cbus Documentation Release 0.
Contents 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 3 4 4 Hacking 2.1 Official documentation . . . . . . . . . . . . . 2.2 CNI / network protocol . . . . . . . . . . . . . 2.3 Setting up a fake CNI and sniffing the protocol 2.4 USB support / 5500PCU . . . . . . . . . . . . 2.
Python Module Index ii 51
cbus Documentation, Release 0.1-dev Project Page / Source repository: https://github.com/micolous/cbus libcbus is a set of Python libraries for interacting with Clipsal C-Bus.
cbus Documentation, Release 0.
CHAPTER 1 Introduction Welcome to libcbus! This is a Python library for interacting with Clipsal CBus units, and provides some additional utility functions, such as: • A high-level DBus-based API for sharing a CBus PCI with multiple application on a computer. • A library for parsing information from CBus Toolkit project backup files. • A “fake PCI” test server for parsing data sent by CBus applications. 1.1 What is CBus? CBus is a home automation and electrical control system made by Clipsal.
cbus Documentation, Release 0.1-dev libcbus also includes an abstraction daemon called cdbusd which will allow multiple applications to simultaneously use the PCI. This daemon requires D-Bus, which is not available on Windows. Other components of libcbus will continue to function. 1.2.2 Comparison to C-Gate C-Gate is Clipsal’s own C-Bus control software. It is a closed source application written in Java, that uses the SerialIO library (also closed source) or sockets to communicate with a PCI.
cbus Documentation, Release 0.1-dev 1.4.2 Mac OS X In order to run this software, you’ll need to first install Xcode (from the App Store) and MacPorts. You then need to install dbus and the Python bindings for it: # port install dbus +universal 1.4.3 Windows Windows doesn’t have a D-Bus, so you can’t use cdbusd. However, you can use the libraries with Twisted directly. But most of the applications interface with cdbusd. 1.4.
cbus Documentation, Release 0.1-dev 6 Chapter 1.
CHAPTER 2 Hacking Information about using the hardware and software. 2.1 Official documentation Official serial protocol documentation is available from http://training.clipsal.com/downloads/OpenCBus/OpenCBusProtocolDownloads.html Clipsal’s website: You should generally implement software in conjunction with reading these guides.
cbus Documentation, Release 0.1-dev 2.3 Setting up a fake CNI and sniffing the protocol If you want to see how Toolkit interacts with a Serial PCI, use the tcp_serial_redirect.py script from the pySerial example scripts. This can be run even on a non-Windows machine, for dealing with pesky 100 different revisions of PL2303 USB-Serial adapters that require different and conflicting Windows drivers. For example: $ python tcp_serial_redirect.
cbus Documentation, Release 0.1-dev 2.5 Unit Tests There’s some basic unit tests that are written that require you have the nosetests package (nose on pip). When you run nosetests, it will discover all the unit tests in the package and try to run them. I’m targetting Python 2.6 and 2.7 at this time. I’ll have a look into Python 3 support when some more backend libraries that this project requires work on Python 3. Patches still welcome.
cbus Documentation, Release 0.1-dev 10 Chapter 2.
CHAPTER 3 CNI Discovery At the moment this is a rather unorganised set of notes while I’m still figuring out the protocol. I’ve started working on a test program for dissecting the protcol in cbus/discovery_test.py. 3.1 Discovery Query A client will broadcast a UDP packet on 255.255.255.255:20050.
cbus Documentation, Release 0.1-dev Product IDs: • 01: CNI2 • 02: Hidden – Toolkit ignores packets with this product ID. May be used for internal development. • 03: WISER • Other values: “unknown” Example packet data: Recv Client 1 (172.26.1.
CHAPTER 4 Wiser The Wiser is a rebadged SparkLAN WRTR-501 802.11b/g/draft-n WiFi Router with custom firmware. It runs an embedded Linux system, with an expanded web interface for hosting Flash/XMLSocket based control of CBus. According to the source code release from Clipsal, this runs Linux 2.6.17.14. The kernel configuration indicates that the board is a fv13xx ARM system. Also used by: • Airlink101 AR680W • PCi MZK-W04N XMLSocket is also used by the iPhone version of the control software.
cbus Documentation, Release 0.1-dev 4.2 Protocol 4.2.1 Discovery and Handshake After the SWF is started, it loads the configuration file from /clipsal/resources/local_config.xml. This looks like: PAGE 19cbus Documentation, Release 0.1-dev 4.2.4 Project and Skin It also returns a XML which is a form of the project file, and a XML which contains localised strings and resource image references. This can also be downloaded from /clipsal/resources/project.
cbus Documentation, Release 0.1-dev 4.4 CFTP CFTP is a service which acts as a back-door into the device. It runs on port 8336, and is managed by the service cftp_daemon. It has a hard-coded password to access the service. Despite the name, it doesn’t actually implement FTP. It is used by Clipsal’s programming software in order to manage the device. It appears to have the following functionality: • Manage port forwards inside of the network when the device is acting as the router for the network.
cbus Documentation, Release 0.1-dev 4.4.3 Authenticated state When in the authenticated state, the network code appears to be far less robust. Sending large commands causes the daemon to crash. This may be an effective and easy way to disable cftp_daemon on the device. PASS Client command: PASS bloop Server response: 201 Logged in Transitions to the authenticated state. Has no effect in authenticated mode. Note: There is no way to change this password. It is hard coded in Wiser’s firmware.
cbus Documentation, Release 0.1-dev GETFILELIST Client command: GETFILELIST Server response: 202 FILE1=C:\HomeGate\Projects\Current\EXAMPLEproj.tar.gz Retrieves a list of “files” on the device associated with the project. This only returns the project file. The path is faked by the daemon, with “EXAMPLE” replaced by the project name. GETPROJ Client command: GETPROJ Server response: 202-Port=8337 202 FILE=C:\HomeGate\Projects\Current\EXAMPLEproj.tar.
cbus Documentation, Release 0.1-dev – cftp_daemon will not be able to copy a new project file into RAM temporarily for flashing, and may be permanently stuck in this state. This partial brick state could probably gotten around by writing NULL over the contents of /dev/mtdblock/6, then transferring a new project file. 4.5 Firmware image Firmware image for the device is bundled with the PICED software as Firmware/firmware_1_24_0.img.
cbus Documentation, Release 0.1-dev 20 Chapter 4.
CHAPTER 5 daemons The cbus.daemon package defines a number of daemons used to interact with the C-Bus network. 5.1 cdbusd cdbusd is a daemon that is used to allow multiple applications on the same computer to share use of a PC Interface. The daemon also provides clock services to the C-Bus network. It is recommended when building C-Bus applications that you use the D-Bus interface to the network. For more information on the D-Bus client interface, please see D-Bus Client API. 5.
cbus Documentation, Release 0.1-dev • saged which is a backend WebSockets server that translates WebSockets messages into messages in cdbusd, and implements some basic access controls. • sageclient.js which implements the saged WebSockets protocol in JavaScript. • sageui.js which implements the UI of sage itself, which is built on jQuery Mobile. 5.3.1 Running sage requires that you have a running instance of cdbusd first.
cbus Documentation, Release 0.1-dev • locations: A dictionary of locations, with the key representing the ID of the location, and the value representing the name to display. Location 0 must exist, and is shown by default. • widgets: A dictionary of group addresses describing what widgets to display. – The key is the group address to control. – The option name sets the name to display in the UI.
cbus Documentation, Release 0.1-dev 5.3.3 Screenshots Android (Chrome) 24 Chapter 5.
cbus Documentation, Release 0.1-dev 5.3.
cbus Documentation, Release 0.1-dev iOS “Web App” 26 Chapter 5.
cbus Documentation, Release 0.1-dev 5.3.
cbus Documentation, Release 0.1-dev 5.4 staged staged is a scene control daemon. This isn’t finished yet. It connects to cdbusd, and allows you to create simple scenes that react to messages sent to particular group addresses. 28 Chapter 5.
CHAPTER 6 dump_labels utility dump_labels parses a Toolkit backup file (CBZ) and prints out group and unit address labels into a JSON file. It will remove all unneeded programming markup from the CBZ, and leave a skeleton of information which can be used in conjunction with the library and other applications. 6.
cbus Documentation, Release 0.1-dev 30 Chapter 6.
CHAPTER 7 D-Bus Client API The recommended way to interact with libcbus is through cdbusd and it’s D-Bus API. It allows many applications, written in any language with D-Bus bindings to interact with the network with one PCI. It abstracts away the majority of C-Bus protocol details and provides D-Bus methods and events for interacting with the network. This document describes the interface au.id.micolous.cbus.CBusInterface.
cbus Documentation, Release 0.1-dev • level (d) – An amount between 0.0 and 1.0 indicating the brightness to set. Returns Single-byte string with code for the confirmation event. Return type s # Fades GA 5 to 45% brightness over 12 seconds. mdbus2 -s au.id.micolous.cbus.CBusService / au.id.micolous.cbus.CBusInterface.lighting_group_ram lighting_group_terminate_ramp(group_addr) Stops ramping a group address at the current point. Parameters group_addr (y) – Group address to stop ramping of.
CHAPTER 8 libcbus module index 8.1 cbus Package This is the package where all C-Bus modules are defined. 8.1.1 Common functions cbus.common defines various common helper utilities used by the library, and constants required to communicate with the C-Bus network. The majority of the functionality shouldn’t be needed by your own application, however it is used internally within the protocol encoders and decoders. cbus.common.add_cbus_checksum(i) Appends a C-Bus checksum to a given message.
cbus Documentation, Release 0.1-dev Throws ValueError If the given duration is too long and cannot be represented. cbus.common.get_real_cbus_checksum(i) Calculates the supposedly correct cbus checksum for a message. Assumes input of a base16 encoded message with the checksum ignored. cbus.common.ramp_rate_to_duration(rate) Converts a given ramp rate code into a duration in seconds. Parameters rate (int) – The ramp rate code to convert. Returns The number of seconds the ramp runs over.
cbus Documentation, Release 0.1-dev class cbus.protocol.base_packet.SpecialPacket Bases: cbus.protocol.base_packet.BasePacket checksum = False destination_address_type = None dp = None priority_class = None rc = None class cbus.protocol.base_packet.SpecialClientPacket Bases: cbus.protocol.base_packet.SpecialPacket Client -> PCI communications have some special packets, which we make subclasses of SpecialClientPacket to make them entirely seperate from normal packets.
cbus Documentation, Release 0.1-dev application = None classmethod decode_packet(data, checksum, flags, destination_address_type, rc, dp, priority_class) encode(source_addr=None) group_address = None level_request = False status_request = False pp_packet Module class cbus.protocol.pp_packet.PointToPointPacket(checksum=True, unit_address=0, hops=None) Bases: cbus.protocol.base_packet.
cbus Documentation, Release 0.1-dev Parameters line (str) – CBus event data Returns Remaining unparsed data (str) or None on error. Return type str or NoneType delimiter = ‘\r\n’ identify(unit_address, attribute) Sends an IDENTIFY command to the given unit_address. Parameters • unit_address (int) – Unit address to send the packet to • attribute (int) – Attribute ID to retrieve information for. See s7.2 of Serial Interface Guide for acceptable codes.
cbus Documentation, Release 0.1-dev Return type string lineReceived(line) Called by LineReciever when a new line has been recieved on the PCI connection. Do not override this. Parameters line (str) – Raw CBus event data on_clock_request(source_addr) Event called when a unit requests time from the network. Parameters source_addr (int) – Source address of the unit requesting time. on_clock_update(source_addr, variable, val) Event called when a unit sends time to the network.
cbus Documentation, Release 0.1-dev on_lighting_label_text(source_addr, group_addr, flavour, language_code, label) Event called when a group address’ label text is updated. Parameters • source_addr (int) – Source address of the unit that generated this event. • group_addr (int) – Group address to relabel. • flavour (int) – “Flavour” of the label to update. This is a value between 0 and 3. • language_code (int) – Language code for the label.
cbus Documentation, Release 0.1-dev connectionMade() Called by twisted a connection is made to the PCI. This doesn’t get fired in normal serial connections, however we’ll send a power up notification (PUN). Serial Interface User Guide s4.3.3.4, page 33 decode_cbus_event(line) Decodes a CBus event and calls an event handler appropriate to the event. Do not override this. Parameters line (str) – CBus event data Returns Remaining unparsed data (str) or None on error.
cbus Documentation, Release 0.1-dev lighting_group_terminate_ramp(source_addr, group_addr) Stops ramping a group address at the current point. Parameters • source_addr (int) – Source address of the event. • group_addr (int) – Group address to stop ramping of. Returns Single-byte string with code for the confirmation event. Return type string lineReceived(line) Called by LineReciever when a new line has been recieved on the PCI connection. Do not override this.
cbus Documentation, Release 0.1-dev Applications Running ontop of the C-Bus protocols are applications. This package provides encoders and decoders for application-level messages on the C-Bus network. Application messages inside of C-Bus packets are called “Specific Application Language”, or SALs for short. A packet may contain many SALs for a single application, up to the MTU of the C-Bus network.
cbus Documentation, Release 0.1-dev Parameters • packet (cbus.protocol.base_packet.BasePacket) – The packet that this SAL is to be included in. • variable (int) – The variable being updated. • val (date or time) – The value of that variable. Dates are represented in native date format, and times are represented in native time format. classmethod decode(data, packet, command_code) Do not call this method directly – use ClockSAL.decode encode() is_date is_time class cbus.protocol.application.clock.
cbus Documentation, Release 0.1-dev classmethod decode(data, packet) Decodes a enable control application packet and returns it’s SAL(s). Parameters • data (str) – SAL data to be parsed. • packet (cbus.protocol.base_packet.BasePacket) – The packet that this data is associated with. Returns The SAL messages contained within the given data. Return type list of cbus.protocol.application.enable.EnableSAL encode() Encodes the SAL into a format for sending over the C-Bus network. class cbus.protocol.application.
cbus Documentation, Release 0.1-dev Base type for lighting application SALs. This should not be called directly by your code! Use one of the subclasses of cbus.protocol.lighting.LightingSAL instead. classmethod decode(data, packet) Decodes a lighting application packet and returns it’s SAL(s). Parameters • data (str) – SAL data to be parsed. • packet (cbus.protocol.base_packet.BasePacket) – The packet that this data is associated with. Returns The SAL messages contained within the given data.
cbus Documentation, Release 0.1-dev class cbus.protocol.application.lighting.LightingOffSAL(packet, group_address) Bases: cbus.protocol.application.lighting.LightingSAL Lighting off event SAL Instructs a given group address to turn it’s load off. Creates a new SAL Lighting Off message. Parameters • packet (cbus.protocol.base_packet.BasePacket) – The packet that this SAL is to be included in. • group_address (int) – The group address to turn off.
cbus Documentation, Release 0.1-dev class cbus.protocol.application.temperature.TemperatureSAL(packet=None, group_address=None) Bases: object Base type for temperature broadcast application SALs. This should not be called directly by your code! Use one of the subclasses of cbus.protocol.temperature.TemperatureSAL instead. classmethod decode(data, packet) Decodes a temperature broadcast application packet and returns it’s SAL(s). Parameters • data (str) – SAL data to be parsed. • packet (cbus.protocol.
cbus Documentation, Release 0.1-dev This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see . class cbus.toolkit.cbz.CBZ(fh) Bases: object Opens the file as a CBZ.
CHAPTER 9 Indices and tables • search 49
cbus Documentation, Release 0.1-dev 50 Chapter 9.
Python Module Index c cbus.common, 33 cbus.protocol.application.clock, 42 cbus.protocol.application.enable, 43 cbus.protocol.application.lighting, 44 cbus.protocol.application.temperature, 46 cbus.protocol.base_packet, 34 cbus.protocol.dm_packet, 35 cbus.protocol.packet, 35 cbus.protocol.pciprotocol, 36 cbus.protocol.pciserverprotocol, 39 cbus.protocol.pm_packet, 35 cbus.protocol.pp_packet, 36 cbus.protocol.reset_packet, 36 cbus.protocol.scs_packet, 36 cbus.toolkit.
cbus Documentation, Release 0.
Index A ClockApplication (class in cbus.protocol.application.clock), 42 add_cbus_checksum() (in module cbus.common), 33 ClockRequestSAL (class in application (cbus.protocol.pm_packet.PointToMultipointPacket cbus.protocol.application.clock), 43 attribute), 35 ClockSAL (class in cbus.protocol.application.clock), 42 application_addr1 (cbus.protocol.pciserverprotocol.PCIServerProtocol ClockUpdateSAL (class in attribute), 39 application_addr2 (cbus.protocol.pciserverprotocol.PCIServerProtocolcbus.protocol.
cbus Documentation, Release 0.1-dev decode_cbus_event() (cbus.protocol.pciprotocol.PCIProtocolencode() (cbus.protocol.application.lighting.LightingRampSAL method), 36 method), 45 decode_cbus_event() (cbus.protocol.pciserverprotocol.PCIServerProtocol encode() (cbus.protocol.application.lighting.LightingSAL method), 40 method), 45 decode_packet() (cbus.protocol.dm_packet.DeviceManagementPacket encode() (cbus.protocol.application.lighting.
cbus Documentation, Release 0.1-dev lighting_group_terminate_ramp(), 32 method), 41 lighting_group_terminate_ramp() on_lighting_group_terminate_ramp() (cbus.protocol.pciprotocol.PCIProtocol (cbus.protocol.pciprotocol.PCIProtocol method), 37 method), 38 lighting_group_terminate_ramp() on_lighting_group_terminate_ramp() (cbus.protocol.pciserverprotocol.PCIServerProtocol (cbus.protocol.pciserverprotocol.PCIServerProtocol method), 40 method), 41 LightingApplication (class in on_lighting_label_text() (cbus.
cbus Documentation, Release 0.1-dev SpecialServerPacket (class in cbus.protocol.base_packet), 35 status_request (cbus.protocol.pm_packet.PointToMultipointPacket attribute), 36 T TemperatureApplication (class cbus.protocol.application.temperature), 46 TemperatureBroadcastSAL (class cbus.protocol.application.temperature), 47 TemperatureSAL (class cbus.protocol.application.temperature), 46 in in in V validate_cbus_checksum() (in module cbus.common), 34 validate_ga() (in module cbus.
