Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/markusressel/raspyrfm-client
A python library to send rc signals with the RaspyRFM module
https://github.com/markusressel/raspyrfm-client
433mhz home-automation homeassistant python-library raspberry-pi-3 raspberrypi raspy-rfm raspyrfm
Last synced: about 1 month ago
JSON representation
A python library to send rc signals with the RaspyRFM module
- Host: GitHub
- URL: https://github.com/markusressel/raspyrfm-client
- Owner: markusressel
- License: gpl-3.0
- Created: 2017-03-08T00:04:09.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-02-11T23:56:23.000Z (almost 2 years ago)
- Last Synced: 2024-09-29T00:45:31.250Z (about 2 months ago)
- Topics: 433mhz, home-automation, homeassistant, python-library, raspberry-pi-3, raspberrypi, raspy-rfm, raspyrfm
- Language: Python
- Size: 166 KB
- Stars: 5
- Watchers: 6
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
.. |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 .