A simple CRUD for accessing the openHAB REST API. Whether via the cloud or locally.
Project description
Python openHAB CRUD
A simple CRUD
for accessing the openHAB REST API. Whether via the cloud or locally. The CRUD
can be used only for openHAB Items
. CRUD
means that you can run Create
, Read
, Update
and Delete
on Items
. The openHAB Cloud does not allow to use Create
and Delete
. This is the case for security reasons. In this case you have to create or delete an item locally.
Installation
You can install it by using pip
:
python3 -m pip install python-openhab-crud
Usage
CRUD
means that you can run Create
, Read
, Update
and Delete
on Items
. Reading
an Item
can have two different meanings: You can Read
the whole Item
or only the State
of an Item
. The latter can be done with the getState
function. Also can Updating
an Item
have two different meanings. In openHAB you can change an State
by using sendCommand
or postUpdate
. The function update
is an alias for sendCommand
or postUpdate
. You can specify sendCommand
or postUpdate
as parameters for update
. If no parameter is specified, postUpdate
is used automatically.
At first you have to import the CRUD
module:
from openhab import CRUD
Create connection to the openHAB Cloud (as example myopenhab.org)
If you want to create a connection to the openHAB Cloud
you have to run:
crud = CRUD("https://myopenhab.org", "<your_email>@<your_provider>", "<email_password>")
Please make sure to replace <your_email>@<your_provider>
with your email address and <email_password>
with your password that you used for your openHAB Cloud account
.
Create connection to your local openHAB instance
If you want to create a connection to your local openHAB
instance you have to replace <username>
and <password>
with the username and password of your local openHAB account
:
crud = CRUD("http://<your_ip>:8080", "<username>", "<password>")
Get all Items
If you want to retrieve all Items via the REST API
of openHAB
you can run:
items = crud.getAllItems()
The return value is a list
of dictionaries
(dict
). Each item is represented as dict
. You can check it by using type
:
print(type(items))
You can print each item separately by running:
for item in items:
print(item)
And of course you can access each property by using the get
method:
for item in items:
item_type = item.get("type")
item_name = item.get("name")
item_state = item.get("state")
print("Received item type " + item_type + " with name " + item_name + " and state " + item_state)
Creating new items
You can only create a new Item
if you have access to your local openHAB
instance. For security reasons, this is prohibited via the cloud.
An Item
must contain minimum its Name and its Type. A Label, a given State or Groups will be optional.
So at least you can run as example following:
crud.create("testItem", "String", "my test string", ["testGroup"], "ON")
crud.create("testItem2", "String", "my test string", ["testGroup"])
crud.create("testItem3", "Switch", "my test switch")
crud.create("testItem4", "Switch")
Of course you can use a different order:
crud.create(state="ON", type="String", name="testItem")
Groups
must be passed as a list
, since an Item
can be assigned to several Groups
:
crud.create("testItem", "String", "my test string", ["group1", "group2", "group3"])
The function automatically checks if the Type
of the Item
exists in openHAB and thus can be created. If you want to set a State
for this Item
, it is also automatically checked whether the State
is consistently valid for this Type
.
There will be no response if it is correct!
Reading an item
Reading
an Item
means that all information about this Item
is queried and not only the State
. You can do this as follows:
testItem = crud.read("testItem")
You will receive an Item
as a dictionary
(dict
):
print(type(testItem))
And of course you can access each property by using the get
method:
item_type = testItem.get("type")
item_name = testItem.get("name")
item_state = testItem.get("state")
print("Received item type " + item_type + " with name " + item_name + " and state " + item_state)
Updating an item
Updating
an Item
have two different meanings. In openHAB you can change an State
by using sendCommand
or postUpdate
. The function update
is an alias for sendCommand
or postUpdate
. You can specify sendCommand
or postUpdate
as parameters for update
. If no parameter is specified, postUpdate
is used automatically.
So you can run as example
crud.update("testItem", "Hello World")
or
crud.update("testItem", "Hello World", "postUpdate")
instead of
crud.postUpdate("testItem", "Hello World")
Or if you want to use sendCommand
in openHAB
you can run
crud.update("testItem", "Lorem ipsum", "sendCommand")
instead of
crud.sendCommand("testItem", "Lorem ipsum")
Note: postUpdate
and sendCommand
have validation capabilities. With type
you can set the type
of the Item
. This will call a function which checks that the value
which should change the State
of the Item
is persistent
. However, this does not mean that you are checking the correct Type
, because openHAB
may have a different Type
than the one you want to update. If you will set the validate
variable to True
the Item
is queried via the REST API
and the Type
is checked.
For checking if you put a right value for the State
of the assumed Type
you can run as example
crud.sendCommand("testItem", "Lorem ipsum", "Switch")
or
crud.postUpdate("testItem", "Hello World", "Switch")
If you want to check if the actual Type
on openHAB is correct and you can set the State
to this value you can run:
crud.sendCommand("testItem", "Lorem ipsum", None, True)
or
crud.postUpdate("testItem", "Hello World", None, True)
Another possibility is: name:str, value, type:str = None, validate:bool = None):
crud.sendCommand("testItem", "Lorem ipsum", validate=True)
or
crud.postUpdate("testItem", "Hello World", validate=True)
Of course you can change the order as example to:
crud.postUpdate(validate=True, type="Switch", name="testItem")
There will be no response if it is correct!
Deleting new items
You can only delete an Item
if you have access to your local openHAB
instance. For security reasons, this is prohibited via the cloud.
In this case you can run following:
crud.delete("testItem")
There will be no response if it is correct!
Getting the state of an item
In most cases you only want to query the current State
of an Item
and not get all informations of an Item
. The getState
function can be used for this purpose:
state = crud.getState("testItem")
You get the state as a string:
print(type(state))
This is due to the data transmission via http
. Numerical values must be parsed. openHAB
specific values like UP
, DOWN
, PLAY
, PAUSE
, ON
, OFF
etc. have no data type in Python, i.e. here a string (str
) still makes sense. Here the capitalization must be considered!
At least you can print the State
with:
print(state)
Close session
Since we may want to make several requests in a row, a session
is opened when the CRUD object
is created. This can of course also be terminated at the end:
crud.close()
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for python_openhab_crud-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 806d9a392c272e5d4f50fb57ca6bbc88f74373f07bc070f7a5862599d0c9a002 |
|
MD5 | d00bc980c3d2a805a8558caca76562ad |
|
BLAKE2b-256 | 914237173818f3ef84ff2cc5252460686b7bb5c0b8b25f426f3ce2145130f7ca |