Clipsal C-Bus (C-Gate)

Drives Clipsal / Schneider Electric C-Bus groups through a C-Gate server. GEM holds two sockets open: the C-Gate command port for control, and the status-change port so wall-plate presses and other controllers show up as zone state without polling.

Driver name: clipsal_cbus

How it fits together

C-Bus itself is a two-wire field bus. GEM never talks to it directly — it talks to C-Gate, the Clipsal-supplied server process that owns the C-Bus network interface (CNI, PCI or USB PC interface) and exposes an ASCII control API over TCP.

Because C-Gate is the only thing that may own the bus interface, it usually lives on the same server as C-Bus Toolkit, or on a small always-on PC in the rack. GEM connects to it over the LAN.

C-Gate also listens on 20024, its own diagnostic event port. GEM does not use it, so nothing needs to be opened there.

Prerequisites

• A running C-Gate server, v2.9 or newer, with the site project loaded and started.
• The GEM server's IP address added to C-Gate's access control list. C-Gate has no password — it decides who may connect purely by source address, and an unlisted host is disconnected immediately after the banner.
• Network reachability from GEM to the C-Gate host on TCP 20023 and 20025.
• The C-Bus group addresses for each load, from the C-Bus Toolkit project. C-Gate can list the groups it sees on the bus, but which group is "Kitchen Downlights" is commissioning data that lives in Toolkit.

note

This driver does not need C-Bus Toolkit itself, only C-Gate. Toolkit and GEM can both be connected to C-Gate at the same time.

Setup steps

1. Whitelist GEM on the C-Gate host. Edit C-Gate's access control file (access.txt in the C-Gate config directory on a standard Windows install) and add a remote entry for the GEM server's IP. Restart the C-Gate service so the change takes effect.

2. Confirm the project is running. In C-Gate (or the C-Gate console) check that the project is both loaded and started, and note its name exactly — project names are case-sensitive.

3. Add the device. Go to Devices, add a device and pick the driver Clipsal C-Bus (C-Gate). The Device Attributes section then shows the driver's own fields. Under Connection, fill in C-Gate Host (the machine running C-Gate, not the CNI) and C-Gate Project. Both are required — with either one blank the device never opens a connection.

   Open Devices

   Two starter configurations are offered as Load sample: Single-network lighting site and Load sample: Multi-network commercial site buttons beside the Device Attributes heading; either one fills the fields in for you to edit.

4. Adjust the optional fields only if the site needs it. Click Show 7 optional attributes to reveal Command Port, Status Change Port, Default Network, Default Application, Default Ramp (seconds), Status Poll Interval (ms) and Command Throttle (ms). A standard single-network lighting site needs none of them changed.

5. Read the group numbers off the bus. Open Commands, choose the new device in Test Device, then use the Test Command button on the tree row. C-Gate returns the network tree in the Device Console panel below the grid, which is where the group numbers come from.

   Open Commands

6. Create the zones. One GEM zone per C-Bus group. In the zone editor's Device Assignment section pick the C-Bus device and put the group in Address. Assign each zone to the room it belongs to. GEM does not create these for you — tree reports what is on the bus, but the load-to-room mapping is yours.

   Open Zones

7. Verify. Back in Commands, run get_level against a zone address and confirm a level comes back in the Device Console, then toggle the load at the wall plate and confirm the zone state follows within a second or two — that proves the status-change socket is up.

tip

When you pick the driver, GEM selects a Command Set named clipsal_cbus, creating it if this is the first C-Bus device on site. The command rows themselves appear once the device loads. You do not need to add or edit any of them by hand.

Attribute reference

Device attributes

The Attribute column is the name stored on the device; the Field column is the label shown in the device editor.

Attribute	Field	Required	Default	Purpose
ip	C-Gate Host	yes	—	LAN address of the machine running C-Gate (not the CNI).
project	C-Gate Project	yes	—	C-Gate project name, exactly as spelled in C-Gate. Case-sensitive.
port	Command Port	no	20023	C-Gate interactive command port.
status_port	Status Change Port	no	20025	C-Gate status-change port. GEM opens a second, read-only socket here. Set to 0 to disable it and rely on the resync sweep alone.
network	Default Network	no	254	C-Bus network used when a zone address omits it.
application	Default Application	no	56	C-Bus application used when a zone address omits it. 56 is lighting.
default_ramp	Default Ramp (seconds)	no	0	Ramp time applied to set_level when the command carries no ramp. 0 is instant.
status_interval	Status Poll Interval (ms)	no	60000	Resync sweep — re-reads every configured zone's level. Values below 5000 are ignored and 60000 used instead.
command_throttle	Command Throttle (ms)	no	100	Minimum spacing between outgoing C-Gate command lines.

Zone attributes (written by the driver)

Zones need no attributes beyond Address. The driver writes these back as the bus reports:

Attribute	Meaning
level	Group level as 0–100 percent.
state	on whenever the level is above 0, otherwise off.

Zone address format

Three forms are accepted:

Form	Example	Meaning
Group only	1	Group 1 on the device's Default Network and Default Application.
Network / application / group	254/56/1	Fully qualified. Use this on multi-network sites or for non-lighting applications.
Full C-Gate path	//HOME/254/56/1	Fully qualified including project. The project in the path wins over the device's C-Gate Project.

