|
| 1 | +# pyPiCode |
| 2 | +Python C extension module to wrap the PiCode library. |
| 3 | + |
| 4 | +[](https://www.gnu.org/licenses/lgpl-3.0) |
| 5 | + |
| 6 | +The [**PiCode library**](http://github.com/latchdevel/PiCode) provides an easy way to handle the wireless protocols of weather stations and radio control switches using 433/315Mhz radio frequency in ASK/OOK modulation, which have been implemented by the [pilight project](https://manual.pilight.org/protocols/433.92/index.html) |
| 7 | + |
| 8 | +The PiCode library is a standard C/C++ library, both static and dynamic, that works on any libc/libc++ compatible system, such as macOS, FreeBSD, Linux, and even Windows. |
| 9 | + |
| 10 | +Using [SWIG](https://www.swig.org/), to generate the Python C extension source files that wraps PiCode's static C library: |
| 11 | +- `picode_wrap.c`: CMake compiles the C source file, as does the PiCode library, and they link together to build the Python C extension module. |
| 12 | +- `picode_wrap.py`: Python functions of the picode wrapper module are redefined to add basic docstrings and parameter checks in `__init__.py` package file. |
| 13 | + |
| 14 | +## Install |
| 15 | +Package installation builds the C extension module, so some OS tools are required like these packages on Debian-based Linux systems: |
| 16 | +- Python3 development tools: `python3-dev` |
| 17 | +- Python3 package installer: `python3-pip` |
| 18 | +- C compiler suite: `build-essential` |
| 19 | +- CMake make system: `cmake` |
| 20 | +- Git version control system: `git` |
| 21 | + |
| 22 | +Command to install from GitHub: |
| 23 | +``` |
| 24 | +$ python3 -m pip install -v --user git+https://github.com/latchdevel/pyPiCode.git |
| 25 | +``` |
| 26 | + |
| 27 | +## Tests |
| 28 | +PyPiCode provides a unit tests module to verify its correct operation: |
| 29 | +``` |
| 30 | +$ python3 -m unittest discover -v pypicode |
| 31 | +``` |
| 32 | + |
| 33 | +## Usage |
| 34 | +```python |
| 35 | +>>> import pypicode as picode |
| 36 | +>>> |
| 37 | +>>> picode.decodeString("c:011010100101011010100110101001100110010101100110101010101010101012;p:1400,600,6800@") |
| 38 | +{'protocols': [{'conrad_rsl_switch': {'id': 1, 'unit': 2, 'state': 'on'}}]} |
| 39 | +>>> |
| 40 | +``` |
| 41 | + |
| 42 | +## Functions: |
| 43 | + |
| 44 | ++ **`decodePulseTrain`**`(pulses_list: list)` |
| 45 | + |
| 46 | + Decodes a list of pulses to a results dict. |
| 47 | + |
| 48 | + Returns a dict always, with a key "protocols" and a list of decoded protocols as its value, |
| 49 | + which will be empty if none are decoded, like as { 'protocols': [ ] } |
| 50 | + |
| 51 | ++ **`decodeString`**`(pilight_string: str)` |
| 52 | + |
| 53 | + Decodes a string in pilight format to a results dict. |
| 54 | + |
| 55 | + Returns a dict with a key "protocols" and a list of decoded protocols as its value, or None on failure. |
| 56 | + |
| 57 | ++ **`encodeJson`**`(json: dict, repeats: int = 0)` |
| 58 | + |
| 59 | + Encodes a full json dict to a string in pilight format. |
| 60 | + |
| 61 | + Returns a pilight string or None on failure. |
| 62 | + |
| 63 | ++ **`encodeToPulseTrain`**`(protocol, json_data: dict)` |
| 64 | + |
| 65 | + Encodes a Swig Object of type 'protocol_t *' and a json data dict to a pulses list. |
| 66 | + |
| 67 | + Returns a pulses list or None on failure. |
| 68 | + |
| 69 | ++ **`encodeToPulseTrainByName`**`(protocol_name: str, json_data: dict)` |
| 70 | + |
| 71 | + Encodes a protocol name string and a json data dict to a pulses list. |
| 72 | + |
| 73 | + Returns a pulses list or None on failure. |
| 74 | + |
| 75 | ++ **`encodeToString`**`(protocol_name: str, json_data: dict, repeats: int = 0)` |
| 76 | + |
| 77 | + Encodes a protocol name string and a json data dict to a string in pilight format. |
| 78 | + |
| 79 | + Returns a pilight string or None on failure. |
| 80 | + |
| 81 | ++ **`findProtocol`**`(name: str)` |
| 82 | + |
| 83 | + Find a protocol among all those initialized by name. |
| 84 | + |
| 85 | + Returns a Swig Object of type 'protocol_t *' or None on failure. |
| 86 | + |
| 87 | ++ **`getPiCodeVersion`**`()` |
| 88 | + |
| 89 | + Get version of PiCode library. |
| 90 | + |
| 91 | + Returns the full version string of the PiCode library or None on failure. |
| 92 | + |
| 93 | ++ **`pulseTrainToString`**`(pulses_list: list, repeats: int = 0)` |
| 94 | + |
| 95 | + Converts a list of pulses to a string in pilight format. |
| 96 | + |
| 97 | + Returns a pilight string or None on failure. |
| 98 | + |
| 99 | ++ **`stringToPulseTrain`**`(pilight_string: str)` |
| 100 | + |
| 101 | + Converts a string in pilight format to a pulses lists. |
| 102 | + |
| 103 | + Returns a pulses list or None on failure. |
| 104 | + |
| 105 | + |
| 106 | +# License |
| 107 | +Copyright (c) 2021-2022 Jorge Rivera. All right reserved. |
| 108 | + |
| 109 | +License GNU Lesser General Public License v3.0. |
| 110 | + |
| 111 | +This program is free software; you can redistribute it and/or |
| 112 | +modify it under the terms of the GNU Lesser General Public |
| 113 | +License as published by the Free Software Foundation; either |
| 114 | +version 3 of the License, or (at your option) any later version. |
| 115 | + |
| 116 | +This program is distributed in the hope that it will be useful, |
| 117 | +but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 118 | +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 119 | +Lesser General Public License for more details. |
| 120 | + |
| 121 | +You should have received a copy of the GNU Lesser General Public License |
| 122 | +along with this program; if not, write to the Free Software Foundation, |
| 123 | +Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| 124 | + |
| 125 | +See the [LICENSE](LICENSE) file for license rights and limitations (lgpl-3.0). |
0 commit comments