Metadata-Version: 2.4 Name: raspyrfm-client Version: 1.2.9 Summary: A library to send rc signals with the RaspyRFM module License: GPL-3.0-or-later License-File: LICENSE Author: Markus Ressel Author-email: mail@markusressel.de Requires-Python: >=3.10,<4.0 Classifier: Development Status :: 5 - Production/Stable Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Programming Language :: Python :: 3.13 Classifier: Programming Language :: Python :: 3.14 Project-URL: Homepage, https://github.com/markusressel/raspyrfm-client Project-URL: Repository, https://github.com/markusressel/raspyrfm-client Description-Content-Type: text/x-rst .. |pypi_version| image:: https://badge.fury.io/py/raspyrfm-client.svg :target: https://badge.fury.io/py/raspyrfm-client raspyrfm-client |pypi_version| ============================== A python 3.4+ library that allows the generation of network codes for the RaspyRFM rc module (and other gateways too!). Build Status ============ .. |build_master| image:: https://travis-ci.org/markusressel/raspyrfm-client.svg?branch=master :target: https://travis-ci.org/markusressel/raspyrfm-client/branches .. |build_beta| image:: https://travis-ci.org/markusressel/raspyrfm-client.svg?branch=beta :target: https://travis-ci.org/markusressel/raspyrfm-client/branches .. |build_dev| image:: https://travis-ci.org/markusressel/raspyrfm-client.svg?branch=dev :target: https://travis-ci.org/markusressel/raspyrfm-client/branches .. |codebeat_master| image:: https://codebeat.co/badges/fcac9cfe-b6a2-4c4a-938d-42214371dc3d :target: https://codebeat.co/projects/github-com-markusressel-raspyrfm-client-master .. |codebeat_beta| image:: https://codebeat.co/badges/c6c09759-3f34-4a16-b17e-d7989b3f7fae :target: https://codebeat.co/projects/github-com-markusressel-xs1-api-client-beta .. |codebeat_dev| image:: https://codebeat.co/badges/6ef4cbdd-a452-45b2-8ee8-f7a09e53689f :target: https://codebeat.co/projects/github-com-markusressel-raspyrfm-client-dev +--------------------+------------------+-----------------+ | Master | Beta | Dev | +====================+==================+=================+ | |build_master| | |build_beta| | |build_dev| | +--------------------+------------------+-----------------+ | |codebeat_master| | |codebeat_beta| | |codebeat_dev| | +--------------------+------------------+-----------------+ Home Assistant ============== The initial goal of this library was to be able to integrate the SimpleSolutions ConnAir gateway with `Home Assistant `_. This gateway is sadly not sold anymore but there are other alternatives like the Intertechno Gateway or the `ConnAir Emulator script `_ that can be used on a Raspberry Pi equipped with a 433MHz radio like the `RaspyRFM from Seegel Systeme `_. You can find the related integration documentation here: `RaspyRFM Home Assistant component documentation `_ How to use ========== Installation ------------ :code:`pip install raspyrfm-client` Usage ----- For a basic example have a look at the `example.py `_ file. If you need more info have a look at the `documentation `_ which should help. Basic Example ------------- Import required modules ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: python from raspyrfm_client import RaspyRFMClient from raspyrfm_client.device_implementations.controlunit.actions import Action from raspyrfm_client.device_implementations.controlunit.controlunit_constants import ControlUnitModel from raspyrfm_client.device_implementations.gateway.manufacturer.gateway_constants import GatewayModel from raspyrfm_client.device_implementations.manufacturer_constants import Manufacturer Create the :code:`RaspyRFMClient` object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Get a client instance by calling: .. code-block:: python rfm_client = RaspyRFMClient() Create a :code:`Gateway` instance ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can let the library search automatically for gateways available in LAN using: .. code-block:: python gateways = rfm_client.search() This will return a list of Gateways that can later be used to send signals to. To get a quick overview of what gateway **manufacturers** and **models** are supported call: .. code-block:: python rfm_client.list_supported_gateways() Create a gateway instance with the specified :code:`IP` and :code:`Port` of your Gateway by using: .. code-block:: python gateway = rfm_client.get_gateway(Manufacturer.SEEGEL_SYSTEME, GatewayModel.RASPYRFM, "192.168.2.10", 9876) or .. code-block:: python gateway = rfm_client.get_gateway(Manufacturer.SEEGEL_SYSTEME, GatewayModel.RASPYRFM, "192.168.2.10") # defaults to 49880 or the gateway implementations default Get a :code:`ControlUnit` ^^^^^^^^^^^^^^^^^^^^^^^^^ ControlUnits are the devices that receive the RC signals sent using the gateway, f.ex. a power outlet. To get a quick overview of what ControlUnits **manufacturers** and **models** are supported call: .. code-block:: python rfm_client.list_supported_controlunits() which will give you an indented list of supported manufacturers and their supported models similar to this: .. code-block:: text Elro RC3500-A IP44 DE AB440S AB440D 200W AB440D 300W AB440ID AB440IS AB440L AB440SC AB440WD BAT RC AAA1000-A IP44 Outdoor Brennenstuhl RCS 1000 N Comfort RCS 1044 N Comfort Intertek Model 1919361 [...] To generate codes for a device **you first have to get an instance of its implementation** like this: .. code-block:: python brennenstuhl_rcs1000 = rfm_client.get_controlunit(manufacturer_constants.BRENNENSTUHL, manufacturer_constants.RCS_1000_N_COMFORT) The parameters of the :code:`get_controlunit()` method always need to be an enum value of the specified type. You can get an enum constant by its name though using: .. code-block:: python manufacturer = Manufacturer("Intertechno") model = ControlUnitModel("IT-1500") :code:`ControlUnit` channel configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Before you can generate codes with your shiny new gateway and :code:`ControlUnit` implementations you have to specify a channel configuration for your :code:`ControlUnit`. These **configurations can be very different for every device**. The best way to know the correct way of specifying the channel configuration for a specific device is to look at the source code (yes I know...) or by trial and error (even worse). A good :code:`ControlUnit` implementation should tell you how the configuration should look like when specifying it in a wrong way. However all configurations are a **keyed dictionary**. So in general there are two ways of passing the channel configuration argument. One (inline): .. code-block:: python device.set_channel_config(value1=1, value2=2) Two (as a dictionary): .. code-block:: python device.set_channel_config(**{ 'value1': 1, 'value2': 2 }) **Note** that the **keys always need to be a** :code:`string`. The second one is the recommended one as it will often result in a much more readable source code. For our Brennenstuhl device it would look like this: .. code-block:: python brennenstuhl_rcs1000.set_channel_config(**{ '1': True, '2': True, '3': True, '4': True, '5': True, 'CH': 'A' }) Generate action codes ^^^^^^^^^^^^^^^^^^^^^ Now that you have a properly set up :code:`ControlUnit` you can generate codes for it's supported actions by using an :code:`Action` enum constant that you imported previously. To get a list of supported actions for a :code:`ControlUnit` call: .. code-block:: python brennenstuhl_rcs1000.get_supported_actions() and generate a code for one of them using your :code:`Gateway` instance: .. code-block:: python code = gateway.generate_code(brennenstuhl_rcs1000, Action.ON) Send the code to the :code:`RaspyRFM` module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To send a code for your device of choice you can combine the objects in this call: .. code-block:: python rfm_client.send(gateway, brennenstuhl_rcs1000, Action.ON) This will generate a code specific to the passed in gateway implementation and send it to it's host address immediately after. Custom implementations ====================== The :code:`raspyrfm-client` library is designed so you can implement custom devices in a (hopefully) very easy way. File Structure -------------- All :code:`ControlUnit` implementations are located in the :code:`/device_implementations/controlunit/manufacturer/` module and implement the base class :code:`Device` that can be found in :code:`/device_implementations/controlunit/base.py`. Create a new :code:`ControlUnit` -------------------------------- To create a new :code:`ControlUnit` implementation for a new manufacturer and model create a new subdirectory for your manufacturer and a python file for your model: .. code-block:: ───raspyrfm_client │ │ client.py │ │ │ └───device │ │ actions.py │ │ base.py │ │ │ └───manufacturer │ │ manufacturer_constants.py │ │ │ ├───intertek │ │ Model1919361.py │ │ │ ├───rev │ │ Ritter.py │ │ Telecontrol.py │ │ │ ├───universal │ │ HX2262Compatible.py │ │ │ └───yourmanufacturer │ yourmodel.py ────────────────────────────────────────── Implement a :code:`ControlUnit` ------------------------------- Now the basic implementation of your :code:`ControlUnit` should looks like this: .. code-block:: python from raspyrfm_client.device_implementations.controlunit.actions import Action from raspyrfm_client.device_implementations.controlunit.base import ControlUnit class YourModel(ControlUnit): def __init__(self): from raspyrfm_client.device_implementations.manufacturer_constants import Manufacturer from raspyrfm_client.device_implementations.controlunit.controlunit_constants import ControlUnitModel super().__init__(Manufacturer.YourManufacturer, ControlUnitModel.YourModel) def get_channel_config_args(self): return {} def get_pulse_data(self, action: Action): return [[0, 0], [0, 0]], 0, 0 def get_supported_actions(self) -> [str]: return [Action.ON] Most importantly you have to call the :code:`super().__init__` method like shown. This will ensure that your implementation is found by the :code:`RaspyRFMClient` and you can get an instance of your device using :code:`rfm_client.get_controlunit()` as shown before. If your manufacturer does not exist yet **create a new enum constant** in the :code:`manufacturer_constants.py` file and use its value in your :code:`__init__`. **Do the same thing for your model name** in the :code:`controlunit_constants.py` file. You also have to implement all abstract methods from the :code:`Device` class. Have a look at it's documentation to get a sense of what those methods are all about. After you have implemented all methods you are good to go! Just call :code:`rfm_client.reload_implementation_classes()` and :code:`rfm_client.list_supported_controlunits()` to check if your implementation is listed. If everything looks good you can use your implementation like any other one. Exclude a WIP implementation ---------------------------- To prevent the RaspyRFM client from importing your half baked or base class implementation just include a class field like this: .. code-block:: python class YourModel(ControlUnit): DISABLED = True [...] Contributing ============ GitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks of this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in. License ======= :: raspyrfm-client by Markus Ressel Copyright (C) 2017 Markus Ressel This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .