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

# Device Lifecycle

## Overview

This page describes the lifecycle states a device can be in after it has been linked to the Energy Hub, and which events or API behaviors are associated with state changes.

## States

### Connected

* The `isConnected` field in the general device data model indicates whether the vendor account is authenticated and device access is intact.
* If a vendor account becomes unauthenticated or access is otherwise lost, the device is disconnected.
* On a state change, the `CONNECT` or `DISCONNECT` event is emitted.

```mermaid theme={null}
flowchart TB
  Start[Device gets connected]
  Connected[Connected]
  Disconnected[Disconnected]

  Start --> Connected
  ConnectMsg[CONNECT Event]
  Start -.-> ConnectMsg

  Connected -- Device Authentication Expires --> Disconnected
  DisconnectMsg[DISCONNECT Event]
  Disconnected -.-> DisconnectMsg

  %% Emphasize event boxes (secondary color outline only)
  classDef event fill:transparent,stroke:#00FF7F,stroke-width:2px;
  %% Style state boxes with primary color outline
  classDef state fill:transparent,stroke:#871FFF,stroke-width:2px;
  class Connected,Disconnected state;
  class ConnectMsg,DisconnectMsg event;
```

<Warning>
  This state is not recoverable automatically; it requires end‑user or partner
  intervention.
</Warning>

When a `DISCONNECT` event is received, the connected state **is not auto‑recoverable**. The device **has to be is reconnected by the end‑user** via the standard connect flow: prompt the user to restart the connect session for this device type and complete vendor authentication.

The Energy Hub cannot recover disconnected states by itself and does not delete devices automatically. To avoid billing of disconnected devices, devices must be reconnected or deleted by the partner.

### Online

* The `isOnline` field indicates whether the device is currently reachable for updating state parameters.
* A device can remain authenticated (connected) yet be temporarily unreachable due to connectivity issues, vendor throttling, or geofencing.
* Offline detection can take up to 24 hours for some devices.
* A device is considered online even if only a subset of parameters can be refreshed. If no parameters can be updated, `isOnline` becomes `false` within 24 hours.
* The `isOnline` state recovers automatically when reachability returns; no user or partner action is required.
* When `isOnline` changes, the change is communicated as part of the device "update" method (state update events/streams).

```mermaid theme={null}
flowchart TB
  Online[Online]
  NoOnline[No Online]

  Online <-->|Device Reachable| NoOnline

  UpdateMsg[UPDATE Event]
  Online -.-> UpdateMsg
  NoOnline -.-> UpdateMsg

  %% Emphasize event box (secondary color outline only)
  classDef event fill:transparent,stroke:#00FF7F,stroke-width:2px;
  %% Style state boxes with primary color outline
  classDef state fill:transparent,stroke:#871FFF,stroke-width:2px;
  class Online,NoOnline state;
  class UpdateMsg event;
```

### Deleted

* The Energy Hub does not delete devices autonomously.
* Device deletion is initiated by the partner.
* When a partner deletes a device, deletion is confirmed via the `DELETED` event.

```mermaid theme={null}
flowchart TB
  Start[Partner deletes device]
  Deleted[Deleted]

  Start --> Deleted

  DeleteMsg[DELETE Event]
  Deleted -.-> DeleteMsg

  %% Emphasize event box (secondary color outline only)
  classDef event fill:transparent,stroke:#00FF7F,stroke-width:2px;
  %% Style state boxes with primary color outline
  classDef state fill:transparent,stroke:#871FFF,stroke-width:2px;
  class Deleted state;
  class DeleteMsg event;
```