Pydiagral

https://mguyard.github.io/pydiagral
Admin
Pydiagral is an asynchronous Python library for controlling and monitoring Diagral alarm systems...
Tokens:58,573
Snippets:270
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start System

Source: https://mguyard.github.io/pydiagral/api

Asynchronously starts the system by calling the internal `__system_action` method with the 'start' parameter. This method requires proper authentication.

```python
async def start_system(self) -> SystemStatus:
    """Asynchronously starts the system.

    This method sends a request to start the system and returns the system status.

    Returns:
        SystemStatus: An instance of SystemStatus containing the system status after starting the system.

    Raises:
        ConfigurationError: If the action is not one of the allowed actions.
        AuthenticationError: If the API key, secret key, or PIN code is missing.

    """

    return await self.__system_action("start")
```

--------------------------------

### Start System API

Source: https://mguyard.github.io/pydiagral/api

Asynchronously starts the system.

```APIDOC
## POST /systems/{serial_id}/start

### Description
Asynchronously starts the system. This method sends a request to start the system and returns the system status.

### Method
POST

### Endpoint
/systems/{serial_id}/start

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the system.

#### Request Body
None

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the system status after starting the system.

#### Response Example
```json
{
  "status": "running",
  "message": "System started successfully."
}
```

### Errors
- **ConfigurationError**: If the action is not one of the allowed actions.
- **AuthenticationError**: If the API key, secret key, or PIN code is missing.
```

--------------------------------

### Partial Start System API

Source: https://mguyard.github.io/pydiagral/api

Initiates a partial start of the system with a specified ID.

```APIDOC
## POST /api/system/partial_start/{id}

### Description
Initiates a partial start of the system. The ID specifies the type of partial start.

### Method
POST

### Endpoint
/api/system/partial_start/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - The ID of the partial start. Must be either 1 or 2.

### Request Body
None

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the system status after performing the partial start.

#### Response Example
```json
{
  "status": "partial_start_1"
}
```

### Errors
- **ConfigurationError**: If the provided ID is not 1 or 2.
```

--------------------------------

### Initiate partial system start

Source: https://mguyard.github.io/pydiagral/api

Performs a partial start of the system using a specified ID, which must be 1 or 2.

```python
async def partial_start_system(self, id: int = 1) -> SystemStatus:  # NOT-TESTED
    """Initiate a partial start of the system.

    Args:
        id (int, optional): The ID of the partial start. Must be either 1 or 2. Defaults to 1.

    Returns:
        SystemStatus: An instance of SystemStatus containing the system status after performing the partial start.

    Raises:
        ConfigurationError: If the provided ID is not 1 or 2.

    """

    if id not in [1, 2]:
        raise ConfigurationError("Partial Start Id must be 1 or 2")

    return await self.__system_action(f"partial_start_{id}")
```

--------------------------------

### System Actions API

Source: https://mguyard.github.io/pydiagral/api

Perform system actions like start, stop, presence, or partial starts.

```APIDOC
## POST /systems/{serial_id}/{action}

### Description
Perform a system action such as start, stop, presence, partial start 1, or partial start 2.

### Method
POST

### Endpoint
/systems/{serial_id}/{action}

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the system.
- **action** (string) - Required - The action to perform. Must be one of 'start', 'stop', 'presence', 'partial_start_1', or 'partial_start_2'.

#### Request Body
None

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the system status after performing the action.

#### Response Example
```json
{
  "status": "running",
  "message": "System started successfully."
}
```

### Errors
- **ConfigurationError**: If the action is not one of the allowed actions.
- **AuthenticationError**: If the API key, secret key, or PIN code is missing.
```

--------------------------------

### Define and instantiate Cameras model

Source: https://mguyard.github.io/pydiagral/models

Demonstrates the structure of the Cameras dataclass and how to initialize it with an installation date.

```python
@dataclass
class Cameras(SensorModel):
    """Cameras model representing a sensor with an installation date, inheriting from SensorModel.

    Attributes:
        installation_date (datetime | None): The date when the camera was installed.
            Defaults to None. This attribute is aliased as 'installationDate' in metadata.

    Example:
        >>> camera = Cameras(
        ...     uid="12345",
        ...     type=1,
        ...     gamme=2,
        ...     group=3,
        ...     index=4,
        ...     label="Camera 1",
        ...     serial="SN12345",
        ...     is_video=True,
        ...     ref_code="RC123",
        ...     subtype=5,
        ...     anomalies=None,
        ...     inhibited=False,
        ...     can_inhibit=True,
        ...     installation_date=datetime(2023, 10, 1)
        ... )
        >>> print(camera.installation_date)
        2023-10-01 00:00:00

    """

    installation_date: datetime | None = field(
        default=None, metadata={"alias": "installationDate"}
    )
```

--------------------------------

### Install pydiagral

Source: https://mguyard.github.io/pydiagral

Install the pydiagral library using pip.

```bash
pip install pydiagral
```

--------------------------------

### Start system in presence mode

Source: https://mguyard.github.io/pydiagral/api