Network, application and group must each be 0–255. Anything outside that, or a path form that isn't exactly //PROJECT/network/application/group, is rejected and the zone is skipped with a warning rather than driving a guess.

warning

A two-part address such as 254/1 is rejected. It could mean network/group or application/group, and guessing wrong drives the wrong load. Write it out in full instead.

Give each group exactly one zone. Two zones pointing at the same group — say one addressed 1 and another 254/56/1 — resolve to the same load, and only one of them picks up bus feedback.

Commands

Command	Arguments	Notes
on	address	Group to full on.
off	address	Group off.
set_level	address, level, ramp	level is 0–100 percent. ramp is seconds; omit it to use Default Ramp.
terminate_ramp	address	Stop an in-progress ramp and hold the current level.
get_level	address	Read the group's level. The reply updates zone state asynchronously.
get_zones	—	Lists the zones configured in GEM against this device and re-polls each. Use tree for what C-Gate actually sees on the bus.
tree	network	Dumps the C-Gate network tree. Omit network to use Default Network. Returns the raw response lines.
start_project	—	Issues PROJECT START for the configured project. Only needed if C-Gate has the project loaded but stopped.
raw_command	line	Sends an arbitrary C-Gate command line and returns whatever comes back in the next 1.5 s.

When a command runs against a zone, GEM fills address in from that zone's Address automatically — you only pass it by hand when testing from the Commands page.

tree, start_project and raw_command gather C-Gate's reply over a fixed listening window (3 seconds for the first two, 1.5 for raw_command) because C-Gate's multi-line replies have no end marker. Only one of them can be listening at a time; a second overlapping one returns another raw command is already collecting. Wait for the first to come back and run it again.

Levels and ramps

GEM works in percent everywhere; C-Bus works in a 0-255 byte. The driver converts in both directions, so set_level with 50 sends RAMP … 128 0s and a bus report of 128 shows in GEM as 50%.

Ramp times are taken as whole seconds and capped at 900. C-Bus ramp rates are also discrete — 0, 4, 8, 12, 20, 30, 40, 60, 90, 120, 180, 300, 420, 600 and 900 seconds — and C-Gate rounds whatever it is given to the nearest supported rate, so a request for a 5-second ramp actually runs at 4 seconds.

What GEM does on the connection

Worth knowing when you are watching the Device Console or chasing a comms problem:

• On connect, GEM reads the level of every zone configured against the device, spaced about 60 ms apart, so the UI starts out matching the building.
• That same sweep repeats on the Status Poll Interval. It is a safety net, not the main state channel — live changes arrive on the status-change socket within a second.
• An idle command connection is kept alive with a NOOP every 30 seconds; C-Gate answers 200 OK.
• If the status-change socket drops, GEM retries it every 10 seconds on its own. The command socket reconnects on its own schedule, backing off as failures repeat.
• Outgoing lines are spaced by Command Throttle so a burst of zone commands does not outrun C-Gate.

Known limitations

• No dimmer slider. The driver implements set_level, but the built-in Light Dimmer zone control sends a plain level command that this driver does not answer, so its slider will not move a C-Bus load. Use the Light Switch control for the on/off tile and drive levels from macros, triggers or scenes calling set_level.
• Only the lighting-style status lines are decoded. on, off and ramp update zone state. Measurement (application 228), trigger control (202) and enable control (203) traffic is logged but does not drive zones. Those groups can still be commanded by putting the application number in the zone address.
• No scene or trigger recall command. Trigger groups can be fired today with raw_command, but there is no first-class scene verb.
• No automatic project start on connect. Loading or starting a project on a live building is an operator decision, so it is exposed as an explicit command rather than a connect-time side effect.
• No C-Gate authentication. C-Gate does not offer any; access is IP-based on the C-Gate host.

Troubleshooting

Symptom	Check
Connection refused, or connects then drops instantly	The GEM server IP is not in C-Gate's access control list. Add it on the C-Gate host and restart C-Gate.
Device never attempts a connection at all	C-Gate Host or C-Gate Project is blank. Both are required before the driver will open a socket.
Every command returns a missing-project error	C-Gate Project is empty on the device. Fill it in and reload the device.
Commands return a 4xx code	The project name is misspelled, or the project is loaded but not started. Project names are case-sensitive. Run start_project once if it is merely stopped.
Commands work, state never updates	The status-change socket is not connected. Confirm TCP 20025 is reachable from GEM and that Status Change Port is not 0. Check the device log for cbus status socket connected.
One zone never updates but its neighbours do	Its Address does not parse, or two zones point at the same group. Check the device log for a skipped-address warning.
Levels jump to 100% or look scaled wrong	Something upstream is passing a raw C-Bus byte instead of percent. Pass 0-100 to set_level.
One group ignores commands	Wrong application. Loads outside lighting need the application in the address, e.g. 254/203/1.
Ramp time does not match what was asked	Expected — C-Bus rounds to its nearest supported discrete ramp rate.
tree or raw_command returns "already collecting"	Another one of them is still inside its listening window. Wait a few seconds and retry.

Related

• Zones
• Devices
• Commands
• Script Console