> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery

> Automatically find devices, points, schedules, and assets from connected systems

> Automatically find devices, points, schedules, and assets from your connected systems

Discovery is the process of querying a connected external system to find and register available entities — devices, data points, schedules, and assets — without configuring each item by hand.

## How discovery works

When you run discovery on a connector, KODE OS queries the external system's API for available entities.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A["User triggers discovery"] --> B["KODE OS authenticates with external system"]
    B --> C["Query external API for available entities"]
    C --> D["Parse and normalize discovered items"]
    D --> E["Present results to user"]
    E --> F["User selects items to register"]
    F --> G["Items saved to KODE OS"]
```

<Note>
  Not all integrations support discovery. Check the specific integration page to see if discovery is available. Integrations that only receive data via webhooks or MQTT typically do not have a discovery step.
</Note>

## What gets discovered

### Devices

A device represents physical hardware or a logical grouping in the external system — a thermostat, sensor hub, door controller, meter, or camera.

Each discovered device includes:

| Field           | Description                                             |
| --------------- | ------------------------------------------------------- |
| **External ID** | Unique identifier of the device in the external system  |
| **Name**        | Device name as reported by the external system          |
| **Type**        | Category or model of the device                         |
| **Location**    | Physical location metadata if available from the vendor |
| **Labels**      | Tags or categories from the external system             |

### Points

Points are the individual data values or control endpoints on a device. For a thermostat, points might include current temperature, setpoint, humidity, and operating mode.

Each discovered point includes:

| Field           | Description                                              |
| --------------- | -------------------------------------------------------- |
| **External ID** | Unique identifier of the point in the external system    |
| **Name**        | Point name as reported by the external system            |
| **Unit**        | Unit of measurement (for example, °C, %, kWh)            |
| **Type**        | Whether this is a sensor reading, a command, or a status |
| **Labels**      | Tags or categories from the external system              |

### Schedules

For integrations that support schedule management (for example, Niagara or Distech), KODE OS can discover schedules already configured in the external system. Discovered schedules include name, type (weekly or calendar), current values, and linked point references.

See the [Schedules guide](/products/integrations/capabilities/schedules).

### Assets

Assets are physical or virtual objects that KODE OS tracks for metadata. Unlike devices, they do not have time-series data points. Asset discovery is available for integrations that manage inventory-type data.

Examples of assets:

* Network equipment (routers, switches, servers)
* Furniture (desks, chairs, whiteboards)
* Safety equipment (fire extinguishers, AEDs)
* Any physical item that needs metadata tracking

## Running discovery

<Steps>
  <Step title="Open the connector">
    Go to `Data Sources` in your building, then select the connector you want to discover from.
  </Step>

  <Step title="Start discovery">
    Click `Discover` on the connector detail page. KODE OS authenticates with the external system and queries for available entities.
  </Step>

  <Step title="Review results">
    Discovery results list found devices and their points. Each item shows:

    * Device or point name
    * External system identifier
    * Type and category
    * Whether it is new or already registered
  </Step>

  <Step title="Select and register">
    Select the devices and points you want to register in Cloud BMS. You can select individual items or use Select All for bulk registration. Registered devices and points become available for data collection across the platform.
  </Step>
</Steps>

## Discovery behavior by protocol

| Protocol            | Discovery method                                                                      |
| ------------------- | ------------------------------------------------------------------------------------- |
| **REST / SOAP**     | KODE OS calls the vendor's list or query endpoints to enumerate devices and points    |
| **Modbus / BACnet** | KODE OS scans the network or queries the controller's object list                     |
| **MQTT**            | Discovery is typically not available — devices register by publishing to known topics |
| **Webhook**         | Discovery is typically not available — data arrives as push notifications             |
| **SDK**             | KODE OS uses the vendor's SDK methods to list available entities                      |

## Rediscovery

You can run discovery multiple times on the same connector. When you rediscover:

* **New items** appear as available for registration
* **Existing items** appear as already registered and can be updated
* **Removed items** (no longer found in the external system) are flagged for review

## Troubleshooting

<AccordionGroup>
  <Accordion title="Discovery returns no devices">
    Verify that the connector credentials have the correct permissions in the external system. Some vendor APIs require specific roles or scopes to list devices. Also check that the URL and authentication settings are correct by running a test connection first.
  </Accordion>

  <Accordion title="Discovery times out">
    Large systems with thousands of devices may take longer to discover. If discovery times out, try narrowing the scope by configuring a specific folder, site, or building filter in the connector settings when the integration supports it.
  </Accordion>

  <Accordion title="Discovered devices are missing points">
    Some integrations discover devices and points in separate steps. After registering devices, you may need to run discovery again or open the device detail page to see its points. Also verify that the external system's API exposes point-level data.
  </Accordion>
</AccordionGroup>