Today i’m launching a native Home Assistant Add-on that hosts CGateWeb, C-Gate and everything required to wire it together into a single installable Add-On.
Some features:
Support for remote hosted and self contained CGate instances
Auto downloader for C-Gate using Scheiders website for the latest C-Gate
Over 50 small bug fixes, with everything from threading issues, performance and testability addressed (over 600 unit tests)
I’d love to hear your feedback, as well as any pull requests and repository issues.
Shout out to @the1laz for all the inspiration from his original 300 line script - this entire project wouldn’t be possible without his original inspiration.
Awesome man, glad to find this! I’ll be trying it out today with my cbus2 system to see if I can get rid of Homebridge once and for all!
[edit from a bit later] With the help of a coding agent - all installed and done! Had trouble with the manage mode, so I/we had to install cgate outside of HA, but that’s fine. All up and running and looking good. Thanks!
Wondering if you might be able to give me a few tips on setting this up correctly. I’m trying to help a friend set-up home assistant who has Cbus in their house but I’ve never used it before.
When using managed mode it seems to not download the cgate server correctly, so I’ve put the .zip in the /share/cgate directory.
Questions:
Is there a specific version of cgate server to use? I’ve used v3.6.0 but it’s looping on start up.
Is the intended work flow to start this add-on, then connect to the cgate server using Cbus toolkit to connect it to the CNI?
We have a wiser 2 unit I was hoping to use as the CNI. Fallback is a USB option. I was hoping we could do it all in one add-on without having to run a separate device for cgate.
Hey Doug, this looks to be exactly what I need. Thanks so much for putting this together!
I am however struggling too with setting up in Managed Mode though and would love your help. The schneider site looks to be full of holes so it’s very hard to find the right version of C-Gate to download so any tips would be great. I have an old 2.11 version running on a Raspberry Pi but I want to shut that down and run on a HA Green so your tool looks to be the answer.
It looks to be installing OK in managed mode when I upload the zip file but it just loops when I run it, with this in the logs:
[22:03:13] INFO: Starting C-Gate server…
[22:03:13] INFO: Command port: 20023
[22:03:13] INFO: Event port: 20025
usage: java -jar [JAVA_OPTIONS] CGate.jar [OPTIONS]
-c,–config specify config file to use
-h,–help prints this message
-pv,–patchversion prints the patch version
-s,–servermode ignores shutdown attempts
[22:03:13] WARNING: C-Gate exited with code 1, will restart
Thanks so much for taking the time to report this - you found a real bug, and your logs were exactly what I needed to diagnose it.
What was happening
The startup loop was caused by our addon passing command-line flags to C-Gate that don’t exist in C-Gate 3.x. We were starting it like this:
java -jar cgate.jar -p 20023 -e 20025 -nogui
Those flags (-p, -e, -nogui) are invalid in C-Gate 3, which is why it immediately printed its usage message and exited with code 1 - causing s6 to restart it in a
loop. In C-Gate 3.x the ports are configured via a config file, not command-line arguments.
What I fixed
I’ve released v1.4.15 which includes:
C-Gate now starts correctly using the -s (server mode) flag only
Ports are written into C-GateConfig.txt during installation so custom port settings are respected
The default download URL has been updated - the old Clipsal CDN is dead, I now point to the current Schneider Electric download server which hosts C-Gate 3.3.2
publicly (no login required)
The installer now handles Schneider’s nested zip format automatically (the download is a zip-within-a-zip, which was also causing failures in download mode)
Download failures now log the HTTP status code and give clearer guidance if the URL stops working in future
How to update
If you’re on a Home Assistant Green or any HA Supervisor install, the update should appear in your add-on store automatically. Just update to v1.4.15 and restart the
addon.
Since you were using upload mode with your own zip, that will continue to work - you shouldn’t need to change anything about your setup. The fix applies to both
upload and download mode.
Let me know if you hit any further issues - and thanks again for the detailed report, it made this much easier to track down.
Thanks Doug. That definitely fixed it. I can get CGate Running locally now. I was on cgate 2 also… so have to upgrade to cgate 3.5 (and so deal with the pain of migrating project files)… I think I am getting closer. MQTT still not recognising anything but I can see the events when I listen.
I have auto-discovery of your MQTT set up, but if you’ve got a remote MQTT set up, or some other form of auth you might be seeing some issues I havent uncovered. Feel free to DM me or email me some logs if you get stuck and i’ll see if that helps me address the mqtt issue.
I have only just managed to get back to this and for the life of me I can’t seem to get the MQTT Auto Discovery working, ie. I can’t find the c-bus lights in the devices.
I’m not sure if it is a limit in my knowledge of where to be looking to find the devices OR if I have the C-Gate Web plug-in setup wrong.
What I know:
The local C-Gate service is setup and can acces the c-gate network
Events (like lights on/off) are being recieved and are being published to MQTT. I can see that from the MQTT Settings page (if I listen to a topic).
I can turn lights on and off from the MQTT settings page by publishing a command, eg. cbus/write/254/56/17/switch → ON
I have installed the Mosquitto broker for MQTT.
I have been looking for the C-Bus lights in the Devices page on HA at /Settings → Devices & Services → Devices Tab (is that where I should be expecting to see them?)
I have loaded labels into the C-Gate Web app and in the Web UI I can see the live events for lights coming on and off.
Any help would be greatly appreciated!
Here is some logs from a restart of the C-Gate Web app (debug mode on)
[19:31:04] INFO: Waiting for C-Gate to be ready on port 20023...
[19:31:04] INFO: Starting C-Gate Web Bridge...
[19:31:04] INFO: Starting C-Gate server...
[19:31:04] INFO: Command port: 20023
[19:31:04] INFO: Event port: 20025
[19:31:04] INFO: C-Gate mode: managed
[19:31:04] INFO: Managed mode: C-Gate and cgateweb will be started via s6 services
Schneider Electric C-Gate(TM) v3.5.0 (build 2119)
Error in configuration file: Invalid key : CommandInterface.port
Error in configuration file: Invalid key : EventInterface.port
[19:31:06] INFO: C-Gate is ready
[19:31:06] INFO: Starting C-Gate Web Bridge application...
2026-05-04T09:31:07.802Z INFO [HAIntegration] Detected Home Assistant addon environment
INFO [HAIntegration] Optimized logging for Home Assistant addon environment
INFO [HAIntegration] Home Assistant optimizations applied: logging
DEBUG [EnvironmentDetector] Detecting installation environment...
DEBUG [EnvironmentDetector] Home Assistant indicators check:
{
"isAddon": true,
"optionsPath": "/data/options.json",
"dataPath": "/data",
"configPath": "/config",
"supervisorToken": "4b9b8be1c4ed67f58468576e5ee64ae6c10322c5376f3b56b35de56dd2df294ee1b3c890597b9523cb45ad45ec5dd0c3c5f299c1668431a3",
"hasOptionsFile": true,
"hasDataDirectory": true,
"hasConfigDirectory": true,
"hasSupervisorToken": true,
"hasIngress": false
}
INFO [EnvironmentDetector] Detected Home Assistant addon environment
INFO [ConfigLoader] Loading configuration for addon environment
DEBUG [ConfigLoader] Loaded addon options from:
"/data/options.json"
INFO [ConfigLoader] Auto-detected label file: /config/cgateweb-labels.json
DEBUG [ConfigLoader] Configuration loaded successfully
[INFO] Environment: addon
[INFO] Home Assistant optimizations: logging
[INFO] Configuration loaded from: addon
[INFO] Starting cgateweb...
[INFO] Version: 1.8.0
INFO [ConfigLoader] Auto-detected MQTT configuration from Supervisor API
INFO [ConfigLoader] Applied auto-detected MQTT username
INFO [ConfigLoader] Applied auto-detected MQTT password
INFO [ConfigLoader] Applied auto-detected MQTT broker: core-mosquitto:1883
INFO [ConfigLoader] Configuration validation passed
INFO [CgateConnectionPool-command] Initializing connection pool: 3 connections to 127.0.0.1:20023
INFO [LabelLoader] Loaded 34 labels from /config/cgateweb-labels.json (source: 12LESLIE.xml)
WARN [WebServer] Web API key not configured; mutating endpoints are unauthenticated due to explicit override.
INFO [bridge] Starting cgateweb bridge
WARN [MqttManager] Cannot publish to MQTT: not connected (further drops suppressed until reconnect)
INFO [WebServer] Web server listening on 0.0.0.0:8080
INFO [connection-manager] Starting all connections
INFO [MqttManager] Connecting to MQTT Broker: mqtt://core-mosquitto:1883
Logging to file: logs/event.txt
20260504-193108.367 800 cgate - C-Gate started.
20260504-193108.396 803 cmd3 - Host:/127.0.0.1 opened command interface from port: 53712
INFO [CgateConnectionPool-command] Starting connection pool with 3 connections
INFO [CgateConnection-command] Connecting to C-Gate command port: 127.0.0.1:20023
INFO [CgateConnection-command] Connecting to C-Gate command port: 127.0.0.1:20023
INFO [CgateConnection-command] Connecting to C-Gate command port: 127.0.0.1:20023
INFO [CgateConnection-command] CONNECTED TO C-GATE COMMAND PORT: 127.0.0.1:20023
INFO [CgateConnection-command] C-Gate Sent: EVENT ON
INFO [CgateConnectionPool-command] Pool connection 0 established
INFO [CgateConnection-command] CONNECTED TO C-GATE COMMAND PORT: 127.0.0.1:20023
INFO [CgateConnection-command] C-Gate Sent: EVENT ON
INFO [CgateConnectionPool-command] Pool connection 1 established
INFO [CgateConnection-command] CONNECTED TO C-GATE COMMAND PORT: 127.0.0.1:20023
INFO [CgateConnection-command] C-Gate Sent: EVENT ON
INFO [CgateConnectionPool-command] Pool connection 2 established
INFO [CgateConnectionPool-command] Connection pool started: 3/3 connections healthy
INFO [CgateConnectionPool-command] Health monitoring started: checking every 30000ms
INFO [CgateConnectionPool-command] Keep-alive started: pinging every 60000ms
INFO [connection-manager] Command connection pool started
INFO [CgateConnection-event] Connecting to C-Gate event port: 127.0.0.1:20025
[INFO] cgateweb started successfully (booting)
DEBUG [bridge] C-Gate Recv (Cmd): 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] Skipping non-response line: 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] C-Gate Recv (Cmd): 200 OK.
DEBUG [bridge] C-Gate info 200: OK.
DEBUG [bridge] C-Gate Recv (Cmd): 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] Skipping non-response line: 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] C-Gate Recv (Cmd): 200 OK.
DEBUG [bridge] C-Gate info 200: OK.
DEBUG [bridge] C-Gate Recv (Cmd): 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] Skipping non-response line: 201 Service ready: Schneider Electric C-Gate Version: v3.5.0 (build 2119) #cmd-syntax=1.0
DEBUG [bridge] C-Gate Recv (Cmd): 200 OK.
DEBUG [bridge] C-Gate info 200: OK.
INFO [CgateConnection-event] CONNECTED TO C-GATE EVENT PORT: 127.0.0.1:20025
DEBUG [CgateConnection-event] Event keep-alive started: pinging every 60000ms
INFO [connection-manager] Event connection connected
C-Gate is running.
INFO [MqttManager] CONNECTED TO MQTT BROKER: core-mosquitto:1883
INFO [MqttManager] MQTT reconnected; 38 publish(es) were dropped while disconnected
INFO [connection-manager] MQTT connected
INFO [connection-manager] ALL CONNECTED
INFO [connection-manager] Connection Successful: MQTT (core-mosquitto:1883), C-Gate (127.0.0.1:20023,20025). Awaiting messages...
INFO [bridge] ALL CONNECTED - Initializing services...
INFO [bridge] Getting all initial values for networks: 254/56...
INFO [LabelLoader] Watching label file for changes: /config/cgateweb-labels.json
INFO [HaDiscovery] HA Discovery enabled, querying network trees...
INFO [HaDiscovery] Requesting TreeXML for network 254...
INFO [MqttManager] Bridge readiness changed: Online (all-connected)
INFO [BridgeInitializationService] --- Startup Summary ---
INFO [BridgeInitializationService] C-Gate: 127.0.0.1:20023 (pool: 3), event port: 20025
INFO [BridgeInitializationService] MQTT: core-mosquitto:1883 (authenticated)
INFO [BridgeInitializationService] Networks: 254 (configured)
INFO [BridgeInitializationService] Features: HA Discovery, Bridge Diagnostics, Stale Device Detection, Get-All on Start
INFO [BridgeInitializationService] Labels: 34 custom labels loaded
INFO [BridgeInitializationService] Web UI: http://0.0.0.0:8080/
INFO [BridgeInitializationService] --- Ready ---
DEBUG [bridge] C-Gate Recv (Cmd): 401 Bad object or device ID: //12LESLIE/254/56/* (Network not found)
WARN [bridge] C-Gate Command Error 401: (Object Not Found or Unauthorized) - Bad object or device ID: //12LESLIE/254/56/* (Network not found)
INFO [MqttManager] Subscribed to MQTT topic: cbus/write/#
DEBUG [MqttManager] Ignoring retained write command on reconnect: cbus/write/254/56/17/level
DEBUG [MqttManager] Ignoring retained write command on reconnect: cbus/write/254/56/17/switch
DEBUG [bridge] C-Gate Recv (Cmd): 401 Bad object or device ID: Network not found
WARN [bridge] C-Gate Command Error 401: (Object Not Found or Unauthorized) - Bad object or device ID: Network not found
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] Skipping non-response line: 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] Skipping non-response line: 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] Skipping non-response line: 20260504-193110.421 751 //12LESLIE - Tag information changed at tag address: //12LESLIE/Installation oldtag: null newtag: null
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] Skipping non-response line: 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] Skipping non-response line: 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] Skipping non-response line: 20260504-193110.569 742 //12LESLIE/254 c2211b00-28c1-103f-94b5-db702a32859b Network created type=cni address=192.168.0.100:10001
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] Skipping non-response line: 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] Skipping non-response line: 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] Skipping non-response line: 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] Skipping non-response line: 20260504-193113.555 999 XmlToSqlTransformJob - The job has started.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] Skipping non-response line: 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] Skipping non-response line: 20260504-193113.559 999 XmlToSqlTransformJob - The job has ended.
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
DEBUG [bridge] Skipping non-response line: 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
DEBUG [bridge] Skipping non-response line: 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
DEBUG [bridge] C-Gate Recv (Cmd): 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
DEBUG [bridge] Skipping non-response line: 20260504-193120.394 836 //12LESLIE/254/p/12 c21ed110-28c1-103f-94ec-db702a32859b unit configuration changed (5 changes)
Yes, Settings → Devices & Services → Devices is the right place to look — the issue was that cgateweb was never publishing the discovery messages that put your lights there.
I’ve pushed a fix that auto-retries the discovery query with exponential backoff (2s, 4s, 8s, 16s…) when C-Gate returns “Network not found” or doesn’t respond.
By the second or third retry C-Gate will have finished loading and the lights will populate in HA automatically — no restart needed.
The fix will be in v1.8.1 which I’ll release shortly. Once your add-on updates to that version, you should see all 34 of your labelled devices show up in HA.
If they don’t, watch the add-on log for HA Discovery completed for network 254. Published N entities — that’s the success signal. If you ever want to force a
re-discovery without restarting, publish anything (e.g. 1) to cbus/write/254///gettree.
You nailed it Doug. 1.8.1 hasn’t yet come through on my HA (i’m sure it will soon) but I published to cbus/write/254///gettree and everything was instantly discovered!
I am very grateful for your rapid response. Very impressive.
@benlaughlin you might need to refresh your HACs list to get the latest version. I also added a few fixes to the latest release based on your logs to improve performance for large cgate installs.
Hi! Thanks for the report — that's a real bug, not a configuration issue on your end. Sorry about that.
What's happening: when the add-on runs in managed mode (where the add-on installs and runs C-Gate itself) and you haven't overridden the download URL, the install script was reading the unset URL field as the literal string "null" instead of empty, which prevented the default Schneider download URL from being applied. The URL-scheme check then quite reasonably rejected "null". Fixed in 1.8.8.
Quick clarification on mode — the add-on has two options:
remote — connect to a C-Gate server you're running yourself elsewhere on your network (most common setup; you supply C-Gate's IP in cgate_host).
managed — the add-on downloads, installs and runs C-Gate locally inside the container.
There isn't a "manual" mode per se — when you mention you "configured for manual mode", do you mean you want the add-on to manage C-Gate for you (use managed) or that you're running C-Gate elsewhere and want to point at it (use remote)? That'll change which fix unblocks you:
If managed: update to 1.8.8 once it's out and it should just work. As an immediate workaround on 1.8.7 you can also explicitly set cgate_download_url to https://download.se.com/files?p_Doc_Ref=C-Gate_3_Linux_Package_V3.3.2 in the add-on config — the bug only triggers when the field is empty.
If remote: switch cgate_mode from managed to remote in the add-on config and set cgate_host to your C-Gate server's IP. The install error will go away because the install path is skipped entirely.
Let me know which you're aiming for and I'll help you get the rest of the way there.
Hi. Firstly, thank you for making this! I'd been using a different plugin, but decided to nuke my HA setup and start from scratch again with this plugin instead as I really need the HVAC support. I've got everything running and I can see some stuff appearing in HA listed as Cbus units, and clicking on them does make them come on/off and dim correctly, but even the thermostats and shutter relays are appearing as lights.
Also, when I try to import a .cbz file from Toolkit, I get an error saying Failed Unauthorised. Is this because I'm using C-Gate3 and the formats have changed?
You can set the type of entity through the web interface. If you’re able to email me your .cbz file, I can take a look and see what’s going on - you can send it to doug @ dougrathbone.com
I have taken a look and found a few small bugs, but im unsure if they are related to your issue:
Hi @dougrathbone, I've been using a different plug in and came across yours ... just wondering if a lighting scene is activated on a input unit on the cbus side, is that exposed through your plugin or just the state changes of all the groups involved in the scene?
Hi Doug,
I just came across this today and it looks like just what I need to get rid of a PC which only exists to run CGate, replacing it with “managed” running on my Home Assistant Green. The install and configuration is really easy (thank you) and the documentation is great.
However, I have a challenge or two. The log is here and the CBZ is here.
The first challenge seems to be that the download of CGATE appears to be failing.
The second challenge is that my project file isn’t being found. I did update CBUS Toolkit before I started, to make sure I had the latest version of CGATE. Interestingly though, I still have an XML file not a DB. I exported that to create a CBZ file which, from the documentation, should be ok. I wonder whether I have misinterpreted the location where the file has to go. I created a folder called share using File Editor which, I think ends up as homeassistant/share. Then cgate and then tag - and I dumped the CBZ in there:
