ZenControl

Connect ZenControl to KODE OS for lighting data integration

Overview

Use this integration to connect a ZenControl site to KODE OS. KODE OS discovers gateways, control gear, and application controllers, polls status, and receives live dim, scene, colour, and override events.

Property	Value
System Type	Lighting
Communication	REST and WebSocket (Live API)
Collection	Pull and live stream
Collection Mode	SNAPSHOT

Supported capabilities

Discover devices and points
Collect sensor data
Receive WebSocket (live) data
Write dim level, scene, colour temperature, and override

Prerequisites

A ZenControl cloud account with API access
The API URL, authorization URL, client ID, client secret, and user code
The Live API enabled for the site
KODE OS access to Data Sources

Configure the connector in KODE OS

Open Data Sources for your building.
Select API Catalog, then search for ZenControl.
Select + Add Datasource.
Complete the connector fields, then validate credentials so KODE OS can load sites.

Field	Required	Type	Description
Name	Yes	text	Name that identifies this connection in KODE OS
Area	No	object	Area associated with the connection
URL	Yes	text	ZenControl API base URL
Auth URL	Yes	text	URL used to request and refresh the access token
Client ID	Yes	text	OAuth client identifier
Client Secret	Yes	password	OAuth client secret
User Code	Yes	password	One-time user code for the first token
Site ID	Yes	dropdown or text	Site to collect. Options load after credentials validate. The field is a text box when no sites are returned.
Notes	No	text	Additional connection details

Site ID shows the site name and stores the site identifier. KODE OS reuses a valid token and refreshes it before it expires.

Discover devices and points

After you save the connector, select Discover. Review the returned devices and points, then save the records you want in KODE OS. Every device uses the lighting canonical type. For more details, see the Discovery guide.

Devices and points

Gateway

A gateway is not polled. Its points arrive on the Live API gateway connection stream.

Point	Description	Unit	Writable	Ontology field	Collection
`isConnected`	Whether the gateway is connected. Values are `Inactive` and `Active`.	—	No	`connection_status`	`event.gateway.connection-status`
`lastConnected`	Last connected time in the building time zone	—	No	—	`event.gateway.connection-status`
`lastCommunicated`	Last communicated time in the building time zone	—	No	—	`event.gateway.connection-status`

ECG (control gear)

status is polled. The other points arrive as live events. arcLevel, scene, and override are writable. colourTemp is writable only when the gear supports colour control.

Point	Description	Unit	Writable	Ontology field	Collection
`status`	Online or offline state. Values are `Inactive` and `Active`.	—	No	`connection_status`	REST poll
`arcLevel`	Dim level as a percent, from 0 to 100	%	Yes	`run_percentage_command`	`event.ecg.arc-level`
`scene`	Last-heard scene, from 0 to 15	—	Yes	`scene_command`	`event.ecg.scene-change`
`colourTemp`	Colour temperature number from the Live API	—	Conditional	—	`event.ecg.colour-temp`
`override`	Active override labels, or `None`	—	Yes	—	`event.ecg.override-change`

ECD (application controller)

Both points use a REST poll. A missing operating mode is collected as down.

Point	Description	Unit	Writable	Ontology field	Collection
`status`	Online or offline state. Values are `Inactive` and `Active`.	—	No	`connection_status`	REST poll
`operatingMode`	Numeric operating mode	—	No	`device_mode`	REST poll

What data you get

Point history

REST polls refresh status and operatingMode. Live events refresh dim level, scene, colour temperature, override, and gateway connection. KODE OS stores arcLevel as a percent. A write converts that percent to a DALI arc level from 0 to 254.

Polling schedule

Point history — Default polling: 15 minutes (min: 15 minutes, max: 1 hour)

Live WebSocket events do not use that poll interval. For more details, see the Data collection guide.

Available actions

Write actions are available on the writable ECG points.

Point	Field	Required	Input	Options / default
`arcLevel`	`Level (%)`	Yes	Number	Current value. Range 0 to 100.
`scene`	`Scene`	Yes	Drop down	`Scene 0` through `Scene 15`
`colourTemp`	`Colour temperature`	Yes	Number	Kelvin. KODE OS converts the value before sending it.
`override`	`Override`	Yes	Drop down	Lux, PIR, Colour, Intensity, Switch, Inhibit without switch, Inhibit with switch
`override`	`Duration`	Yes	Duration	Includes a permanent duration

colourTemp can be written only on gear discovered as colour control. Other gear does not accept the command.

Use cases

Once connected, you can:

See dim level and the latest scene on each control gear
Check gateway and device connection status
Set a scene, dim level, colour temperature, or timed override from KODE OS

Troubleshooting

Authentication or connection error

Confirm the API URL, Auth URL, client ID, and client secret. A used, expired, or mismatched user code must be replaced before the first token can be issued.

No live events arriving

Confirm that the Live API is enabled for the site and that the connector is up. Dim level, scene, colour temperature, and override arrive only over the WebSocket.

Discovery returns no devices

Confirm that the credentials can list the selected site. Run Discover again after the connection test succeeds.

Colour temperature write is rejected

Only colour-control gear has a writable colourTemp point. Enter the value in Kelvin.

Get Started

Capabilities

All Integrations

Reference

Overview

Supported capabilities

Prerequisites

Configure the connector in KODE OS

Discover devices and points

Devices and points

Gateway

ECG (control gear)

ECD (application controller)

What data you get

Point history

Polling schedule

Available actions

Use cases

Troubleshooting

​Overview

​Supported capabilities

​Prerequisites

​Configure the connector in KODE OS

​Discover devices and points

​Devices and points

​Gateway

​ECG (control gear)

​ECD (application controller)

​What data you get

​Point history

​Polling schedule

​Available actions

​Use cases

​Troubleshooting

Overview

Supported capabilities

Prerequisites

Configure the connector in KODE OS

Discover devices and points

Devices and points

Gateway

ECG (control gear)

ECD (application controller)

What data you get

Point history

Polling schedule

Available actions

Use cases

Troubleshooting