bosch-control-panel-cc880p 3.1.0

Library to interface with the old CC880p Bosch COntrol Panels

Bosch Control Panel CC880P

Library to interface with the old CC880P Bosch Alarm Control Panels
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • The Reason Behind
   • Interface
   • Wiring
   • Uart Pinout and Configuration
   • Protocol
   • Frames
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About the Project

The Reason Behind

The reason behind the the development of this library, was the need turn the old Bosch Control Panel into a smart device without the need to replace it.

Home Assistant is the home automation I use, and I wanted to integrate also the Bosch control panel into it.

Because there wasn't any integration I could use for that purpose, I decided to implement the library myself and use it as dependency for the custom component bosch_control_panel_cc880 also developed by me for Home Assistant.

(back to top)

Interface

Thanks to this webpage, it was possible to figure out that the interface with the control panel can be done through the UART accessible through the auxiliary module pins (see the UART Pinout). As mentioned in the website, it is possible to completely replace the direct link cable usually needed to configure the control panel through the computer using the A Link Plus software.

(back to top)

Wiring

To sniff and decode the packets supported by the control panel, it was followed the wiring as in the following diagram:

The information about A-Link Plus can be found here. The USB-TTL converter can be a device similar to this.

To make the alarm remotely accessible, it was used a TCP/IP to UART bridge. The current and tested solution was wired as following:

The library bosch-control-panel-cc880p is part of this repository. The ESP8266 represents any device using that chip such as ESP1. Note that it should be flashed with a software like ESP-Link to create a bridge between TCP/IP and UART. Since ESP1 operates at 3.3V and CC880P control panel operates at 5V, there's the need to use a level shifter, or something similar (see this site for examples).

A better solution would be wiring the system as the diagram below:

Using a device like Elfin-EW10 would prevent the usage of level shifter as it also operates at 5V, as well as remove the need to flash any firmware as the device already provides everything needed.

(back to top)

UART Pinout and Configuration

The pinout of the CC880P control panel is:

• TX: Auxiliary Module Pin3 (Note: The website describes the Pin7 by mistake)
• RX: Auxiliary Module Pin7 (Note: The website describes the Pin3 by mistake)
• GND: Auxiliary Module Pin4
• VCC(5V): Auxiliary Module Pin6

The baud rate the control panel operates is 300.

(back to top)

Protocol

Since there was no information about the protocol used to send commands to the control panel and receive the corresponding responses, the approach was to connect the control panel using the A Link Plus and then sniff and decode the packets being transferred back and forth. the following steps were followed:

1. Wiring (see Wiring chapter)
2. Execute the A Link Plus and connect the Alarm (see A Link Plus manual here)
3. Monitor and decode the packets (using a software similar to this )

The result is presented in the frames section.

(back to top)

Frames

Below are presented the decoded frames that are used by this library so far:

Send Keys Command

Command used to send keys to the control panel simulating the pressing of the keypad keys.

'Send Keys' Command

C0 <k1> <k2> <k3> <k4> <k5> <k6> <k7> <area> <nKeys> <crc>

Byte    Identifier  Comments
-------------------------------------------------------------------------------
1       C0          Hexadecimal representation of the 'Send Key' command
2-8     k<n>        Each byte is represents the key of the keypad. Can be sent
                        from 1 up to 7 keys in a single command
9       area        If the alarm is configured to have multiple areas, then
                        this byte identifies the target area that the key(s)
                        will be sent to. Otherwise set it to '00'.
10      nKeys       Number of keys being sent in this command
11      crc         Frame checksum (excluding the 1st byte)

Set Siren Command (Special Command)

Command used to enable/disable the siren

'Set Siren' Command

0E <on> 00 00 00 00 00 00 00 00 <crc>

Byte    Identifier  Comments
-------------------------------------------------------------------------------
1       0E          Hexadecimal representation of the special commands
2       on          Sets the siren on or off:
                      - 0x05 if is to set siren on
                      - 0x06 if is to set siren off
