> ## Documentation Index > Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # ZenControl > Connect ZenControl to KODE OS for lighting status and live control events > 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 1. Open `Data Sources` for your building. 2. Select `API Catalog`, then search for `ZenControl`. 3. Select `+ Add Datasource`. 4. 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](https://docs.kodelabs.com/products/integrations/capabilities/discovery.md). ## 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](https://docs.kodelabs.com/products/integrations/capabilities/data-collection.md). ## 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 > [accordion] 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. > [accordion] 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. > [accordion] Discovery returns no devices > > Confirm that the credentials can list the selected site. Run `Discover` again after the connection test succeeds. > [accordion] Colour temperature write is rejected > > Only colour-control gear has a writable `colourTemp` point. Enter the value in Kelvin. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.