Initiates the system in presence mode. Requires valid authentication credentials.

```python
async def presence(self) -> SystemStatus:
    """Asynchronously starts the system in presence mode.

    Returns:
        SystemStatus: An instance of SystemStatus containing the system status after starting the system in presence mode.

    Raises:
        ConfigurationError: If the action is not one of the allowed actions.
        AuthenticationError: If the API key, secret key, or PIN code is missing.

    """

    return await self.__system_action("presence")
```

--------------------------------

### Initialize TransmitterModel

Source: https://mguyard.github.io/pydiagral/models

Example usage of the TransmitterModel class showing initialization with firmware and plug status.

```python
>>> firmware = FirmwareModel(box="1.0.0", central="2.0.0", centralradio="3.0.0")
>>> transmitter = TransmitterModel(
...     uid="12345",
...     type=1,
...     gamme=2,
...     group=3,
...     index=4,
...     label="Transmitter 1",
...     serial="SN12345",
...     is_video=True,
...     ref_code="RC123",
...     subtype=5,
...     anomalies=None,
...     inhibited=False,
...     can_inhibit=True,
...     firmwares=firmware,
...     is_plug=True
... )
>>> print(transmitter.uid)
12345
```

--------------------------------

### Presence Mode API

Source: https://mguyard.github.io/pydiagral/api

Asynchronously starts the system in presence mode and returns its status.

```APIDOC
## POST /api/system/presence

### Description
Asynchronously starts the system in presence mode. Returns the system status after starting.

### Method
POST

### Endpoint
/api/system/presence

### Request Body
None

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the system status after starting the system in presence mode.

#### Response Example
```json
{
  "status": "presence_mode"
}
```

### Errors
- **ConfigurationError**: If the action is not one of the allowed actions.
- **AuthenticationError**: If the API key, secret key, or PIN code is missing.
```

--------------------------------

### Get Configuration

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves the system configuration from the Diagral API.

```python
    async def get_configuration(self) -> None:
        """Asynchronously retrieve the configuration of the Diagral system.

        This method retrieves the configuration of the Diagral system by sending a GET
        request to the appropriate endpoint. If the access token is not available, it
        attempts to log in to obtain one. Upon successful retrieval, it logs an informational
```

--------------------------------

### Initialize ConfAnomaliesModel

Source: https://mguyard.github.io/pydiagral/models

Example usage of the ConfAnomaliesModel constructor to set various alert statuses.

```python
>>> anomalies = ConfAnomaliesModel(
...     radio_alert=True,
...     power_supply_alert=False,
...     autoprotection_mechanical_alert=True,
...     loop_alert=False,
...     mask_alert=True,
...     sensor_alert=False,
...     media_gsm_alert=True,
...     media_rtc_alert=False,
...     media_adsl_alert=True,
...     out_of_order_alert=False,
...     main_power_supply_alert=True,
...     secondary_power_supply_alert=False,
...     default_media_alert=True,
...     autoprotection_wired_alert=False
... )
print(anomalies.radio_alert)
True
print(anomalies.power_supply_alert)
False
```

--------------------------------

### Perform System Action

Source: https://mguyard.github.io/pydiagral/api

Use this method to perform system actions like start, stop, or presence checks. Ensure all required authentication credentials and action parameters are provided.

```python
async def __system_action(self, action: str) -> SystemStatus:
    """Perform a system action such as start, stop, presence, partial start 1, or partial start 2.

    Args:
        action (str): The action to perform. Must be one of 'start', 'stop', 'presence', 'partial_start_1', or 'partial_start_2'.

    Returns:
        SystemStatus: An instance of SystemStatus containing the system status after performing the action.

    Raises:
        ConfigurationError: If the action is not one of the allowed actions.
        AuthenticationError: If the API key, secret key, or PIN code is missing.

    """

    if action not in [
        "start",
        "stop",
        "presence",
        "partial_start_1",
        "partial_start_2",
    ]:
        raise ConfigurationError(
            "Action must be one of 'start', 'stop', 'presence', 'partial_start_1', or 'partial_start_2'"
        )

    if not self.__apikey or not self.__secret_key:
        raise AuthenticationError(
            "API key and secret key required to get system details"
        )

    if not self.__pincode:
        raise AuthenticationError(f"PIN code required to do system action {action}")

    _TIMESTAMP = str(int(time.time()))
    _HMAC: str = generate_hmac_signature(
        timestamp=_TIMESTAMP,
        serial_id=self.serial_id,
        api_key=self.__apikey,
        secret_key=self.__secret_key,
    )

    _HEADERS: dict[str, str] = {
        "X-PIN-CODE": self.__pincode,
        "X-HMAC": _HMAC,
        "X-TIMESTAMP": _TIMESTAMP,
        "X-APIKEY": self.__apikey,
    }
    response_data, *_ = await self._request(
        "POST", f"systems/{self.serial_id}/{action}", headers=_HEADERS
    )
    _LOGGER.debug(
        "Successfully performed action %s: %s", action.upper(), response_data
    )
    return SystemStatus.from_dict(response_data)
```