3-10    XX          Not used and thus, set to 0.
11      crc         Frame checksum (excluding the 1st byte)

Set Arm Command (Special Command)

Command used to arm/disarm the alarm

'Arm/Disarm' Command

0E <arm> 00 00 00 00 00 00 00 00 <crc>

Byte    Identifier  Comments
-------------------------------------------------------------------------------
1       0E          Hexadecimal representation of the special commands
2       on          Arm/Disarm the alarm:
                      - 0x01 if is to arm the alarm
                      - 0x02 if is to disarm the alarm
3-10    XX          Not used and thus, set to 0.
11      crc         Frame checksum (excluding the 1st byte)

Set Output Command

Command used to set (enable/disable) outputs of the control panel.

'Set Output' Command

0E <on> <out> 00 00 00 00 00 00 00 <crc>

Byte    Identifier  Comments
-------------------------------------------------------------------------------
1       0E          Hexadecimal representation of special commands
2       on          Special function to be executed:
                        Set Output On: Set this byte to 0x03
                        Set Output Off: Set this byte to 0x04
3       out         This byte represents the index of the target output.
                      Supports setting the outputs 1-5, which values in this
                      byte are 0-4 respectively.
4-10    XX          All those bytes should be set to 0.
11      crc         Frame checksum (excluding the 1st byte)

Get Status Command

Command used to request the overall status of the control panel. After sending this command is expected the control panel to answer with the Get Status Response.

'Get Status' Command

01 00 00 00 <c2c1> <c4c3> <c6c5> <c7> 00 00 <crc>

Byte   Identifier   Comments
----------------------------
1       01          Hexadecimal representation of the 'Get Status' command.
2-4     XX          This bytes are not used and thus set to 0.
5-8     c1..c7      Corresponds to the installer code needed to have permissions
                      to get the alarm status. Each digit occupies a nibble.
                      Not used digits should be set to 0xF.
9..10   XX          This bytes are not used and thus set to 0.
11      crc         Frame checksum (excluding the 1st byte)

Get Status Response

Response of Get Status Command. This frame contains all the relevant information about the status of the control panel.

'Get Status' Response

04 <out> <out> <zone> <zone> <en> <en> XX XX <area> <s/h> <m>

Byte   Identifier   Comments
----------------------------
1       04      :   Hexadecimal representation of the 'Get Status' response
2-3     out     :   Each bit set indicates whether an output is on.
                        Maximum number of outputs is 14.
                        Bits 1-8 of byte 3 correspond to the outputs 1-8 of the
                        control panel.
                        Bits 1-6 of byte 2 correspond to the outputs 9-14 of the
                        control panel.
                        Bits 7-8 of byte 2 are not used.
4-5     zone    :   Each bit set indicates whether a zone is triggered.
                        Maximum number of zones is 16.
                        Bits 1-8 of byte 4 correspond to the zones 1-8 of the
                        control panel.
                        Bits 1-8 of byte 5 correspond to the zones 9-16 of the
                        control panel.
6-7     en      :   Each bit set indicates whether a zone is enabled (only
                        applied when the mode of the alarm is set to `STAY`, as
                        in this mode is possible to have only a subset of zones
                        enabled).
                        Bits 1-8 of byte 6 correspond to the zones 1-8 of the
                        control panel.
                        Bits 1-8 of byte 7 correspond to the zones 9-16 of the
                        control panel.
8-9     XX      :   Unknown and not used bytes.
10      area    :   Indicates whether the stay status as well as the away
                        status of the control panel is enabled for each area.
                        Maximum number if areas is 4.
                        Bits 1-4 correspond to the away status of the areas 1-4
                        Bits 5-8 correspond to the stay status of the areas 5-8
11      s/h   :   Indicate the status of the siren (1 bit) + the current hours.
                        Bit 6 if set mean the siren is triggered.
                        Bits 0-4 represents the hours (0h-23h)
                        Other bits are not used and thus unknown.
