# Connection

TypeScript source: `hooks/connection.ts`

## Types

### ConnectionData

Source: `hooks/connection.ts:77`

State and actions exposed by the DepthAI connection hook and provider.

#### Members

| Name | Type | Description |
| --- | --- | --- |
| `connected` | `boolean` | Whether the underlying DepthAI connection is currently open.<br />Remarks: This becomes `false` during
reconnect, close, or disconnect handling before derived state such as topics and pipeline data is requested again. |
| `connections` | `VisualizerConnection[]` | Visualizer connections consumed by Foxglove-derived panels.<br />Remarks: The array
is empty until the underlying connection exposes a visualizer connection. |
| `daiConnection` | `DAIConnection | null` | Active DepthAI connection instance, or `null` before connection or after cleanup. |
| `fullPipeline` | `Pipeline | null | undefined` | Parsed full pipeline graph.<br />Remarks: `undefined` means the full pipeline
has not been requested or was reset during reconnect. `null` means the backend returned no full pipeline. |
| `isConnectionError` | `boolean` | Whether the connection failed in a Viewer-specific flow. |
| `isPipelineLoading` | `boolean` | Whether pipeline data is currently loading. |
| `pipeline` | `Pipeline | null | undefined` | Parsed default pipeline graph.<br />Remarks: `undefined` means the pipeline has not
been requested or was reset during reconnect. `null` means the backend returned no default pipeline. |
| `pipelineState` | `PipelineState[] | null | undefined` | Live pipeline node state.<br />Remarks: `undefined` is the initial
provider placeholder value. The hook resets this to `null` during reconnect, close, and disconnect, and later replaces it when
live state arrives from the backend. |
| `setIsPipelineLoading` | `(isLoading: boolean) => void` | Updates the pipeline loading state. |
| `toggleTopic` | `(topic: string) => void` | Toggles subscription for a stream topic.<br />Remarks: Fake topics are toggled
locally. Point cloud topics also toggle the shared point cloud color topic so image data is available for coloring. |
| `topics` | `Topic[]` | Stream topics currently reported by the backend plus any configured fake topics.<br />Remarks: The list
is cleared when the connection reconnects, closes, or disconnects. |
| `topicsLoading` | `boolean` | Whether stream topics are currently loading. |
| `unsupportedTopics` | `string[]` | Topic names that the visualizer cannot render.<br />Remarks: Values are appended after
deserialization reports unsupported encoded streams. |

### TokenRefreshHandler

Source: `hooks/connection.ts:31`

```ts
(newToken: string) => void | boolean
```

Token refresh behavior used by WebRTC connections.

#### Remarks

Pass `true` to write refreshed tokens back to the URL, pass a callback to handle them in the host application, or pass `false` to
disable automatic propagation.

### Topic

Source: `hooks/connection.ts:36`

Stream topic advertised by a DepthAI pipeline and shown in stream controls.

#### Members

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `annotations` | `string[]` | `[]` | Annotation topics rendered together with this topic. |
| `enabled` | `boolean` | | Whether the stream is currently subscribed in the active connection.<br />Remarks: Fake topics update
this flag locally; backend topics are toggled through the connection. |
| `extraAnnotations` | `string[]` | `[]` | Annotation topics from sibling groups that can be attached to this topic. |
| `kind` | `"pointCloud" | "image" | "imu" | "rgbd"` |  | Stream payload kind used by the visualizer renderer. |
| `name` | `string` |  | Backend topic name used for subscribe/unsubscribe calls. |
| `parent?` | `string` | | Parent topic used when this synthetic topic is derived from another stream.<br />Remarks: `undefined`
means the topic is a backend topic or a standalone fake topic. |

### UseCreateConnectionArgs

Source: `hooks/connection.ts:165`

Arguments for creating and maintaining a DepthAI connection from React state.

#### Members

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `activeServices` | `DAIService[]` | `[]` | DepthAI service names to poll while connected. |
| `clientId` | `string` |  | WebRTC client id.<br />Remarks: Use an empty string for WebSocket connections. |
| `connectionUrl` | `string` | | WebSocket URL or signaling endpoint used by the connection.<br />Remarks: For `ws`, this is the
backend WebSocket URL. For `webrtc`, it is passed to the connection initializer together with `token` and `clientId`. |
| `defaultTopics?` | `string[]` | | Stream topics opened automatically after connection.<br />Remarks: `undefined` leaves topic
selection to the backend/default connection behavior. |
| `fakeTopics?` | `Topic[]` | `[]` | Synthetic topics merged into the backend topic list.<br />Remarks: Fake topics are useful
when the host wants to expose derived views that are not directly advertised by the backend. |
| `isViewer?` | `boolean` | `false` | Enables Viewer-specific error handling and default stream behavior.<br />Remarks: When
enabled, disconnects show the Viewer-specific toast and set `isConnectionError` to `true`. |
| `messageHandlerVersion?` | `MessageHandlerVersion` | | Backend message handling protocol expected by the visualizer connection.
|
| `onNewConnection?` | `(connection: DAIConnection) => void` | | Called after a new `DAIConnection` instance is created and before
it is initialized.<br />Remarks: The callback can attach host-specific listeners. It may run more than once when connection
parameters change or the hook reconnects. |
| `token` | `string` |  | WebRTC auth token.<br />Remarks: Use an empty string for WebSocket connections. |
| `tokenRefresh?` | `TokenRefreshHandler` | `false` | Controls WebRTC token refresh propagation. |
| `type` | `"webrtc" | "ws"` |  | Connection transport used by the DepthAI backend. |
| `withDebugLogs?` | `boolean` | `false` | Enables verbose connection logging. |

## Functions

### useCreateConnection

Source: `hooks/connection.ts:273`

```ts
(__namedParameters: UseCreateConnectionArgs) => ConnectionData
```

Creates a managed DepthAI connection and exposes connection state for React components.

#### Remarks

The hook creates and initializes `DAIConnection`, subscribes to connection events, resets topics/pipeline state during reconnect
or disconnect, updates active service polling when `activeServices` changes, and forwards key presses to the active connection
while connected. Viewer WebRTC connections also receive session recovery settings backed by the latest refreshed token. It also
clears pending reconnect timers on unmount.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `__namedParameters` | `UseCreateConnectionArgs` |  |

#### Example

```ts
const connection = useCreateConnection({
	type: 'ws',
	connectionUrl: 'ws://localhost:8765',
	token: '',
	clientId: '',
	activeServices: [],
});
```