--------------------------------

### GET /systems/{serial_id}

Source: https://mguyard.github.io/pydiagral/api

Retrieves detailed information about a specific system.

```APIDOC
## GET /systems/{serial_id}

### Description
Retrieves the full details of a system identified by its serial ID.

### Method
GET

### Endpoint
systems/{serial_id}

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.
```

--------------------------------

### GET /users/systems/{serial_id}/configuration

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves the configuration of the Diagral system. Requires authentication.

```APIDOC
## GET /users/systems/{serial_id}/configuration

### Description
Asynchronously retrieves the configuration of the Diagral system. Requires authentication.

### Method
GET

### Endpoint
/users/systems/{serial_id}/configuration

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the system.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **configuration** (object) - An object containing the system's configuration details.

#### Response Example
{
  "configuration": {
    "setting1": "value1",
    "setting2": "value2"
  }
}
```

--------------------------------

### Execute System Actions

Source: https://mguyard.github.io/pydiagral/api

Performs specific system actions like start or stop. Validates the action type and requires authentication credentials.

```python
async def __system_action(self, action: str) -> SystemStatus:
        """Perform a system action such as start, stop, presence, partial start 1, or partial start 2.

        Args:
            action (str): The action to perform. Must be one of 'start', 'stop', 'presence', 'partial_start_1', or 'partial_start_2'.

        Returns:
            SystemStatus: An instance of SystemStatus containing the system status after performing the action.

        Raises:
            ConfigurationError: If the action is not one of the allowed actions.
            AuthenticationError: If the API key, secret key, or PIN code is missing.

        """

        if action not in [
            "start",
            "stop",
            "presence",
            "partial_start_1",
            "partial_start_2",
        ]:
            raise ConfigurationError(
                "Action must be one of 'start', 'stop', 'presence', 'partial_start_1', or 'partial_start_2'"
            )

        if not self.__apikey or not self.__secret_key:
            raise AuthenticationError(
                "API key and secret key required to get system details"
            )

        if not self.__pincode:
            raise AuthenticationError(f"PIN code required to do system action {action}")

        _TIMESTAMP = str(int(time.time()))
        _HMAC: str = generate_hmac_signature(
            timestamp=_TIMESTAMP,
            serial_id=self.serial_id,
            api_key=self.__apikey,
            secret_key=self.__secret_key,
        )

        _HEADERS: dict[str, str] = {
            "X-PIN-CODE": self.__pincode,
            "X-HMAC": _HMAC,
            "X-TIMESTAMP": _TIMESTAMP,
            "X-APIKEY": self.__apikey,
        }
        response_data, *_ = await self._request(
            "POST", f"systems/{self.serial_id}/{action}", headers=_HEADERS
        )
        _LOGGER.debug(
            "Successfully performed action %s: %s", action.upper(), response_data
        )
        return SystemStatus.from_dict(response_data)
```

```python
async def start_system(self) -> SystemStatus:
        """Asynchronously starts the system.

        This method sends a request to start the system and returns the system status.

        Returns:
            SystemStatus: An instance of SystemStatus containing the system status after starting the system.

        Raises:
            ConfigurationError: If the action is not one of the allowed actions.
            AuthenticationError: If the API key, secret key, or PIN code is missing.

        """

        return await self.__system_action("start")
```

```python
async def stop_system(self) -> SystemStatus:
        """Asynchronously stops the system.

        This method sends a request to stop the system and returns the system status.

        Returns:
            SystemStatus: An instance of SystemStatus containing the system status after stopping the system.

        Raises:
            ConfigurationError: If the action is not one of the allowed actions.
            AuthenticationError: If the API key, secret key, or PIN code is missing.

        """

        return await self.__system_action("stop")
```

--------------------------------

### Get System Details API

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves the system details using API key, secret key, and PIN code.

```APIDOC
## GET /api/systems/{serial_id}/details

### Description
Asynchronously retrieves the system details. This method fetches the system details using the provided API key, secret key, and PIN code. It generates the necessary HMAC signature and includes it in the request headers.

### Method
GET

### Endpoint
/api/systems/{serial_id}/details

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the system.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **SystemDetails** (SystemDetails) - An instance of SystemDetails containing the retrieved system information.

#### Response Example
```json
{
  "serial_id": "YOUR_SERIAL_ID",
  "model": "Model XYZ",
  "version": "1.2.3",
  "status": "active"
}
```

### Error Handling
- **AuthenticationError**: If the API key, secret key, or PIN code is not provided.
```

--------------------------------

### GET System Details

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves the system details using the provided API key, secret key, and PIN code. It generates the necessary HMAC signature for authentication.

