python-selve-new

Python library for interfacing with Selve devices (roller shutters, awnings, blinds) via the USB-RF Gateway. This is a complete rewrite of the original library with improved async support, comprehensive testing, and production-ready stability.

Description

This library provides a Python interface to control Selve devices through their USB-RF Gateway. It implements the complete Selve protocol for communication with:

Devices: Roller shutters, awnings, and blinds with individual or group control
Sensors: Temperature, wind, and light sensors for automated control
Iveo Controllers: Wall-mounted and remote controllers
Transmitters: RF transmitters for integration with other systems

The library features full async/await support, automatic device discovery, event handling, and robust error recovery. It's designed for integration into home automation systems like Home Assistant.

Features

Async Architecture: Built on asyncio for non-blocking operation
Auto-Discovery: Automatically finds USB-RF Gateway and configured devices
Device Management: Control individual devices or groups
Position Control: Precise positioning with percentage-based commands
Event System: Subscribe to device state changes and sensor readings
Error Handling: Robust error recovery and connection management
Comprehensive API: Full coverage of Selve protocol commands
Type Safety: Fully typed for better IDE support and fewer errors
Well Tested: 350+ unit and integration tests for production stability

Supported Device Types

Roller shutters (Commeo, Iveo)
Awnings
Venetian blinds
Group controls
senSim sensors (wind, sun, temperature)
Iveo remote controllers
RF transmitters

Installation

pip install python-selve-new

Usage

Basic Example

import asyncio
from selve import Selve

async def main():
    # Initialize and discover devices
    gateway = Selve()
    await gateway.setup()
    
    # Get all devices
    devices = gateway.discover_devices()
    print(f"Found {len(devices)} devices")
    
    # Control a device
    device = gateway.device(0)  # Get device by ID
    await device.open()         # Fully open
    await asyncio.sleep(5)
    await device.set_position(50)  # Move to 50%
    await asyncio.sleep(5)
    await device.close()        # Fully close
    
    # Cleanup
    await gateway.stopWorker()

asyncio.run(main())

Advanced Usage

import asyncio
from selve import Selve

async def on_state_change(device):
    """Callback when device state changes"""
    print(f"Device {device.id} changed to position {device.target_value}")

async def main():
    # Initialize with specific port
    gateway = Selve(port="/dev/ttyUSB0")
    await gateway.setup()
    
    # Register callback for state changes
    gateway.register_callback(on_state_change)
    
    # Discover all device types
    devices = gateway.discover_devices()
    groups = gateway.discover_groups()
    sensors = gateway.discover_sensors()
    
    print(f"Devices: {len(devices)}")
    print(f"Groups: {len(groups)}")
    print(f"Sensors: {len(sensors)}")
    
    # Control a group of devices
    if groups:
        group = gateway.group(0)
        await group.set_position(75)
    
    # Read sensor values
    for sensor in sensors:
        print(f"Sensor {sensor.id}: {sensor.value}")
    
    # Keep running to receive events
    try:
        await asyncio.sleep(3600)  # Run for 1 hour
    finally:
        await gateway.stopWorker()

asyncio.run(main())

Device Control Methods

# Position control
await device.open()              # Fully open (0%)
await device.close()             # Fully close (100%)
await device.stop()              # Stop movement
await device.set_position(50)    # Move to 50%

# State queries
position = device.target_value   # Current target position
state = device.state            # Current state (IDLE, MOVING, etc.)

# Device info
name = device.name              # Device name
device_type = device.type       # Device type

Gateway & Firmware Methods

# Firmware
version = await controller.firmwareGetVersion()  # Gateway firmware version

# Gateway parameters
await controller.setDuty(mode)         # Set duty cycle mode
await controller.setRF(addr)           # Set RF base address
temp = await controller.getTemperature() # Internal gateway temperature

Home Assistant Integration

This library is used by the homeassistant-selve integration to provide native Selve device support in Home Assistant.

Features in Home Assistant:

Automatic device discovery
Cover entities for shutters, awnings, and blinds
Position control with slider
Sensor entities for environmental data
Group control support
Event-driven updates

To use in Home Assistant, install the custom integration:

Install via HACS (recommended) or manually copy the integration

Add to configuration.yaml:

selve:
  port: /dev/ttyUSB0  # or auto-detect

Restart Home Assistant
Devices appear as cover entities

See homeassistant-selve for full documentation.

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run integration tests (requires hardware or mocks)
pytest tests/integration/ -m "not hardware"

# Run with coverage
pytest --cov=selve --cov-report=html

Project Structure

selve/
├── __init__.py          # Main Selve class
├── device.py            # Device control
├── group.py             # Group control
├── sensor.py            # Sensor handling
├── gateway.py           # Gateway communication
├── commands/            # Protocol command implementations
└── util/                # Utilities and protocol handling

tests/
├── unit/                # Unit tests (337 tests)
└── integration/         # Integration tests (24 tests)

Requirements

Python 3.9 or higher
pyserial >= 3.4
untangle >= 1.1.1

License

This project is licensed under the GNU General Public License v2.0 or later (GPLv2+).

Credits

Author: Stefan Altheimer (me@stefan-altheimer.de)
Original Library: Based on concepts from the original python-selve
Protocol: Implements the Selve USB-RF Gateway protocol

Support

Report issues: GitHub Issues
Home Assistant integration: homeassistant-selve

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_selve_new-2.5.15.tar.gz (122.1 kB view details)

Uploaded Jul 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

python_selve_new-2.5.15-py3-none-any.whl (127.4 kB view details)

Uploaded Jul 26, 2026 Python 3

File details

Details for the file python_selve_new-2.5.15.tar.gz.

File metadata

Download URL: python_selve_new-2.5.15.tar.gz
Upload date: Jul 26, 2026
Size: 122.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.25

File hashes

Hashes for python_selve_new-2.5.15.tar.gz
Algorithm	Hash digest
SHA256	`924bc70cf7737b4017709b5a001101b334fa9d7a76f3c006c81c8c8c90c78c7c`
MD5	`416963a1022fdd421093ac1fcd742777`
BLAKE2b-256	`c36c0ee18e8bf69c935bbf5d89c37abc3673394baa83c1016f3332cc4caefbdf`

See more details on using hashes here.

File details

Details for the file python_selve_new-2.5.15-py3-none-any.whl.

File metadata

Download URL: python_selve_new-2.5.15-py3-none-any.whl
Upload date: Jul 26, 2026
Size: 127.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.25

File hashes

Hashes for python_selve_new-2.5.15-py3-none-any.whl
Algorithm	Hash digest
SHA256	`6cd91f7433289cf70f941e54850f98019d54538879850622f956422fbf6d884b`
MD5	`9a7e15cd5efb12d2ff261adb932d15c0`
BLAKE2b-256	`478cf10d473439bf81a17af0b30a3f1f4ee1f89cebe6a7162f241de8d6e6d538`