12      m   :   Indicate the current minutes.
                        Bits 0-5 represents the minutes (0m-59m).
                        Other bits are not used and thus unknown.

(back to top)

Getting Started

This library provides a CLI (Command Line Interface) to interact with the control panel.

Prerequisites

Installation

The installation of the library, including the CLI, is as simple as run:

$ pip install .

After that, the library is ready to be used, and now the CLI can be used. To get help how to use it type in the terminal the following:

$ control_panel -h

(back to top)

Usage

After following the Installation section, now the usage of the CLI can be found by running:

$ control_panel -h
usage: control_panel [-h] [-v] -c IP -p PORT {cmd} ...

Connects to the Control Panel

positional arguments:
  {cmd}
    cmd                 Execute a command

options:
  -h, --help            show this help message and exit
  -v, --version         Gets the current version
  -c IP, --connect IP   the host ip
  -p PORT, --port PORT  the host port

There are 2 options to run the CLI as shown in the following sections.

Run in Listen Mode

In this mode, the script will connect to the control panel in listening only mode, where it will output any kind of change on the control panel.

To run it the minimum should be:

$ control_panel -c 192.168.1.22 -p 23

Run in Commanding Mode

This mode, allows the user to send commands to the control panel. To see the list of available commands the user can do:

$ control_panel -c <ip> -p <port> cmd -h
usage: control_panel cmd [-h]  {sendKeys,setMode,setSiren,setOut} ...

positional arguments:
  cmd
  {sendKeys,setMode,setSiren,setOut}
    sendKeys            Sends a set of keys to the control panel. Currently supports the following: [0-9*#]{1,7}
    setMode             Change the control panel mode like arm, disarm, etc
    setSiren            Change the control panel siren status
    setOut              Change the output status of the control panel

options:
  -h, --help            show this help message and exit

The following are some examples:

$ control_panel -c <ip> -p <port> cmd setSiren off
Before: Siren(on=True)
After: Siren(on=False)

$ control_panel -c <ip> -p <port> cmd setSiren 1
Before: Siren(on=False)
After: Siren(on=True)

$ control_panel -c <ip> -p <port> cmd setSiren 1
Before: Siren(on=False)
After: Siren(on=True)

$ control_panel -c <ip> -p <port> cmd setOut 3 on
Before: Output(on=False)
After: Output(on=True)

(back to top)

Roadmap

• Complete documentation:
  • Hardware Used
  • Block diagram of the involved hardware
  • Table of the packets (commands and responses)
  • Other
• Configure precommit and linter
• Implement the battery of unit/integration tests
• Implement a commandline interface
• Gracefully shutdown when a signal is received (e.g. A keyboard Interrupt)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

To contribute to this project, you need to execute the following steps:

1. Install

   1. Create a virtual environment (see how to here):

   2. Activate the virtual environment (see how to here):

   3. Install all the requirements for development:

      pip install -e ".[dev]"

   4. Install pre-commit:

      pre-commit install

2. Create new feature and commit the changes

   1. Create a new feature branch based from the main branch:

      git checkout -b feature/<feature_name>

   2. Implement the changes for the feature

   3. Run formatters/linters:

      1. Autopep8:

         autopep8 src/ tests/

      2. Flake8:

         flake8 src/ tests/

      3. Mypy:

         mypy src/ tests/

   4. Commit the changes (this should run pre-commit to format/lint anyway)

(back to top)

License

Distributed under the Apache License Version 2.0. See LICENSE.txt for more information.

(back to top)

Contact

Hugo Gomes - [e-mail]

Project Link: https://github.com/hgomes88/bosch-control-panel-cc880p

Pipy Releases: https://pypi.org/project/bosch-control-panel-cc880p

(back to top)

Acknowledgments

• [othneildrew] Best Readme Template
• [Yes Thomas] Programming Bosh Alarm Panel without direct link cable

(back to top)