Metadata-Version: 2.4
Name: JablotronPy
Version: 0.7.4
Summary: Client to interact with Jablotron Cloud API to control Jablotron alarm systems
Author-email: "F. de Gier" <freddegier@me.com>
Project-URL: Homepage, https://github.com/fdegier/JablotronPy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.2
Dynamic: license-file

[![PyPI version](https://badge.fury.io/py/jablotronpy.svg)](https://badge.fury.io/py/jablotronpy)

# JablotronPy

Jablotron Cloud API client written in Python that allows you to retrieve data from Jablotron systems as well as control
them.

## Installation

The package is published to [PyPi](https://pypi.org/project/JablotronPy), to install it run the following
command:

```bash
pip install jablotronpy
```

## Usage

This is an example of initializing a client and getting all sections from the first available service:

```python
import os
from jablotronpy.jablotronpy import Jablotron

# Initialize client and perform login
client = Jablotron(
  username=os.environ["JABLOTRON_USER"],
  password=os.environ["JABLOTRON_PASS"],
  pin_code=os.environ["JABLOTRON_PIN"]
)
client.perform_login()

# Get service and its sections
service_id = client.get_services()[0]["service-id"]
sections = client.get_sections(service_id=service_id)
print(sections)
```

## Methods

The client offers a variation of data, here is a table of the methods and data it returns:

| Method                    | Description                                                                  |
|---------------------------|------------------------------------------------------------------------------|
| perform_login             | Performs initial login to Jablotron Cloud API                                |
| get_services              | Returns list of available services for specified Jablotron Cloud account     |
| get_service_information   | Returns additional information about specified service                       |
| get_sections              | Returns available sections for specified service                             |
| get_thermo_devices        | Returns list of available thermo devices for specified service               |
| get_keyboard_segments     | Returns list of available keyboards and their segments for specified service |
| get_programmable_gates    | Returns available programmable gates and their states for specified service  |
| get_service_history       | Returns list of historical events for specified service                      |
| control_section           | Sets specified section of specified service to desired state                 |
| control_programmable_gate | Sets specified programmable gate of specified service to desired state       |

## Detecting active alarms

The Jablotron Cloud API does not push notifications to third-party clients, so detecting an
active alarm requires polling. The signal lives in the `sectionsGet` response, **not** in
`serviceListGet` or in the section state itself (a section in alarm continues to report state
`ARM`). While an alarm is live, `data["service-states"]` contains an `events` list:

```json
{
  "service-states": {
    "service-name": "Home",
    "events": [
      {
        "type": "ALARM",
        "message": "Alarm - Periphery PIR hallway (wifi), Section House",
        "date": "2026-04-26T10:24:16+0200"
      }
    ]
  },
  "states": [{"cloud-component-id": "SEC-...", "state": "ARM"}],
  "sections": [...]
}
```

Notes:

- The `events` key is **only present while an event is active**. If the alarm ends before
  the next poll, you will miss it.
- Observed `type` value: `"ALARM"`. Other types (tamper, sabotage, fault) likely exist but
  are not yet documented here.
- The `JA100/eventHistoryGet.json` endpoint exposed via `get_service_history` returns
  `400 METHOD.NOT-SUPPORTED` for some panels (e.g. JA100F), so it is not a reliable
  fallback.

Minimal poller:

```python
sections = client.get_sections(service_id=sid)
for event in sections["service-states"].get("events", []):
    if event["type"] == "ALARM":
        ...  # handle alarm
```
