A powerful and easy-to-use Python library for seamless integration with the Diagral alarm system.

pydiagral

Welcome to the documentation for pydiagral, a Python library for interacting with the Diagral API.

📍 About pydiagral

pydiagral is an asynchronous Python interface for the Diagral alarm system. This library allows users to control and monitor their Diagral alarm system through the official API.

✅ Requirement

To use this library, which leverages the Diagral APIs, you must have a Diagral box (DIAG56AAX or DIAG59AAX). This box connects your Diagral alarm system to the internet, enabling interaction with the alarm system via the API. DIAG56AAX is End of Sales but you can find more information about the DIAG59AAX available inside the DIAG99AGX.

📦 Key Features

The DiagralAPI class offers the following functionalities:

• Authentication:

  • Connect to the Diagral API with username and password
  • Log in to obtain an access token
  • Create, validate, and delete API keys

• System Configuration:

  • Retrieve alarm configuration

• System Information:

  • Obtain system details
  • Retrieve the current system status
  • Manage webhooks
  • Manage anomalies

• System Interraction:

  • Activate or Desactivate system (partially or globally)
  • List automatism rules (running their actions is not implemented yet)

🚀 Quick Start

To get started with pydiagral, follow these steps:

1. Installation:

   pip install pydiagral
   

2. Example

A modular and easy-to-use test script is available example_code.py to help you get started with the library.

Simply create a .env file with the following content:

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

And run the example_code.py.

3. Request timeout

Each request to the Diagral cloud may take up to 30 seconds. To allow more, set request_timeout (in seconds) when creating the client:

async with DiagralAPI(
    username=username,
    password=password,
    serial_id=serial_id,
    request_timeout=60,
) as diagral:
    ...

To give a single call a shorter deadline, wrap it in asyncio.timeout(). That deadline cannot exceed request_timeout.

4. Shared session

To send requests through an aiohttp.ClientSession you already manage, pass it as session. The client uses it as is and never closes it:

async with aiohttp.ClientSession() as session:
    async with DiagralAPI(
        username=username,
        password=password,
        serial_id=serial_id,
        session=session,
    ) as diagral:
        ...

Without session, the client opens its own on async with and closes it on exit.

📖 Documentations

Package Documentation

Library documentation is available here.

Package Structure

For detailed library documentation, please refer to the following sections:

• API Reference: Comprehensive documentation of the DiagralAPI class and its methods
• Data Models: Description of the data structures used
• Exceptions: List of package exceptions

Diagral API Official documentation

Official Diagral API is available here.

🙋 FAQ

How to find Serial on DIAG56AAX

The serial number can only be found with physical access to the box. You need to open it, and you will find a label with a QR Code.

On this label, there is a 14-character code that represents the serial number of the box.

🤝 Contribution

Contributions are welcome! Here are several ways you can contribute:

• Submit Pull Requests: Review open PRs, and submit your own PRs.
• Report Issues: Submit bugs found or log feature requests.

📄 License

pydiagral is distributed under the GPL-v3 License. See the LICENSE file for more details.