> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Harmonized interfaces

> Advertise machine-readable device capabilities that implementations can share across vendors and domains

Sensor fields and control parameters describe *how* to exchange values. A harmonized interface describes *what those values mean together*. It is a versioned capability contract that lets a client interoperate without product-specific knowledge.

| Item               | Value                                                   |
| ------------------ | ------------------------------------------------------- |
| Namespace          | `urn:nfi:iot:hi:1.0`                                    |
| Discovery request  | `<getInterfaces>` in `iq get`                           |
| Discovery response | `<interfaces>` containing `<interface ref="…">` entries |

## Interface identifiers

Each interface is a URI. Neuro-Foundation base interfaces use `urn:nfi:iot:hi:`; aggregate interfaces use `urn:nfi:iot:hia:`; shared enumeration definitions use `urn:nfi:iot:hie:`. The URI ends in a version, so compatibility is explicit.

```text theme={null}
urn:nfi:iot:hi:sensor:temperature:1.0
urn:nfi:iot:hia:statistics:average:1.0
urn:nfi:iot:hie:media:format:1.0
```

An interface defines mandatory behavior and optional extensions. If a device advertises an optional part, it must implement that part exactly as the interface defines it. Devices may still expose additional fields and controls outside the minimum contract.

Anyone controlling a domain can publish an interface in a namespace they own. Only Foundation-published interfaces use the `urn:nfi:` namespace.

## Discover capabilities

For a standalone device:

```xml theme={null}
<iq type='get' from='app@example.net/a1' to='device@example.org/d1' id='if-1'>
  <getInterfaces xmlns='urn:nfi:iot:hi:1.0'/>
</iq>
```

For a node behind a concentrator, add its extended address:

```xml theme={null}
<getInterfaces xmlns='urn:nfi:iot:hi:1.0'
               id='Station01'
               src='MeteringTopology'
               pt='north-campus'/>
```

The response lists supported URIs:

```xml theme={null}
<iq type='result' id='if-1'>
  <interfaces xmlns='urn:nfi:iot:hi:1.0'>
    <interface ref='urn:nfi:iot:hi:sensor:temperature:1.0'/>
    <interface ref='urn:nfi:iot:hi:identity:location:1.0'/>
    <interface ref='urn:nfi:iot:hi:identity:version:1.0'/>
  </interfaces>
</iq>
```

## Aggregate interfaces

Aggregates add generic behavior to a base interface without multiplying definitions. For example, a historical-statistics aggregate can extend temperature, humidity, or power sensors. The aggregate's version is explicit; the base version comes from the separately advertised base URI.

## Consumer rules

* Feature-detect every interface and version; never infer it from a model name.
* Require the base interface before applying one of its aggregates.
* Ignore unknown interface URIs while retaining them for diagnostics.
* Negotiate a version you understand; do not silently treat a future major version as compatible.
* Keep application policy separate from capability discovery. Support does not imply permission.