> ## 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 automatically find and register all available entities -- devices, data points, schedules, and assets -- without requiring manual configuration for each individual item.

## How Discovery Works

When you run discovery on a connector, KODE OS queries the external system's API to retrieve a list of all available entities. The discovery process follows this flow:

```mermaid theme={null}
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's 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 a physical piece of hardware or a logical grouping in the external system -- a thermostat, a sensor hub, a door controller, a meter, or a camera.

Each discovered device includes:

| Field           | Description                                                |
| --------------- | ---------------------------------------------------------- |
| **External ID** | The unique identifier of the device in the external system |
| **Name**        | The device name as reported by the external system         |
| **Type**        | The 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 associated with a device. For a thermostat, points might include current temperature, setpoint, humidity, and operating mode.

Each discovered point includes:

| Field           | Description                                               |
| --------------- | --------------------------------------------------------- |
| **External ID** | The unique identifier of the point in the external system |
| **Name**        | The point name as reported by the external system         |
| **Unit**        | The unit of measurement (e.g., °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 (e.g., Niagara, Distech), KODE OS can discover existing schedules configured in the external system. Discovered schedules include their name, type (weekly or calendar), current values, and linked point references.

See the [Schedules guide](/products/integrations/capabilities/schedules) for more details on schedule types and management.

### Assets

Assets are physical or virtual objects that KODE OS tracks for metadata purposes -- 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 requiring metadata tracking

## Running Discovery

### Step 1 -- Navigate to the Connector

Go to **Data Sources** in your building, then select the connector you want to discover from.

### Step 2 -- Start Discovery

Click the **Discover** button on the connector detail page. KODE OS authenticates with the external system and begins querying for available entities.

### Step 3 -- Review Results

The discovery results are presented in a list showing all found devices and their associated points. Each item shows:

* Device/point name
* External system identifier
* Type and category
* Whether it's new or already registered

### Step 4 -- Select and Register

Select the devices and points you want to register in KODE OS. You can select individual items or use "Select All" for bulk registration. Once registered, these devices and points become available for data collection across the platform.

## Discovery Behavior by Protocol

How discovery works depends on the communication protocol used by the integration:

| Protocol            | Discovery Method                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| **REST / SOAP**     | KODE OS calls the vendor's list/query endpoints to enumerate devices and points                   |
| **Modbus / BACnet** | KODE OS scans the network or queries the controller's object list for available points            |
| **MQTT**            | Discovery is typically not available -- devices register themselves 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** are shown as available for registration
* **Existing items** are shown 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 the discovery times out, try narrowing the scope by configuring a specific folder, site, or building filter in the connector settings (if 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 navigate to the device detail page to see its individual points. Also verify that the external system's API exposes point-level data.
  </Accordion>
</AccordionGroup>