# OpenHAB python rule engine
A Python 3.x rule engine for OpenHAB. This rule engine allows you to define rules using Python 3.x.
**Please note that [OpenHAB username/password authentication](https://www.openhab.org/docs/configuration/restdocs.html) (basic authentication)
must be activated**. To do so, open [API security settings](doc/api_settings.png) and enable the advanced setting [Allow Basic Authentication](doc/basic_auth.png).
To run this software, you can use Docker or the [PIP](https://realpython.com/what-is-pip/) package manager, as shown below
**Docker approach**
```
sudo docker run -e openhab_uri=http://192.168.1.17:8080 -e user=me -e pwd=secret -v /etc/openhab2/automation/rules/python:/rules grro/pythonrule_engine
```
**PIP approach**
```
sudo pip install openhab-pythonrule-engine
```
```
sudo pyrule --command listen --openhab_uri http://localhost:8080 --python_rule_directory /etc/openhab2/automation/rules/python --user me --pwd secret
```
In this case, the rules engine connects to the Openhab instance running on the local machine on port 8080. Also, the /etc/openhab2/automation/rules/python directory is used to search for python-based rules
If you are using a *systemd-based Linux distribution*, you can use the *register* command to register and start the rule engine as a systemd entity.
This automatically starts the rule engine at boot time. Starting the Rule Engine manually with the *listen* command is no longer necessary.
```
sudo pyrule --command register --openhab_uri http://localhost:8080 --python_rule_directory /etc/openhab2/automation/rules/python --user me --pwd secret
```
**Rules**
To trigger a rule method, the **@when** decorator must be used. Currently the conditions listed below are supported
| condition | example | description |
|---|---|---|
| *cron* | @when('Time cron */1 * * * *') | fires based on cron expression |
| *item state change* | @when('Item PhoneLisaLastSeen changed') | fires when the specified Item's State changes |
| *item command* | @when('Item SelectDoorCam received command ON') <br/> @when('Item SelectDoorCam received command OFF') | fires when the specified Item receives a Command |
Example: **my_rule.py** (located within /etc/openhab2/automation/rules/python)
```python
from openhab_pythonrule_engine.condition import when
from openhab_pythonrule_engine.item_registry import ItemRegistry
@when("Time cron */1 * * * *") # each minute
@when("Item PhoneLisaLastSeen changed")
@when("Item PhoneTimLastSeen changed")
def update_presence_based_on_phone_seen(item_registry: ItemRegistry):
last_time_present = item_registry.get_state_as_datetime('LastDateTimePresence')
for phone_name in item_registry.get_group_membernames('Phones'):
last_seen = item_registry.get_state_as_datetime(phone_name)
print(last_seen)
if last_seen > last_time_present:
last_time_present = last_seen
item_registry.set_state('LastDateTimePresence', last_time_present)
# uncomment the code below for local debugging
#item_registry = ItemRegistry.new_singleton(openhab_uri="http://192.168.1.27:8080/", user="xxx", pwd="secret")
#update_presence_based_on_phone_seen(item_registry)
```
If the rule method defines a (single!) argument, the item_registry object is automatically injected.
The item_registry object provides methods for getting and setting the item state. When setting the state, the data value
is automatically converted to the item-specific data type
Raw data
{
"_id": null,
"home_page": "https://github.com/grro/openhab_pythonrule_engine",
"name": "openhab-pythonrule-engine",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "webthings,home automation,openhab,python3,python,rules",
"author": "Gregor Roth",
"author_email": "gregor.roth@web.de",
"download_url": "https://files.pythonhosted.org/packages/8a/1e/1743c1fd9a58d37b5d500263b8e191f01aee9983a9869b65503e8f8d933f/openhab_pythonrule_engine-1.2.28.tar.gz",
"platform": null,
"description": "# OpenHAB python rule engine\nA Python 3.x rule engine for OpenHAB. This rule engine allows you to define rules using Python 3.x. \n\n**Please note that [OpenHAB username/password authentication](https://www.openhab.org/docs/configuration/restdocs.html) (basic authentication)\nmust be activated**. To do so, open [API security settings](doc/api_settings.png) and enable the advanced setting [Allow Basic Authentication](doc/basic_auth.png).\n\nTo run this software, you can use Docker or the [PIP](https://realpython.com/what-is-pip/) package manager, as shown below\n\n**Docker approach**\n```\nsudo docker run -e openhab_uri=http://192.168.1.17:8080 -e user=me -e pwd=secret -v /etc/openhab2/automation/rules/python:/rules grro/pythonrule_engine \n```\n\n**PIP approach**\n```\nsudo pip install openhab-pythonrule-engine\n```\n\n```\nsudo pyrule --command listen --openhab_uri http://localhost:8080 --python_rule_directory /etc/openhab2/automation/rules/python --user me --pwd secret\n```\nIn this case, the rules engine connects to the Openhab instance running on the local machine on port 8080. Also, the /etc/openhab2/automation/rules/python directory is used to search for python-based rules\n\nIf you are using a *systemd-based Linux distribution*, you can use the *register* command to register and start the rule engine as a systemd entity.\nThis automatically starts the rule engine at boot time. Starting the Rule Engine manually with the *listen* command is no longer necessary.\n```\nsudo pyrule --command register --openhab_uri http://localhost:8080 --python_rule_directory /etc/openhab2/automation/rules/python --user me --pwd secret\n``` \n\n\n**Rules**\n\nTo trigger a rule method, the **@when** decorator must be used. Currently the conditions listed below are supported\n\n| condition | example | description |\n|---|---|---|\n| *cron* | @when('Time cron */1 * * * *') | fires based on cron expression |\n| *item state change* | @when('Item PhoneLisaLastSeen changed') | fires when the specified Item's State changes |\n| *item command* | @when('Item SelectDoorCam received command ON') <br/> @when('Item SelectDoorCam received command OFF') | fires when the specified Item receives a Command |\n\n\nExample: **my_rule.py** (located within /etc/openhab2/automation/rules/python)\n```python\nfrom openhab_pythonrule_engine.condition import when\nfrom openhab_pythonrule_engine.item_registry import ItemRegistry\n\n\n@when(\"Time cron */1 * * * *\") # each minute\n@when(\"Item PhoneLisaLastSeen changed\")\n@when(\"Item PhoneTimLastSeen changed\")\ndef update_presence_based_on_phone_seen(item_registry: ItemRegistry):\n last_time_present = item_registry.get_state_as_datetime('LastDateTimePresence')\n for phone_name in item_registry.get_group_membernames('Phones'):\n last_seen = item_registry.get_state_as_datetime(phone_name)\n print(last_seen)\n if last_seen > last_time_present:\n last_time_present = last_seen\n item_registry.set_state('LastDateTimePresence', last_time_present)\n\n# uncomment the code below for local debugging\n#item_registry = ItemRegistry.new_singleton(openhab_uri=\"http://192.168.1.27:8080/\", user=\"xxx\", pwd=\"secret\")\n#update_presence_based_on_phone_seen(item_registry)\n```\n\nIf the rule method defines a (single!) argument, the item_registry object is automatically injected.\nThe item_registry object provides methods for getting and setting the item state. When setting the state, the data value\nis automatically converted to the item-specific data type\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Openhab python rule engine",
"version": "1.2.28",
"project_urls": {
"Homepage": "https://github.com/grro/openhab_pythonrule_engine"
},
"split_keywords": [
"webthings",
"home automation",
"openhab",
"python3",
"python",
"rules"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "148430dd638a5797651f91917119463724f93233eb013ac302d3e5db7f66b91e",
"md5": "8d0464e5cd21d635a30a21f127821b38",
"sha256": "1c4fc75a6cc258aeeff86b7b12d0222071a78793d57621d14a5abb9c7426a786"
},
"downloads": -1,
"filename": "openhab_pythonrule_engine-1.2.28-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d0464e5cd21d635a30a21f127821b38",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25348,
"upload_time": "2023-09-29T04:59:05",
"upload_time_iso_8601": "2023-09-29T04:59:05.704180Z",
"url": "https://files.pythonhosted.org/packages/14/84/30dd638a5797651f91917119463724f93233eb013ac302d3e5db7f66b91e/openhab_pythonrule_engine-1.2.28-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8a1e1743c1fd9a58d37b5d500263b8e191f01aee9983a9869b65503e8f8d933f",
"md5": "a2f95f23cd71b3f849eb553f3f66359a",
"sha256": "77ee97ec5406798076896bfdef89df966fd021df3dd9a7912b9e76651f9daaf3"
},
"downloads": -1,
"filename": "openhab_pythonrule_engine-1.2.28.tar.gz",
"has_sig": false,
"md5_digest": "a2f95f23cd71b3f849eb553f3f66359a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16296,
"upload_time": "2023-09-29T04:59:07",
"upload_time_iso_8601": "2023-09-29T04:59:07.363882Z",
"url": "https://files.pythonhosted.org/packages/8a/1e/1743c1fd9a58d37b5d500263b8e191f01aee9983a9869b65503e8f8d933f/openhab_pythonrule_engine-1.2.28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-29 04:59:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grro",
"github_project": "openhab_pythonrule_engine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openhab-pythonrule-engine"
}
JSON