```APIDOC
## GET System Details

### Description
Asynchronously retrieves the system details. This method fetches the system details using the provided API key, secret key, and PIN code, generating the necessary HMAC signature.

### Method
GET

### Endpoint
N/A (Internal method)

### Parameters
#### Headers
- **X-PIN-CODE** (string) - Required - The PIN code for authentication.
- **X-HMAC** (string) - Required - The HMAC signature for authentication.
- **X-TIMESTAMP** (string) - Required - The timestamp of the request.
- **X-APIKEY** (string) - Required - The API key for authentication.
- **X-SECRET-KEY** (string) - Required - The secret key for authentication.

### Response
#### Success Response (200)
- **SystemDetails** (object) - An instance of SystemDetails containing the retrieved system information.

#### Response Example
```json
{
  "serial_id": "12345",
  "model": "Diagral Connect",
  "version": "1.0.0"
}
```

### Raises
- **AuthenticationError**: If the API key, secret key, or PIN code is not provided.
```

--------------------------------

### GET /systems/{serial_id}/configurations

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieve the configuration of the Diagral system. This method sends a GET request to the appropriate endpoint. If the access token is not available, it attempts to log in to obtain one. Upon successful retrieval, it logs an informational message with the configuration details. The retrieved configuration is stored in the self.alarm_configuration attribute, allowing it to be reused within the same session without needing to collect it multiple times.

```APIDOC
## GET /systems/{serial_id}/configurations

### Description
Asynchronously retrieve the configuration of the Diagral system. This method retrieves the configuration of the Diagral system by sending a GET request to the appropriate endpoint. If the access token is not available, it attempts to log in to obtain one. Upon successful retrieval, it logs an informational message with the configuration details. The retrieved configuration is stored in the self.alarm_configuration attribute, allowing it to be reused within the same session without needing to collect it multiple times.

### Method
GET

### Endpoint
/systems/{serial_id}/configurations

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the Diagral system.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **AlarmConfiguration** (object) - The configuration details of the Diagral system.

#### Response Example
```json
{
  "alarm_configuration": {
    "alarm": {
      "name": "string"
    }
  }
}
```

### Error Handling
- **AuthenticationError**: If the access token is not available.
```

--------------------------------

### POST /users/systems/{serial_id}/api_keys

Source: https://mguyard.github.io/pydiagral/api

Sets a new API key for the system. This is often used for initial setup or when temporary keys are needed.

```APIDOC
## POST /users/systems/{serial_id}/api_keys

### Description
Sets a new API key for the system. This is often used for initial setup or when temporary keys are needed. Requires authentication.

### Method
POST

### Endpoint
/users/systems/{serial_id}/api_keys

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The serial ID of the system.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **api_key** (string) - The newly generated API key.
- **secret_key** (string) - The secret key associated with the API key.

#### Response Example
{
  "api_key": "your_new_api_key",
  "secret_key": "your_secret_key"
}
```

--------------------------------

### Get System Rudes Asynchronously

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves Rudes data for a system using API and secret keys for authentication. Requires valid credentials and raises AuthenticationError if keys are missing.

```python
async def get_automatism_rudes(self) -> Rudes:
    """Asynchronously retrieves the automatism Rudes for the system.

    This method fetches the Rudes data for the system identified by the serial ID.
    It requires valid API and secret keys for authentication.

    Returns:
        Rudes: An instance of the Rudes class populated with the data from the response.

    Raises:
        AuthenticationError: If the API key or secret key is not provided.

    """

    if not self.__apikey or not self.__secret_key:
        raise AuthenticationError(
            "API key and secret key required to get system details"
        )

    _TIMESTAMP = str(int(time.time()))
    _HMAC: str = generate_hmac_signature(
        timestamp=_TIMESTAMP,
        serial_id=self.serial_id,
        api_key=self.__apikey,
        secret_key=self.__secret_key,
    )

    _HEADERS: dict[str, str] = {
        "X-HMAC": _HMAC,
        "X-TIMESTAMP": _TIMESTAMP,
        "X-APIKEY": self.__apikey,
    }
    response_data, *_ = await self._request(
        "GET",
        f"systems/{self.serial_id}/rudes",
        headers=_HEADERS,
    )
    return Rudes.from_dict(response_data)
```

--------------------------------

### GET /systems/{serial_id}/rudes

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves the automatism Rudes for the system identified by the serial ID. Requires valid API and secret keys for authentication.

```APIDOC
## GET /systems/{serial_id}/rudes

### Description
Asynchronously retrieves the automatism Rudes for the system. This method fetches the Rudes data for the system identified by the serial ID.

### Method
GET

### Endpoint
systems/{serial_id}/rudes

### Response
#### Success Response (200)
- **Rudes** (Rudes) - An instance of the Rudes class populated with the data from the response.
```

--------------------------------

### Get System Rudes with HMAC Signature

Source: https://mguyard.github.io/pydiagral/api

Retrieves automatism Rudes for a system using HMAC authentication. Requires valid API and secret keys. Raises AuthenticationError if keys are missing.

```python
        if not self.__apikey or not self.__secret_key:
            raise AuthenticationError(
                "API key and secret key required to get system details"
            )

        _TIMESTAMP = str(int(time.time()))
        _HMAC: str = generate_hmac_signature(
            timestamp=_TIMESTAMP,
            serial_id=self.serial_id,
            api_key=self.__apikey,
            secret_key=self.__secret_key,
        )

        _HEADERS: dict[str, str] = {
            "X-HMAC": _HMAC,
            "X-TIMESTAMP": _TIMESTAMP,
            "X-APIKEY": self.__apikey,
        }
        response_data, *_ = await self._request(
            "GET",
            f"systems/{self.serial_id}/rudes",
            headers=_HEADERS,
        )
        return Rudes.from_dict(response_data)
```

