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

Metadata

Release files for python-selve-new 2.5.20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-selve-new 2.5.20
File	Size	Uploaded
python_selve_new-2.5.20.tar.gz	140.7 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-selve-new 2.5.20
File	Interpreter	ABI	Platform	Reset
python_selve_new-2.5.20-py3-none-any.whl 145.1 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 285.8 kB

Release files / python_selve_new-2.5.20.tar.gz

Download URL	python_selve_new-2.5.20.tar.gz
Size	140.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`0a09ee8c8be3c662207421f113d3046977851416613fabdafd8e9fcd646eadd4`
BLAKE2b-256 checksum How to use checksums	`f9adb86d71e6b65c4e96da2684de5857e73ffb0e4083e2bc82c35d1e1ffdf99a`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / python_selve_new-2.5.20-py3-none-any.whl

Download URL	python_selve_new-2.5.20-py3-none-any.whl
Size	145.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6ccf2262a8b52fd0cb051752e7f02527f96140014a3735ebf8b16cc609b1f2ed`
BLAKE2b-256 checksum How to use checksums	`e726b1399bbe7c6b0c3d723ac2bc49151c7ff2b387d63a5b9aad85706c8ce398`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`