Skip to content

DamianFlynn/cgate-mqtt

BranchesTags
 
 

Repository files navigation

C-Gate to MQTT Bridge for CBUS Integration

The C-Gate to MQTT Bridge project offers a powerful solution for seamlessly integrating Clipsal CBUS PLCs with MQTT-enabled IoT devices and services. This repository provides the necessary code and comprehensive instructions to deploy and configure the C-Gate to MQTT Bridge. The application goes beyond basic integration by incorporating MQTT Discovery for Home Assistant, enabling automatic device recognition and configuration.

The code is based on the original fork the1laz

Purpose

This project aims to establish a bridge between the Clipsal C-Gate Server and MQTT, unlocking the potential for real-time, bi-directional communication between CBUS PLCs and various IoT platforms. By supporting MQTT Discovery for Home Assistant, the project simplifies the process of integrating CBUS devices into Home Assistant's ecosystem, enhancing automation and control capabilities.

Features

  • Seamless CBUS Integration: The C-Gate to MQTT Bridge connects CBUS PLCs with MQTT brokers, facilitating real-time communication and control.
  • MQTT Discovery for Home Assistant: The application supports MQTT Discovery, automatically configuring CBUS devices within Home Assistant as Dimmers, Switches, or Phantoms.
  • Trigger Application Support: The project includes support for CBUS Trigger applications, enabling Home Assistant to identify and respond to triggered events.
  • eDLT Label Support: Dynamic labelling support for C-Bus DLT wall switches, allowing real-time label updates via MQTT with automatic time/date synchronization.
  • Flexible Configuration: Users can customize the application's settings to align with their specific CBUS setup and MQTT broker.

CBUS Lighting and Trigger Applications

  1. Configure CBUS Toolkit with MQTT Discovery information for lighting devices.
  2. Run the C-Gate to MQTT Bridge, connecting it to your C-Gate Server and MQTT broker.
  3. Home Assistant will automatically recognize lighting devices and configure them as Dimmers, Switches, or Phantoms.
  4. When CBUS trigger applications are fired, Home Assistant will receive MQTT Events and can respond accordingly.
  5. Use Home Assistant to control CBUS lighting devices.

eDLT (Electronic Dynamic Labelling Technology)

The bridge now supports dynamic labelling for C-Bus DLT wall switches:

  • Dynamic Label Updates: Update DLT switch labels in real-time via MQTT
  • Automatic Time/Date Sync: Keep DLT units synchronized with current time
  • Auto-Discovery: Automatically detects DLT units from your C-Bus project file
  • Template Support: Optional templating for dynamic content (e.g., temperature displays)

For detailed DLT usage instructions, see DLT-SUPPORT.md.

Usage

You can easily and quickly get your C-Bus connected to MQTT, by implementing the following stack.

  • ser2sock: Serial Port to TCP Socket proxy, Optional to implement, supports USB to Serial Adaptors
  • cgate-server: Clipsal C-Gate server, can be configured to connect directly to CNI or via ser2sock. Recommended as this allows for the C-Bus toolkit to be used remotely in parallel
  • cgate-mqtt: Bridge C-Bus Applications to MQTT. MQTT can be integrated into many platforms including Home Assistant

The following docker-compose.yaml file will load and run the complete stack. You just need to configure each application as directed.

version: '3.8'

x-disabled:

services:

  # CNI Serial port (RS232 to USB) to TCP 10001
  ser2sock:
    hostname: "ser2sock"
    image: ghcr.io/damianflynn/ser2sock:latest
    container_name: ser2sock
    restart: unless-stopped
    networks:
      - proxy
    ports:
        - 10001:10001
    environment:
      - "SERIAL_DEVICE=/dev/ttyUSB0"
    volumes:
      - /dev/ttyUSB0:/dev/ttyUSB0
    devices:
      - /dev/serial/by-id/usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0:/dev/ttyUSB0
    privileged: true

  # Clipsal C-Bus C-Gate Server
  cgate-server:
    hostname: "cgate-server"
    image: ghcr.io/damianflynn/cgate-server:latest
    container_name: cgate-server
    depends_on:
      - ser2sock
    networks:
      - proxy
    ports:
        - 20023:20023
        - 20024:20024
        - 20025:20025
        - 20026:20026
        - 20123:20123
    volumes:
        - /opt/appdata/cbus/config:/config
        - /opt/appdata/cbus/tags:/tag
        - /opt/appdata/cbus/logs:/logs
    restart: unless-stopped

  # C-Gate to MQTT Bridge
  cgate-mqtt:
    hostname: "cgate-mqtt"
    image: ghcr.io/damianflynn/cgate-mqtt:latest
    container_name: cgate-mqtt
    restart: unless-stopped
    networks:
      - proxy
    depends_on:
      - cgate-server
    volumes:
      - /opt/appdata/cbus/settings.js:/usr/src/app/settings.js
      - /opt/appdata/cbus/tags/CBUS-PROJECT.xml:/usr/src/app/HOME.xml