--------------------------------

### Get Alarm Name

Source: https://mguyard.github.io/pydiagral/api

Get the name of the alarm from the configuration. This method will attempt to fetch the configuration if it hasn't been loaded yet.

```APIDOC
## Get Alarm Name

### Description
Get the name of the alarm from the configuration. This method will attempt to fetch the configuration if it hasn't been loaded yet.

### Method
GET (implicitly, by calling `get_configuration`)

### Endpoint
N/A (This is a method within the API class)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **str** (string) - The name of the alarm from the configuration.

### Error Handling
- **ConfigurationError**: If unable to retrieve the alarm configuration.
```

--------------------------------

### Enable Product in System

Source: https://mguyard.github.io/pydiagral/api

Convenience method to asynchronously enable a product. It calls the internal `__action_product` method with the 'enable' action. Ensure API credentials and PIN code are configured.

```python
async def enable_product(
    self, type: str, product_id: int
) -> SystemStatus:  # NOT-TESTED
    """Asynchronously enables a product in the system.

    Args:
        type (str): The type of the product to enable.
        product_id (int): The unique identifier of the product to enable.

    Returns:
        SystemStatus: An instance of SystemStatus containing the system status after enabling the product.

    Raises:
        ConfigurationError: If the action is not 'enable'
        AuthenticationError: If the API key, secret key, or PIN code is not provided.

    """
    return await self.__action_product(
        action="enable", type=type, product_id=product_id
    )
```

--------------------------------

### Cameras Model

Source: https://mguyard.github.io/pydiagral/models

Represents a camera sensor model with installation date tracking.

```APIDOC
## Cameras Model

### Description
Represents a camera sensor model that inherits from SensorModel, including an installation date attribute.

### Attributes
- **installation_date** (datetime | None) - Optional - The date when the camera was installed. Aliased as 'installationDate' in metadata.
```

--------------------------------

### Initialize BoxModel

Source: https://mguyard.github.io/pydiagral/models

Instantiates a BoxModel with firmware and basic box attributes.

```python
>>> firmware = FirmwareModel(box="1.0.0", central="2.0.0", centralradio="3.0.0")
>>> box = BoxModel(name="Box 1", serial="123456789", vendor="VendorName", firmwares=firmware)
>>> print(box.name)
Box 1
```

```python
@dataclass
class BoxModel(CamelCaseModel):
    """BoxModel represents a model for a box with various attributes.

    Attributes:
        name (str | None): The name of the box. Defaults to None.
        serial (str | None): The serial number of the box. Defaults to None.
        vendor (str | None): The vendor of the box. Defaults to None.
        firmwares (FirmwareModel | None): The firmware model associated with the box. Defaults to None.

    Example:
        >>> firmware = FirmwareModel(box="1.0.0", central="2.0.0", centralradio="3.0.0")
        >>> box = BoxModel(name="Box 1", serial="123456789", vendor="VendorName", firmwares=firmware)
        >>> print(box.name)
        Box 1

    """

    name: str | None = None
    serial: str | None = None
    vendor: str | None = None
    firmwares: FirmwareModel | None = None
```

--------------------------------

### GET /systems/{serial_id}/status

Source: https://mguyard.github.io/pydiagral/api

Retrieves the current operational status of the system.

```APIDOC
## GET /systems/{serial_id}/status

### Description
Fetches the current status of the system. Requires authentication headers including X-PIN-CODE, X-HMAC, X-TIMESTAMP, and X-APIKEY.

### Method
GET

### Endpoint
systems/{serial_id}/status

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.
```

--------------------------------

### Initialize and Access AlarmConfiguration

Source: https://mguyard.github.io/pydiagral/models

Demonstrates how to instantiate the AlarmConfiguration model with various sub-models and access its attributes.

