aioiregul

Asynchronous Python library to interact with IRegul systems via their undocumented API over sockets.

Note: This library is under active development.

Features

• 🔄 Fully asynchronous using asyncio and aiohttp
• 🔌 Socket-based communication with IRegul systems
• 🎯 Type-safe with comprehensive type hints
• 📊 Parse and decode IRegul API responses
• 🏠 Home automation integration ready

Requirements

• Python 3.14 or higher
• aiohttp
• BeautifulSoup4
• python-slugify

Installation

uv pip install aioiregul

Or install from source:

git clone https://github.com/PoppyPop/aioiregul.git
cd aioiregul
uv sync --all-extras

Quick Start

import asyncio
import aioiregul

async def main():
    # Configure connection options
    options = aioiregul.ConnectionOptions(
        username='your_username',
        password='your_password'
    )

    # Create device instance
    device = aioiregul.Device(options)

    # Collect data from the device
    data = await device.collect()

    # Display results
    print(data)

# Run the async function
asyncio.run(main())

Development Setup

Using VS Code Devcontainer (Recommended)

The easiest way to get started with development:

1. Install Docker and VS Code
2. Install the Remote - Containers extension
3. Open the project in VS Code
4. Click "Reopen in Container" when prompted

All dependencies and tools will be automatically installed!

Local Development

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/Mac
# Or on Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Sync all dependencies
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=aioiregul --cov-report=html

# Run specific test
uv run pytest tests/test_iregul.py -v

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check . --fix

# Type checking
uv run mypy src/

# Run all pre-commit hooks
uv run pre-commit run --all-files

Project Structure

aioiregul/
├── .devcontainer/          # VS Code devcontainer configuration
├── src/
│   └── aioiregul/         # Main library code
├── tests/                 # Unit tests
├── examples/              # Example scripts and sample data
├── pyproject.toml         # Project configuration
├── CONTRIBUTING.md        # Contribution guidelines
└── README.md              # This file

API Documentation

ConnectionOptions

Configuration for connecting to IRegul systems.

@dataclass
class ConnectionOptions:
    username: str                    # IRegul account username
    password: str                    # IRegul account password
    iregul_base_url: str            # Base URL (default: https://vpn.i-regul.com/modules/)
    refresh_rate: timedelta         # Data refresh interval (default: 5 minutes)

Device

Main class for interacting with IRegul devices.

device = Device(options: ConnectionOptions)
data = await device.collect()  # Fetch current device data

IRegulData

Data structure for IRegul measurements.

@dataclass
class IRegulData:
    id: str           # Data point identifier
    name: str         # Human-readable name
    value: Decimal    # Measured value
    unit: str         # Unit of measurement

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Checklist

• Write tests for new features
• Update documentation
• Follow code style guidelines (Ruff, MyPy)
• Add type hints to all functions
• Write docstrings for public APIs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This library reverse-engineers the undocumented IRegul API. It is not officially supported by IRegul.

Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Read the docs

Changelog

See CHANGELOG.md for version history and changes.