networks:
  proxy:
    driver: bridge
    external: true

Configuration

Modify the settings.js file to configure the following options:

  • mqtt: MQTT broker connection settings.
  • cbusip: IP address of the C-Bus system.
  • cgateCmdPort: Port for C-Gate command channel.
  • cgateEventPort: Port for C-Gate event channel.
  • logging: Enable/disable console logging.
  • messageinterval: Interval for processing MQTT messages.
  • enableHassDiscovery: Enable Home Assistant MQTT discovery.
  • topicPrefix: MQTT topic prefix.
  • retainreads: Retain MQTT messages for read requests.
  • getallnetapp: Network application for getting all values.
  • getallonstart: Get all values on startup.
  • getallperiod: Period for getting all values.
  • enableDltSupport: Enable DLT dynamic labelling support.
  • enableDltTemplating: Enable template processing in DLT labels.
  • updateDltTimeOnStart: Update DLT time/date on startup.
  • updateDltTimePeriod: Period for updating DLT time/date.

This is my current settings.js

//Ser2Sock IP Address
exports.cbusip = '172.100.10.100';

//cbus project name
exports.cbusname = "HOME";

//mqtt server ip:port (my Home Assistant MQTT Broker)
exports.mqtt = '172.100.10.110:1883';
exports.mqttusername = 'cbus';
exports.mqttpassword = 'Password!';

// Map the C-Bus project information to Home Assistant Discovery Messages
exports.enableHassDiscovery = true;

// These should not need to be changed
exports.getallonstart = true;
exports.getallnetapp = '254/56';
exports.getallperiod = 60*15;
exports.retainreads = true;
exports.messageinterval = 200;

//logging
exports.logging = false;

C-Bus Project Configuration

The application supports parsing C-Bus project configuration from XML files. The C-Bus Project file (XML only currently) should be mapped to the container as follows

    volumes:
      - /opt/appdata/cbus/tags/CBUS-PROJECT.xml:/usr/src/app/HOME.xml

In this case, my project file is stored on the disk as /opt/appdata/cbus/tags/CBUS-PROJECT.xml and is mapped into the container. You should edit this to match your own project file. Note: The suffix :/usr/src/app/HOME.xml should not be changed currently for the application to correctly locate the project

Building

  1. Clone this repository to your local machine.
  2. Navigate to the project directory.

Docker

The included Dockerfile can be used to create a container for the project

docker build -t cgate-mqtt:latest .
docker create \
    --name cgate-mqtt \
    -v path/to/settings.js:/usr/src/settings.js \
    --restart unless-stopped \
    cgate-mqtt:latest

Local Installation

Install the required Node.js packages using the following command:

npm install

Configure the settings in the settings.js file to match your environment. Run the application using the following command:

node <path-to-your-app>/app.js

Dependencies

The following Node.js packages are used in this project:

  • mqtt: MQTT client library for Node.js.
  • net: Provides networking functionality.
  • events: Provides event handling capabilities.
  • xml2js: XML to JavaScript object converter.
  • fs: Provides file system-related functionality.
  • path: Provides utilities for working with file and directory paths.

Features

  • [-] Connects to MQTT broker and C-Gate system.
  • [-] Handles C-Bus commands and events.
  • [-] Supports MQTT topics for lighting control and status.
  • [-] Provides Home Assistant MQTT discovery for easy integration.
  • HVAC, I haven't try it but have a look at this fork: https://github.com/mminehanNZ/cgateweb)

MQTT Topics

The application uses MQTT topics for communication. The topics are structured as follows:

Bridge and Lighting Topics

  • cbus/bridge/cbus2-mqtt/state: Bridge online/offline status.
  • cbus/event/cbus2-mqtt/<unique_id>/state: Trigger Events.
  • cbus/light/cbus2-mqtt/<unique_id>/state: Light state (ON/OFF).
  • cbus/light/cbus2-mqtt/<unique_id>/set: Set light state.
  • cbus/light/cbus2-mqtt/<unique_id>/brightness: Light brightness (0-100).
  • cbus/light/cbus2-mqtt/<unique_id>/brightness/set: Set Light brightness (0-100).
  • cbus/light/cbus2-mqtt/<unique_id>/attributes: C-Bus attributes for the group in JSON package, can also be seen in Home Assistant {"cbus_address":"254/56/3","unit_name":"DIM1A-01","unit_address":"0x3","unit_type":"Dimmer","unit_model":"L5508D1A","output_channel":"3"}

DLT Topics

  • cbus/dlt/<network>_<application>_<group>/<line>/set: Set DLT label text (e.g., cbus/dlt/254_56_129/1/set)
  • cbus/dlt/<network>_<application>_<group>/<line>/state: Current DLT label text

Where:

  • <network>: C-Bus network (typically 254)
  • <application>: C-Bus application (typically 56 for lighting)
  • <group>: C-Bus group address
  • <line>: Button/line number (1-5 for most DLT switches)

Troubleshooting

  • If you encounter any issues, enable detail logging and refer to the console logs for more information.
  • Check the configuration settings in settings.js.

Conclusion

The C-Gate to MQTT Bridge project is a comprehensive solution for seamlessly integrating Clipsal CBUS PLCs with MQTT-enabled IoT devices and services. By facilitating real-time communication, MQTT Discovery, and support for trigger applications, this application enhances the automation and control capabilities of CBUS systems within the larger IoT ecosystem. Through this bridge, users can unlock new possibilities for managing their CBUS lighting and trigger applications.

Versioning & Releases

This project uses Conventional Commits and Release Please to automate versioning and changelog generation.

How it works

Every commit merged to main should follow the conventional commit format:

Prefix Effect Example
fix: Patch version bump (0.4.x) fix: prevent crash on short MQTT topic
feat: Minor version bump (0.x.0) feat: add DLT label support
fix!: / feat!: Breaking change: minor bump on 0.x (e.g. 0.4.0 → 0.5.0), major bump on ≥1.0.0 (x.0.0) feat!: breaking change to topic structure
chore:, docs:, refactor: No version bump chore: pin Dockerfile base image

Release flow

  1. After each push to main, Release Please automatically opens (or updates) a "chore: release X.Y.Z" pull request.
  2. That PR contains the version bump in src/package.json and updated CHANGELOG.md entries grouped by commit type.
  3. When you are ready to ship, merge the Release Please PR — this creates a GitHub Release and pushes a semver tag (e.g. v0.5.0).
  4. The tag triggers the Docker publish workflow, which builds and pushes:
    • ghcr.io/damianflynn/cgate-mqtt:0.5.0
    • ghcr.io/damianflynn/cgate-mqtt:0.5
    • ghcr.io/damianflynn/cgate-mqtt:latest

You control when a release happens — commits accumulate in the Release Please PR until you decide to merge it.

Contributors

Thanks to everyone who has contributed code to this project:

Contributor Contribution
@DamianFlynn Original author and maintainer
@the1laz Message queue implementation (original cgateweb fork)
@tomtokic eDLT (Electronic Dynamic Labelling) support
@NickLocke Fix deprecated object_id for Home Assistant 2026.04
@DaveQB Fix crash on malformed C-Bus trigger events

Contributions are welcome! If you have suggestions, bug reports, or feature requests, please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

About

MQTT interface for C-Bus written in Node.js

Resources

Readme

License

MIT license
Activity

Stars

12 stars

Watchers

1 watching

Forks

5 forks
Report repository

Releases 5

v0.4.5 Latest
Apr 3, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages

  • JavaScript 99.0%
  • Dockerfile 1.0%