```python
@dataclass
class AlarmConfiguration(CamelCaseModel):
    """AlarmConfiguration model represents the configuration of an alarm system.

    Attributes:
        alarm (AlarmModel | None): The alarm model associated with the configuration.
        groups (list[Group] | None): A list of groups associated with the alarm configuration.
        sirens (list[SensorModel] | None): A list of siren sensor models.
        cameras (list[Cameras] | None): A list of camera models.
        sensors (list[SensorModel] | None): A list of sensor models.
        commands (list[SensorModel] | None): A list of command sensor models.
        reading_date (datetime | None): The date when the configuration was read, aliased as "readingDate".
        transceivers (list[TransceiverModel] | None): A list of transceiver models.
        transmitters (list[TransmitterModel] | None): A list of transmitter models.
        presence_group (list[int] | None): A list of group marche presence, aliased as "presenceGroup".
        installation_state (int | None): The state of the installation, aliased as "installationState".
        central_information (CentralInformation | None): Information about the central unit, aliased as "centralInformation".
        partial_group1 (list[int] | None): A list of group marche partielle 1, aliased as "partialGroup1".
        partial_group2 (list[int] | None): A list of group marche partielle 2, aliased as "partialGroup2".

    Example:
        >>> alarm_config = AlarmConfiguration(
        ...     alarm=AlarmModel(name="Home Alarm"),
        ...     groups=[Group(name="Group A", index=1)],
        ...     sirens=[SensorModel(uid="12345", type=1)],
        ...     cameras=[Cameras(uid="67890", type=2)],
        ...     sensors=[SensorModel(uid="54321", type=3)],
        ...     commands=[SensorModel(uid="98765", type=4)],
        ...     reading_date=datetime(2023, 10, 1),
        ...     transceivers=[TransceiverModel(uid="11223", type=5)],
        ...     transmitters=[TransmitterModel(uid="44556", type=6)],
        ...     presence_group=[1, 2, 3],
        ...     installation_state=1,
        ...     central_information=CentralInformation(has_plug=True),
        ...     partial_group1=[4, 5, 6],
        ...     partial_group2=[7, 8, 9]
        ... )
        >>> print(alarm_config.alarm.name)
        Home Alarm

    """

    alarm: AlarmModel | None = None
```

--------------------------------

### GET /systems/{serial_id}/rudes

Source: https://mguyard.github.io/pydiagral/api

Retrieves the automatism rules (Rudes) for the specified system.

```APIDOC
## GET systems/{serial_id}/rudes

### Description
Fetches the automatism Rudes data for the system identified by the serial ID.

### Method
GET

### Endpoint
systems/{serial_id}/rudes

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.
```

--------------------------------

### Initialize DiagralAPI Instance

Source: https://mguyard.github.io/pydiagral/api

Initializes the DiagralAPI with user credentials and system details. Requires a valid email for the username and raises ConfigurationError for invalid inputs.

```python
def __init__(
    self,
    username: str,
    password: str,
    serial_id: str,
    apikey: str | None = None,
    secret_key: str | None = None,
    pincode: str | None = None,
) -> None:
    """Initialize the DiagralAPI instance.

    Args:
        username (str): The email address for Diagral API authentication.
        password (str): The password for Diagral API authentication.
        serial_id (str): The serial ID of the Diagral system.
        apikey (str | None, optional): The API key for additional authentication. Defaults to None.
        secret_key (str | None, optional): The secret key for additional authentication. Defaults to None.
        pincode (str | None, optional): The PIN code for the Diagral system. Defaults to None.

    Raises:
        ConfigurationError: If any required field is empty or invalid.

    """
    # Validate username as an email
    if (
        not username
        or not isinstance(username, str)
        or not self.__is_valid_email(username)
    ):
        raise ConfigurationError("username must be a valid non-empty email address")
    self.username: str = username

    # Validate password
    if not password or not isinstance(password, str):
        raise ConfigurationError("password must be a non-empty string")
    self.__password: str = password

    # Validate serial_id
    if not serial_id or not isinstance(serial_id, str):
        raise ConfigurationError("serial_id must be a non-empty string")
    self.serial_id: str = serial_id

    # Set apikey and secret_key
    self.__apikey = apikey
    self.__secret_key = secret_key

    # Validate pincode
    if pincode is not None:
        if not isinstance(pincode, str) or (
            isinstance(pincode, str) and not pincode.isdigit()
        ):
            raise ConfigurationError("pincode must be an string of digits")
    self.__pincode: str | None = pincode

    # Initialize session and access_token
    self.session: aiohttp.ClientSession | None = None
    self.__access_token: str | None = None

    # Set default values for other attributes
    self.alarm_configuration: AlarmConfiguration | None = None

```

--------------------------------

### Enable Product

Source: https://mguyard.github.io/pydiagral/api

Asynchronously enables a product in the Diagral system.

```APIDOC
## Enable Product

### Description
Asynchronously enables a product in the system.

### Parameters
#### Request Body
- **type** (str) - Required - The type of the product to enable.
- **product_id** (int) - Required - The unique identifier of the product to enable.

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the system status after enabling the product.
```

--------------------------------

### GET /systems/{serial_id}/status

Source: https://mguyard.github.io/pydiagral/api

Retrieves the current status of the system using HMAC authentication.

```APIDOC
## GET /systems/{serial_id}/status

### Description
Asynchronously retrieves the system status. This method fetches the current status of the system using the provided API key, secret key, and PIN code. It generates an HMAC signature for authentication and sends a GET request to the system status endpoint.

### Method
GET

### Endpoint
systems/{serial_id}/status

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.

### Response
#### Success Response (200)
- **SystemStatus** (SystemStatus) - An instance of SystemStatus containing the retrieved system status.

### Errors
- **ConfigurationError**: Raised if the API key, secret key, or PIN code is not provided.
```

--------------------------------

### Configure Environment Variables

Source: https://mguyard.github.io/pydiagral

Set up your Diagral API credentials and configuration in a .env file.

```dotenv
USERNAME=your_email@example.com
PASSWORD=your_password
SERIAL_ID=your_serial_id
PIN_CODE=your_pin_code
LOG_LEVEL=DEBUG

```

--------------------------------

### GET /webhooks/{serial_id}/subscription

Source: https://mguyard.github.io/pydiagral/api

Retrieves the current webhook subscription details for the specified system.

```APIDOC
## GET webhooks/{serial_id}/subscription

### Description
Retrieves the webhook subscription details for the system.

### Method
GET

### Endpoint
webhooks/{serial_id}/subscription

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.
```

--------------------------------

### Get Alarm Name

Source: https://mguyard.github.io/pydiagral/api

Retrieves the alarm name from the configuration, triggering a fetch if not already loaded.

```python
if not self.alarm_configuration:
    await self.get_configuration()

if not self.alarm_configuration:
    raise ConfigurationError("Failed to retrieve alarm configuration")

return self.alarm_configuration.alarm.name
```

--------------------------------

### Initialize AlarmModel

Source: https://mguyard.github.io/pydiagral/models

Instantiates an AlarmModel with associated box and plug configurations.

```python
>>> box = BoxModel(name="Box 1", serial="123456789", vendor="VendorName")
>>> plug = CentralPlugModel(name="Central Plug 1", serial="987654321", vendor="VendorName")
>>> alarm = AlarmModel(box=box, plug=plug, tls=True, name="Home Alarm", central=plug, force_push_config=True)
>>> print(alarm.name)
Home Alarm
```

```python
@dataclass
class AlarmModel(CamelCaseModel):
    """AlarmModel represents the configuration and state of an alarm system.

    Attributes:
        box (BoxModel | None): The box model associated with the alarm system.
        plug (CentralPlugModel | None): The central plug model for the alarm system.
        tls (bool | None): Indicates if TLS (Transport Layer Security) is enabled.
        name (str | None): The name of the alarm system.
        central (CentralPlugModel | None): The central plug model for the alarm system.
        force_push_config (bool | None): Indicates if the configuration should be forcefully pushed.
                                         This attribute is aliased as "forcePushConfig".

    Example:
        >>> box = BoxModel(name="Box 1", serial="123456789", vendor="VendorName")
        >>> plug = CentralPlugModel(name="Central Plug 1", serial="987654321", vendor="VendorName")
        >>> alarm = AlarmModel(box=box, plug=plug, tls=True, name="Home Alarm", central=plug, force_push_config=True)
        >>> print(alarm.name)
        Home Alarm

    """

    box: BoxModel | None = None
    plug: CentralPlugModel | None = None
    tls: bool | None = None
    name: str | None = None
    central: CentralPlugModel | None = None
    force_push_config: bool | None = field(
        default=None, metadata={"alias": "forcePushConfig"}
    )
```

--------------------------------

### Define and instantiate TransceiverModel

Source: https://mguyard.github.io/pydiagral/models

Shows the TransceiverModel dataclass definition and how to associate it with a FirmwareModel instance.

```python
@dataclass
class TransceiverModel(SensorModel):
    """TransceiverModel represents a model for a transceiver device, inheriting from SensorModel.

    Attributes:
        firmwares (FirmwareModel | None): An optional attribute that holds the firmware information associated with the transceiver.

    Example:
        >>> firmware = FirmwareModel(box="1.0.0", central="2.0.0", centralradio="3.0.0")
        >>> transceiver = TransceiverModel(
        ...     uid="12345",
        ...     type=1,
        ...     gamme=2,
        ...     group=3,
        ...     index=4,
        ...     label="Transceiver 1",
        ...     serial="SN12345",
        ...     is_video=True,
        ...     ref_code="RC123",
        ...     subtype=5,
        ...     anomalies=None,
        ...     inhibited=False,
        ...     can_inhibit=True,
        ...     firmwares=firmware
        ... )
        >>> print(transceiver.uid)
        12345

    """

    firmwares: FirmwareModel | None = None
```

--------------------------------

### Get Devices Info API

Source: https://mguyard.github.io/pydiagral/api

Asynchronously retrieves information about various device types from the alarm configuration.

```APIDOC
## GET /api/devices

### Description
Asynchronously retrieves information about various device types (cameras, commands, sensors, sirens, transmitters) from the alarm configuration. This method compiles the information into a dictionary.

### Method
GET

### Endpoint
/api/devices

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **dict** (DeviceList) - A dictionary where keys are device types and values are lists of dictionaries containing device information (index and label).

#### Response Example
```json
{
  "cameras": [
    {"index": 1, "label": "Front Door Camera"}
  ],
  "commands": [
    {"index": 1, "label": "Arm System"}
  ],
  "sensors": [
    {"index": 1, "label": "Living Room Motion"}
  ],
  "sirens": [
    {"index": 1, "label": "Main Siren"}
  ],
  "transmitters": [
    {"index": 1, "label": "Cellular Transmitter"}
  ]
}
```

### Error Handling
- **ConfigurationError**: If the alarm configuration cannot be retrieved.
```

--------------------------------

### Retrieve system details asynchronously

Source: https://mguyard.github.io/pydiagral/api

Fetches system details by generating an HMAC signature using API credentials and a PIN code. Requires valid authentication keys to be set on the instance.

```python
async def get_system_details(self) -> SystemDetails:
    """Asynchronously retrieves the system details.

    This method fetches the system details using the provided API key, secret key,
    and PIN code. It generates the necessary HMAC signature and includes it in the
    request headers.

    Returns:
        SystemDetails: An instance of SystemDetails containing the retrieved system information.

    Raises:
        AuthenticationError: If the API key, secret key, or PIN code is not provided.

    """

    if not self.__apikey or not self.__secret_key:
        raise AuthenticationError(
            "API key and secret key required to get system details"
        )

    if not self.__pincode:
        raise AuthenticationError("PIN code required to get system details")

    _TIMESTAMP = str(int(time.time()))
    _HMAC: str = generate_hmac_signature(
        timestamp=_TIMESTAMP,
        serial_id=self.serial_id,
        api_key=self.__apikey,
        secret_key=self.__secret_key,
    )

    _HEADERS: dict[str, str] = {
        "X-PIN-CODE": self.__pincode,
        "X-HMAC": _HMAC,
        "X-TIMESTAMP": _TIMESTAMP,
        "X-APIKEY": self.__apikey,
    }
    response_data, *_ = await self._request(
        "GET", f"systems/{self.serial_id}", headers=_HEADERS
    )
    _LOGGER.debug("Successfully retrieved system details: %s", response_data)
    return SystemDetails.from_dict(response_data)
```

--------------------------------

### Define and Instantiate CentralPlugModel

Source: https://mguyard.github.io/pydiagral/models

Initializes a CentralPlugModel with firmware details and device attributes.

```python
@dataclass
class CentralPlugModel(CamelCaseModel):
    """CentralPlugModel represents the central plug device.

    Attributes:
        name (str | None): The name of the central plug device.
        serial (str | None): The serial number of the central plug device.
        vendor (str | None): The vendor of the central plug device.
        firmwares (FirmwareModel | None): The firmware information of the central plug device.

    Example:
        >>> firmware = FirmwareModel(box="1.0.0", central="2.0.0", centralradio="3.0.0")
        >>> central_plug = CentralPlugModel(
        ...     name="Central Plug 1",
        ...     serial="123456789",
        ...     vendor="VendorName",
        ...     firmwares=firmware
        ... )
        >>> print(central_plug.name)
        Central Plug 1
        >>> print(central_plug.serial)
        123456789
        >>> print(central_plug.vendor)
        VendorName
        >>> print(central_plug.firmwares.box)
        1.0.0

    """

    name: str | None = None
    serial: str | None = None
    vendor: str | None = None
    firmwares: FirmwareModel | None = None
```

--------------------------------

### GET /systems/{serial_id}/anomalies

Source: https://mguyard.github.io/pydiagral/api

Retrieves the list of anomalies for a specific system identified by its serial ID.

```APIDOC
## GET systems/{serial_id}/anomalies

### Description
Fetches the list of anomalies for the system identified by the serial ID.

### Method
GET

### Endpoint
systems/{serial_id}/anomalies

### Parameters
#### Path Parameters
- **serial_id** (string) - Required - The unique identifier of the system.
```

--------------------------------

### Retrieve Device Information

Source: https://mguyard.github.io/pydiagral/api

Compiles a list of devices including cameras, commands, sensors, sirens, and transmitters from the configuration.

```python
if not self.alarm_configuration:
    await self.get_configuration()

if not self.alarm_configuration:
    raise ConfigurationError("Failed to retrieve alarm configuration")

device_types: list[str] = sorted(
    ["cameras", "commands", "sensors", "sirens", "transmitters"]
)
devices_infos = {}
for device_type in device_types:
    _LOGGER.debug("Retrieving devices information for %s", device_type)
    devices: Any | None = getattr(self.alarm_configuration, device_type, None)
    if devices is not None:
        devices_infos[device_type] = [
            {"index": device.index, "label": device.label} for device in devices
        ]
    else:
        devices_infos[device_type] = []
_LOGGER.debug("Successfully retrieved devices information: %s", devices_infos)
return DeviceList.from_dict(devices_infos)
```

--------------------------------

### GET Alarm Name

Source: https://mguyard.github.io/pydiagral/api

Retrieves the name of the alarm from the stored configuration. It will attempt to fetch the configuration if it hasn't been loaded yet.

```APIDOC
## GET Alarm Name

### Description
Gets the name of the alarm from the configuration. If the configuration is not yet loaded, it will be fetched first.

### Method
GET

### Endpoint
N/A (Internal method)

### Response
#### Success Response (200)
- **name** (string) - The name of the alarm.

#### Response Example
```json
{
  "name": "My Alarm System"
}
```

### Raises
- **ConfigurationError**: If unable to retrieve the alarm configuration.
```
Tokens:
Raw