python-openhab-rest-client 0.2.4
A Python client for the openHAB REST API. This library enables easy interaction with the openHAB REST API to control smart home devices, retrieve status information, and process events.
Requires Python: >=3.6

# python-openhab-rest-client

A Python client for the openHAB REST API. This library enables easy interaction with the openHAB REST API to control smart home devices, retrieve status information, and process events.

## Features

Supports the following openHAB REST API endpoints:

- Actions
- Addons
- Audio
- Auth
- ChannelTypes
- ConfigDescriptions
- Discovery
- Events (ItemEvents, ThingEvents, InboxEvents, LinkEvents, ChannelEvents)
- Iconsets
- Inbox
- Items
- Links
- Logging
- ModuleTypes
- Persistence
- ProfileTypes
- Rules
- Services
- Sitemaps
- Systeminfo
- Tags
- Templates
- ThingTypes
- Things
- Transformations
- UI
- UUID
- Voice

Supports both Server-Sent Events (SSE) and regular REST requests. SSE is used for the events of openHAB.

## Requirements

- Python 3.x
- `requests`
- `json`

## Installation

Install via pip:

```sh
pip install python-openhab-rest-client
```

## Usage

Basically, you always need the `OpenHABClient`. Regardless of whether you carry out a normal `REST request` or one via `SSE`.

### Authentication

#### Basic Authentication

```python
from openhab import OpenHABClient

client = OpenHABClient(url="http://127.0.0.1:8080", username="openhab", password="habopen")
```

The `url`, the `username` and the `password` can also vary. In particular, it is possible that `url` could be a remote IP address or even the openHAB cloud.

#### Token-based Authentication

It is also conceivable that a `token` could be used instead of `basic authentication`, i.e. with a `username` and `password`. A `token` is used by default in openHAB. The `basic authentication` must actually be activated manually.

For token-based access, the initialization of the client is as follows:

```python
client = OpenHABClient(url="http://127.0.0.1:8080", token="oh.openhab.U0doM1Lz4kJ6tPlVGjH17jjm4ZcTHIHi7sMwESzrIybKbCGySmBMtysPnObQLuLf7PgqnI7jWQ5LosySY8Q")
```

Of course, your `token` will probably look different here too.

### Requests

#### Normal REST requests

Depending on the `endpoint`, a corresponding class must be imported from the library. If you want to access endpoints of the REST API with which you want to access `items`, you import the `Items` class, for example. There are then different functions in this class for each endpoint for items. More details can be found in the documentation.

An easy example could be:

```python
from openhab import OpenHABClient, Items

client = OpenHABClient(url="http://127.0.0.1:8080", username="openhab", password="habopen")
itemsAPI = Items(client)

allItems = itemsAPI.getAllItems()
print("All Items:", allItems)
```

#### Server-sent Events (SSE) requests

All normal REST requests are static. This means that they do not react to status changes. You would therefore have to send several REST requests in succession (polling). Or you can use the various evetnts from openHAB. This can be done using server-sent events (SSE) without polling. The server sends a message to the client exactly when it can make something available. With polling, on the other hand, you would have to constantly send requests to the server, which would significantly increase the network and server load.

There are various [events](https://www.openhab.org/docs/developer/utils/events.html) in openHAB. For `ItemEvents`, `ThingEvents`, `InboxEvents`, `LinkEvents` and `ChannelEvents` there are own classes. However, there is also the `Events` class. More information can be found in the documentation.

An example looks like this:

```python
from openhab import OpenHABClient, ItemEvents

client = OpenHABClient(url="http://127.0.0.1:8080", username="openhab", password="habopen")
itemEvents = ItemEvents(client)

response =  itemEvents.ItemStateChangedEvent()

with response as events:
    for line in events.iter_lines():
        line = line.decode()

        if "data" in line:
            line = line.replace("data: ", "")

            try:
                data = json.loads(line)
                print(data)
            except json.decoder.JSONDecodeError:
                print("Event could not be converted to JSON")
```

### Tests

There is also a test function for each function. This means that every class that you import also has a test class that you can import. These tests work with a try-catch, as well as with a print output. Neither the value of the REST API nor something like True or False is returned. Effectively, however, the actual function is called from this test function and also executed in full, unless an exception is thrown.

In other words... For example, if you use the following import,

```python
from openhab import Items
```

then the test class to be imported would be the following:

```python
from openhab.tests import ItemsTest
```

From e.g. the following function

```python

itemsAPI = Items(client)
itemsAPI.sendCommand("testSwitch", "ON")
```

then becomes the following function for the test:

```python

itemsTest = ItemsTest(client)
itemsTest.testSendCommand("testSwitch", "ON")
```

However, both would also really execute a sendCommand in openHAB. The test classes test whether a function can be executed. In the end, it can only not be executed if the endpoint does not exist or has been implemented incorrectly. However, a non-existent endpoint can also occur, for example, if the name of the item is incorrect.

## Full list of Methods

### OpenHABClient

`OpenHABClient` is a Python class that provides an interface to interact with the openHAB REST API. It allows users to send requests to openHAB to retrieve and manipulate smart home devices, events, and configurations. The get, put, post and delete methods are used in the other classes for the client. You therefore do not need to use them raw.

#### Initialization

##### Constructor

```python
from openhab import OpenHABClient

OpenHABClient(url: str, username: str = None, password: str = None, token: str = None)
```
###### Parameters:
- `url` (str): The base URL of the openHAB server (e.g., "http://127.0.0.1:8080").
- `username` (str, optional): Username for Basic Authentication (default is `None`).
- `password` (str, optional): Password for Basic Authentication (default is `None`).
- `token` (str, optional): Bearer Token for Token-based Authentication (default is `None`).

###### Example:

```python
client = OpenHABClient("http://127.0.0.1:8080", username="admin", password="password")
```

#### Methods

##### `get`

```python
get(endpoint: str, header: dict = None, params: dict = None)
```

Sends a GET request to the openHAB server.

###### Parameters:
- `endpoint` (str): The API endpoint (e.g., `"/items"`).
- `header` (dict, optional): Headers to include in the request.
- `params` (dict, optional): Query parameters for the request.

###### Example:

```python
response = client.get("/items")
print(response)
```

##### `post`

```python
post(endpoint: str, header: dict = None, data=None, params: dict = None)
```

Sends a POST request to the openHAB server.

###### Parameters:
- `endpoint` (str): The API endpoint (e.g., `"/items"`).
- `header` (dict, optional): Headers to include in the request.
- `data` (optional): Data to send in the request body.
- `params` (dict, optional): Query parameters for the request.

###### Example:

```python
data = {"type": "Switch", "state": "ON"}
response = client.post("/items/light", data=json.dumps(data))
print(response)
```

##### `put`

```python
put(endpoint: str, header: dict = None, data=None, params: dict = None)
```

Sends a PUT request to update a resource in openHAB.

###### Example:

```python
data = {"state": "OFF"}
response = client.put("/items/light", data=json.dumps(data))
print(response)
```

##### `delete`

```python
delete(endpoint: str, header: dict = None, data=None, params: dict = None)
```

Sends a DELETE request to remove a resource from openHAB.

###### Example:

```python
response = client.delete("/items/light")
print(response)
```

#### Authentication

The client supports two types of authentication:
- **Basic Authentication** (Username & Password)
- **Bearer Token Authentication**

If a token is provided, it is used for authentication; otherwise, Basic Authentication is used if credentials are supplied.

#### Error Handling

Errors during requests are caught and logged, with appropriate exception handling for HTTP errors, connection issues, and timeouts.


### Actions

The `Actions` class provides methods to interact with the OpenHAB actions API. It allows retrieving available actions for a specific `thingUID` and executing actions.

#### Initialization

```python
from openhab import OpenHABClient, Actions

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
actions = Actions(client)
```

#### Methods

##### `getAllActions(thingUID: str, language: str = None) -> list`

Retrieves all available actions for a given thing UID.

**Parameters:**
- `thingUID` (str): The UID of the thing for which actions should be retrieved.
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `list`: A list of available actions.

###### Example:
```python
actions_list = actions.getAllActions("myThingUID")
print(actions_list)
```

##### `execute_action(thingUID: str, actionUID: str, actionInputs: dict, language: str = None) -> str`

Executes an action on a specific thing.

**Parameters:**
- `thingUID` (str): The UID of the thing on which the action is executed.
- `actionUID` (str): The UID of the action to be performed.
- `actionInputs` (dict): A dictionary containing input parameters for the action.
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `str`: The response from the OpenHAB server.

###### Example:

```python
response = actions.execute_action("myThingUID", "actionID", {"param1": "value1"})
print(response)
```

### Addons

The `Addons` class provides methods for interacting with the openHAB add-ons via the REST API.

#### Methods

##### `getAddons(serviceID: str = None, language: str = None) -> dict`

Retrieves a list of all available add-ons.

**Parameters:**
- `serviceID` (optional): Filter by service ID.
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing add-ons data.

##### `getAddon(addonID: str, serviceID: str = None, language: str = None) -> dict`

Retrieves details of a specific add-on by its ID.

**Parameters:**
- `addonID`: The unique identifier of the add-on.
- `serviceID` (optional): Filter by service ID.
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing details of the specified add-on.

##### `getAddonConfig(addonID: str, serviceID: str = None) -> dict`

Retrieves the configuration of a specific add-on.

**Parameters:**
- `addonID`: The unique identifier of the add-on.
- `serviceID` (optional): Filter by service ID.

**Returns:**
A dictionary containing the configuration of the add-on.

##### `updateAddonConfig(addonID: str, configData: dict, serviceID: str = None) -> dict`

Updates the configuration of a specific add-on.

**Parameters:**
- `addonID`: The unique identifier of the add-on.
- `configData`: Dictionary containing new configuration settings.
- `serviceID` (optional): Specify the target service.

**Returns:**
A dictionary containing the updated configuration.

##### `installAddon(addonID: str, serviceID: str = None, language: str = None) -> dict`

Installs an add-on by its ID.

**Parameters:**
- `addonID`: The unique identifier of the add-on.
- `serviceID` (optional): Specify the target service.
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing the installation status.

##### `uninstallAddon(addonID: str, serviceID: str = None, language: str = None) -> dict`

Uninstalls an add-on by its ID.

**Parameters:**
- `addonID`: The unique identifier of the add-on.
- `serviceID` (optional): Specify the target service.
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing the uninstallation status.

##### `getAddonServices(language: str = None) -> dict`

Retrieves a list of all available add-on services.

**Parameters:**
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing available add-on services.

##### `getAddonSuggestions(language: str = None) -> dict`

Retrieves a list of suggested add-ons for installation.

**Parameters:**
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing suggested add-ons.

##### `getAddonTypes(language: str = None) -> dict`

Retrieves a list of all available add-on types.

**Parameters:**
- `language` (optional): Language preference for the response.

**Returns:**
A dictionary containing available add-on types.

##### `installAddonFromUrl(url: str) -> dict`

Installs an add-on from a given URL.

**Parameters:**
- `url`: The URL of the add-on to install.

**Returns:**
A dictionary containing the installation status.

### Audio

The `Audio` class provides methods for interacting with the OpenHAB audio API. It allows retrieving default audio sinks and sources, as well as listing available sinks and sources.

#### Initialization

```python
from openhab import OpenHABClient, Audio

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
audio = Audio(client)
```

#### Methods

##### `getDefaultSink(language: str = None) -> dict`

Retrieves the default audio sink if defined, or the first available sink.

**Parameters:**
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `dict`: Information about the default sink.

###### Example:

```python
default_sink = audio.getDefaultSink()
print(default_sink)
```

##### `getDefaultSource(language: str = None) -> dict`

Retrieves the default audio source if defined, or the first available source.

**Parameters:**
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `dict`: Information about the default source.

###### Example:

```python
default_source = audio.getDefaultSource()
print(default_source)
```

##### `getSinks(language: str = None) -> list`

Retrieves a list of all available audio sinks.

**Parameters:**
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `list`: A list of available audio sinks.

###### Example:

```python
sinks = audio.getSinks()
print(sinks)
```

##### `getSources(language: str = None) -> list`

Retrieves a list of all available audio sources.

**Parameters:**
- `language` (str, optional): The language for the response (sets the `Accept-Language` header).

**Returns:**
- `list`: A list of available audio sources.

###### Example:

```python
sources = audio.getSources()
print(sources)
```

### Auth

The `Auth` class provides methods for handling authentication in OpenHAB, including retrieving API tokens, revoking tokens, logging out, and managing authentication sessions.

#### Initialization

```python
from openhab import OpenHABClient, Auth

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
auth = Auth(client)
```

#### Methods

##### `getAPITokens(language: str = None) -> dict`

Retrieves the API tokens associated with the authenticated user.

**Parameters:**
- `language` (str, optional): The language for the request (sets the `Accept-Language` header).

**Returns:**
- `dict`: JSON response containing API tokens.

###### Example:

```python
tokens = auth.getAPITokens()
print(tokens)
```

##### `revokeAPIToken(tokenName: str, language: str = None) -> dict`

Revokes a specific API token associated with the authenticated user.

**Parameters:**
- `tokenName` (str): The name of the API token to revoke.
- `language` (str, optional): The language for the request.

**Returns:**
- `dict`: JSON response confirming the revocation.

###### Example:

```python
response = auth.revokeAPIToken("my_token")
print(response)
```

##### `logout(refreshToken: str, language: str = None) -> dict`

Terminates the session associated with a given refresh token.

**Parameters:**
- `refreshToken` (str): The refresh token used to delete the session.
- `language` (str, optional): The language for the request.

**Returns:**
- `dict`: JSON response confirming the logout.

###### Example:

```python
response = auth.logout("my_refresh_token")
print(response)
```

##### `getSessions(language: str = None) -> dict`

Retrieves the sessions associated with the authenticated user.

**Parameters:**
- `language` (str, optional): The language for the request.

**Returns:**
- `dict`: JSON response containing session details.

###### Example:

```python
sessions = auth.getSessions()
print(sessions)
```

##### `getToken(grantType: str, code: str = None, redirectURI: str = None, clientID: str = None, refreshToken: str = None, codeVerifier: str = None, language: str = None) -> dict`

Obtains access and refresh tokens.

**Parameters:**
- `grantType` (str): The type of grant being requested.
- `code` (str, optional): Authorization code for authentication.
- `redirectURI` (str, optional): Redirect URI for OAuth authentication.
- `clientID` (str, optional): Client ID for authentication.
- `refreshToken` (str, optional): Refresh token for token renewal.
- `codeVerifier` (str, optional): Code verifier for PKCE authentication.
- `language` (str, optional): The language for the request.

**Returns:**
- `dict`: JSON response containing access and refresh tokens.

###### Example:

```python
token_response = auth.getToken(
    grantType="authorization_code",
    code="auth_code",
    redirectURI="http://localhost/callback",
    clientID="client123",
    codeVerifier="verifier123"
)
print(token_response)
```

### ChannelTypes

The `ChannelTypes` class provides methods to interact with OpenHAB's channel types, allowing retrieval of all available channel types, specific channel types by UID, and linkable item types.

#### Initialization

```python
from openhab import OpenHABClient, ChannelTypes

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
channelTypes = ChannelTypes(client)
```

#### Methods

##### `getAllChannelTypes(language: str = None, prefixes: str = None) -> list`

Retrieves all available channel types.

**Parameters:**
- `language` (str, optional): The preferred language for the response (`Accept-Language` header).
- `prefixes` (str, optional): A query parameter to filter channel types by prefix.

**Returns:**
- `list`: A list of available channel types.

###### Example:

```python
channels = channel_types.getAllChannelTypes(language="en", prefixes="zwave")
print(channels)
```

##### `getChannelTypeByUID(channelTypeUID: str, language: str = None) -> dict`

Retrieves details of a specific channel type by its UID.

**Parameters:**
- `channelTypeUID` (str): The unique identifier of the channel type.
- `language` (str, optional): The preferred language for the response.

**Returns:**
- `dict`: JSON response containing details of the specified channel type.

###### Example:

```python
channelDetails = channelTypes.getChannelTypeByUID("zwave:switch_binary", language="en")
print(channelDetails)
```

##### `getLinkableItemTypes(channelTypeUID: str) -> list`

Retrieves the item types that can be linked to a specified trigger channel type.

**Parameters:**
- `channelTypeUID` (str): The unique identifier of the channel type.

**Returns:**
- `list`: A list of item types that can be linked to the given channel type.

###### Example:

```python
linkableItems = channelTypes.getLinkableItemTypes("zwave:switch_binary")
print(linkableItems)
```

### ConfigDescriptions

The `ConfigDescriptions` class provides methods to interact with OpenHAB's configuration descriptions, allowing retrieval of all available descriptions and specific descriptions by URI.

#### Initialization

```python
from openhab import OpenHABClient, ConfigDescriptions

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
configDescriptions = ConfigDescriptions(client)
```

#### Methods

##### `getAllConfigDescriptions(language: str = None, scheme: str = None) -> list`

Retrieves all available configuration descriptions.

**Parameters:**
- `language` (str, optional): The preferred language for the response (`Accept-Language` header).
- `scheme` (str, optional): A query parameter to filter results by a specific scheme.

**Returns:**
- `list`: A list of available configuration descriptions.

###### Example:

```python
configs = configDescriptions.getAllConfigDescriptions(language="en", scheme="thing")
print(configs)
```

##### `getConfigDescriptionByUri(uri: str, language: str = None) -> dict`

Retrieves a specific configuration description by its URI.

**Parameters:**
- `uri` (str): The URI of the requested configuration description.
- `language` (str, optional): The preferred language for the response.

**Returns:**
- `dict`: JSON response containing details of the specified configuration description.

###### Example:

```python
configDetails = configDescriptions.getConfigDescriptionByURI("thing-type:zwave:device", language="en")
print(config_details)
```

### Discovery

The `Discovery` class provides methods to interact with OpenHAB's discovery service, allowing retrieval of all available bindings that support discovery and starting a discovery scan for specific bindings.

#### Initialization

```python
from openhab import OpenHABClient, Discovery

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
discovery = Discovery(client)
```

#### Methods

##### `getAllDiscoveryBindings() -> list`

Retrieves all bindings that support discovery.

**Returns:**
- `list`: A list of strings representing the bindings that support discovery.

###### Example:

```python
bindings = discovery.getAllDiscoveryBindings()
print(bindings)
```

##### `startBindingScan(bindingID: str) -> int`
Starts the asynchronous discovery process for a binding and returns the timeout duration in seconds.

**Parameters:**
- `bindingID` (str): The ID of the binding for which the discovery process is to be started.

**Returns:**
- `int`: Timeout duration of the discovery operation in seconds.

###### Example:

```python
timeout = discovery.startBindingScan("zwave")
print(timeout)
``` 

### Events

The `Events` class provides methods to interact with OpenHAB's event service. It allows you to retrieve various event streams, including item-related events, thing-related events, inbox events, and more.

#### Initialization

```python
from openhab import OpenHABClient, Events

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
events = Events(client)
```

#### Methods

##### `getAllEvents(topics: str = None) -> list`

Retrieves all available events, optionally filtered by topic.

**Parameters:**
- `topics` (str, optional): A comma-separated list of topics to filter the events by.

**Returns:**
- `list`: A SSE stream of events.

###### Example:

```python
events = events.getAllEvents(topics="openhab/items")
print(events)
```

##### `initiateStateTracker() -> str`

Initiates a new item state tracker connection.

**Returns:**
- `str`: The connection ID as a string.

###### Example:

```python
connectionID = events.initiateStateTracker()
print(connectionID)
```

##### `updateSSEConnectionItems(connectionID: str, items: list) -> str`

Changes the list of items an SSE connection will receive state updates for.

**Parameters:**
- `connectionID` (str): The ID of the existing connection.
- `items` (list): A list of item names to subscribe to for state updates.

**Returns:**
- `str`: A success message when the update is completed.

###### Example:

```python
successMessage = events.updateSSEConnectionItems(connectionID, ["item1", "item2"])
print(successMessage)
```

#### `ItemEvents` Class

The `ItemEvents` class allows you to retrieve events related to items.

##### `ItemEvent()`

Get all item-related events.

**Returns:**
- `list`: A SSE stream of item events.

##### `ItemAddedEvent(itemName: str = "*")`

Get events for added items.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of added item events.

##### `ItemRemovedEvent(itemName: str = "*")`

Get events for removed items.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of removed item events.

##### `ItemUpdatedEvent(itemName: str = "*")`

Get events for updated items.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of updated item events.

##### `ItemCommandEvent(itemName: str = "*")`

Get events for item commands.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of item command events.

##### `ItemStateEvent(itemName: str = "*")`

Get events for item state changes.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of item state events.

##### `ItemStatePredictedEvent(itemName: str = "*")`

Get events for predicted item state changes.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of predicted item state events.

##### `ItemStateChangedEvent(itemName: str = "*")`

Get events for item state changes.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").

**Returns:**
- `list`: A SSE stream of state changed events.

#### `ThingEvents` Class

The `ThingEvents` class allows you to retrieve events related to things.

##### `ThingAddedEvent(thingUID: str = "*")`

Get events for added things.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of added thing events.

##### `ThingRemovedEvent(thingUID: str = "*")`

Get events for removed things.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of removed thing events.

##### `ThingUpdatedEvent(thingUID: str = "*")`

Get events for updated things.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of updated thing events.

##### `ThingStatusInfoEvent(thingUID: str = "*")`

Get events for thing status information.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of status information events.

##### `ThingStatusInfoChangedEvent(thingUID: str = "*")`

Get events for thing status information changes.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of status changed events.

#### `InboxEvents` Class

The `InboxEvents` class allows you to retrieve events related to things in the inbox.

##### `InboxAddedEvent(thingUID: str = "*")`

Get events for added things in the inbox.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of added inbox events.

##### `InboxRemovedEvent(thingUID: str = "*")`

Get events for removed things in the inbox.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of removed inbox events.

##### `InboxUpdatedEvent(thingUID: str = "*")`

Get events for updated things in the inbox.

**Parameters:**
- `thingUID` (str, optional): The UID of the thing (default is "*").

**Returns:**
- `list`: A SSE stream of updated inbox events.

#### `LinkEvents` Class

The `LinkEvents` class allows you to retrieve events related to item-channel links.

##### `ItemChannelLinkAddedEvent(itemName: str = "*", channelUID: str = "*")`

Get events for added item-channel links.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").
- `channelUID` (str, optional): The UID of the channel (default is "*").

**Returns:**
- `list`: A SSE stream of added item-channel link events.

##### `ItemChannelLinkRemovedEvent(itemName: str = "*", channelUID: str = "*")`

Get events for removed item-channel links.

**Parameters:**
- `itemName` (str, optional): The name of the item (default is "*").
- `channelUID` (str, optional): The UID of the channel (default is "*").

**Returns:**
- `list`: A SSE stream of removed item-channel link events.

#### `ChannelEvents` Class

The `ChannelEvents` class allows you to retrieve events related to channel descriptions and triggers.

##### `ChannelDescriptionChangedEvent(channelUID: str = "*")`

Get events for changes in channel descriptions.

**Parameters:**
- `channelUID` (str, optional): The UID of the channel (default is "*").

**Returns:**
- `list`: A SSE stream of channel description changed events.

##### `ChannelTriggeredEvent(channelUID: str = "*")`

Get events for triggered channels.

**Parameters:**
- `channelUID` (str, optional): The UID of the channel (default is "*").

**Returns:**
- `list`: A SSE stream of triggered channel events.

### Iconsets

The `Iconsets` class provides methods to interact with OpenHAB's icon sets. It allows you to retrieve all available icon sets, optionally filtered by language.

#### Initialization

```python
from openhab import OpenHABClient, Iconsets

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
iconsets = Iconsets(client)
```

#### Methods

##### `getAllIconsets(language: str = None) -> list`

Gets all icon sets, optionally filtered by language.

**Parameters:**
- `language` (str, optional): An optional language preference for the response (e.g., 'en', 'de').

**Returns:**
- `list`: A list of icon sets with details such as ID, label, description, and supported formats.

###### Example:

```python
iconsets = iconsets.getAllIconsets(language="en")
print(iconsets)
```

### Inbox

The `Inbox` class provides methods to interact with the inbox of discovered things in OpenHAB. It allows you to retrieve all discovered things, approve or ignore discovery results, and remove entries from the inbox.

#### Initialization

```python
from openhab import OpenHABClient, Inbox

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
inbox = Inbox(client)
```

#### Methods

##### `getAllDiscoveredThings(includeIgnored: bool = True) -> list`

Gets all discovered things, optionally including ignored ones.

**Parameters:**
- `includeIgnored` (bool, optional): Whether ignored entries should also be included. Defaults to `True`.

**Returns:**
- `list`: A list of discovered things with details such as UID, flag, label, and properties.

###### Example:

```python
discoveredThings = inbox.getAllDiscoveredThings()
print(discoveredThings)
```

##### `removeDiscoveryResult(thingUID: str) -> dict`

Removes a discovery result from the inbox.

**Parameters:**
- `thingUID` (str): The UID of the discovered thing to be removed.

**Returns:**
- `dict`: The API response to the delete request.

###### Example:

```python
response = inbox.removeDiscoveryResult("someThingUID")
print(response)
```

##### `approveDiscoveryResult(thingUID: str, thingLabel: str, newThingID: str = None, language: str = None) -> dict`

Approves the discovery result by adding the thing to the registry.

**Parameters:**
- `thingUID` (str): The UID of the discovered thing.
- `thingLabel` (str): The new name of the thing.
- `newThingID` (str, optional): The new thing ID.
- `language` (str, optional): The language preference for the response.

**Returns:**
- `dict`: The API response to the approval request.

###### Example:
```python
response = inbox.approveDiscoveryResult("someThingUID", "NewThingLabel")
print(response)
```

##### `ignoreDiscoveryResult(thingUID: str) -> dict`

Flags a discovery result as ignored for further processing.

**Parameters:**
- `thingUID` (str): The UID of the discovered thing.

**Returns:**
- `dict`: The API response to the ignore request.

###### Example:

```python
response = inbox.ignoreDiscoveryResult("someThingUID")
print(response)
```

##### `unignoreDiscoveryResult(thingUID: str) -> dict`

Removes the ignore flag from a discovery result.

**Parameters:**
- `thingUID` (str): The UID of the discovered thing.

**Returns:**
- `dict`: The API response to the unignore request.

###### Example:

```python
response = inbox.unignoreDiscoveryResult("someThingUID")
print(response)
```

### Items

The `Items` class provides methods for managing OpenHAB items via the REST API. It enables the retrieval, addition, updating and deletion of items as well as the management of tags, metadata and statuses.

#### **Initilization**

```python
from openhab import OpenHABClient, Items

client = OpenHABClient("http://openhab-server:8080", username="user", password="pass")
items = Items(client)
```

#### **Methoden**

##### `getAllItems(...) -> list`

Retrieves all available items.

**Parameter:**
- `language` (str, optional): Language filter for the header `Accept-Language`.
- `type` (str, optional): Item type filter.
- `tags` (str, optional): Item tag filter.
- `metadata` (str, optional): Metadata selector (default: `.*`).
- `recursive` (bool, optional): Should group members be retrieved recursively? (Default: `False`).
- `fields` (str, optional): Limitation to certain fields (comma-separated).
- `staticDataOnly` (bool, optional): Only return cached data? (Default: `False`).

**Example:**

```python
allItems = items.getAllItems(language="de", type="Switch")
print(allItems)
```

##### `addOrUpdateItems(items: list) -> dict`

Adds a list of items or updates existing ones.

**Parameter:**
- `items` (list): List of items as a dictionary.

**Example:**

```python
new_items = [{"name": "NewLight", "type": "Switch"}]
response = items.addOrUpdateItems(new_items)
print(response)
```

##### `getItem(itemName: str, ...) -> dict`

Gets the details of a single item.

**Parameter:**
- `itemName` (str): Name of the item.
- `language`, `metadata`, `recursive` (see `getAllItems`).

**Example:**

```python
itemData = items.getItem("LivingRoomLight")
print(itemData)
```

##### `addOrUpdateItem(itemName: str, itemData: dict, ...) -> dict`

Adds or updates an item.

**Parameter:**
- `itemName` (str): Name of the item.
- `itemData` (dict): Data of the item.
- `language` (str, optional).

**Example:**

```python
newItem = {"type": "Switch", "label": "New Light"}
response = items.addOrUpdateItem("NewLight", newItem)
print(response)
```

##### `sendCommand(itemName: str, command: str) -> dict`

Sends a command to an item.

**Example:**

```python
response = items.sendCommand("LivingRoomLight", "ON")
print(response)
```

##### `postUpdate(itemName: str, state: str) -> dict`

Updates the status of an item.

**Example:**

```python
response = items.postUpdate("LivingRoomLight", "OFF")
print(response)
```

##### `deleteItem(itemName: str) -> dict`

Deletes an item from the registry.

**Example:**

```python
response = items.deleteItem("OldItem")
print(response)
```

##### `addGroupMember(itemName: str, memberItemName: str) -> dict`

Adds an item to a group.

**Example:**

```python
response = items.addGroupMember("LivingRoomGroup", "NewLight")
print(response)
```

##### `removeGroupMember(itemName: str, memberItemName: str) -> dict`

Removes an item from a group.

**Example:**
```python
response = items.removeGroupMember("LivingRoomGroup", "OldLight")
print(response)
```

##### `addMetadata(itemName: str, namespace: str, metadata: dict) -> dict`

Adds metadata to an item.

**Example:**

```python
metadata = {"value": "20", "config": {"unit": "°C"}}
response = items.addMetadata("Thermostat", "temperature", metadata)
print(response)
```

##### `removeMetadata(itemName: str, namespace: str) -> dict`

Removes metadata from an item.

**Example:**

```python
response = items.removeMetadata("Thermostat", "temperature")
print(response)
```

##### `getMetadataNamespaces(itemName: str, ...) -> list`

Returns the metadata namespace of an item.

**Example:**

```python
namespaces = items.getMetadataNamespaces("Thermostat")
print(namespaces)
```

##### `getSemanticItem(itemName: str, semanticClass: str, ...) -> dict`

Returns the item of a specific semantic class.

**Example:**

```python
semanticItem = items.getSemanticItem("Thermostat", "Point")
print(semanticItem)
```

##### `getItemState(itemName: str) -> dict`

Gets the current status of an item.

**Example:**

```python
state = items.getItemState("LivingRoomLight")
print(state)
```

##### `updateItemState(itemName: str, state: str, ...) -> dict`

Updates the status of an item.

**Example:**

```python
response = items.updateItemState("LivingRoomLight", "ON")
print(response)
```

##### `addTag(itemName: str, tag: str) -> dict`

Adds a tag to an item.

**Example:**
```python
response = items.addTag("LivingRoomLight", "Lighting")
print(response)
```

##### `removeTag(itemName: str, tag: str) -> dict`

Removes a tag from an item.

**Example:**

```python
response = items.removeTag("LivingRoomLight", "Lighting")
print(response)
```

##### `purgeOrphanedMetadata() -> dict`

Deletes unused metadata.

**Example:**

```python
response = items.purgeOrphanedMetadata()
print(response)
```

### Links

The `Links` class provides methods to manage links between items and channels in OpenHAB via the REST API.

#### Methods

##### `getAllLinks(channelUID: str = None, itemName: str = None) -> list`

Retrieves all available links.

- `channelUID` *(optional, str)* – Filters by the Channel UID.  
- `itemName` *(optional, str)* – Filters by the Item Name.  

**Returns:** A list of links containing details such as `itemName`, `channelUID`, and configuration.  

##### `getIndividualLink(itemName: str, channelUID: str) -> dict`

Retrieves a specific link between an item and a channel.

- `itemName` *(str)* – The name of the item.  
- `channelUID` *(str)* – The UID of the channel.  

**Returns:** A dictionary containing details of the link, including the item, channel UID, and configuration.  

##### `linkItemToChannel(itemName: str, channelUID: str, configuration: dict) -> dict`

Creates a link between an item and a channel.

- `itemName` *(str)* – The name of the item.  
- `channelUID` *(str)* – The UID of the channel.  
- `configuration` *(dict)* – The configuration parameters for the link.  

**Returns:** The API response confirming the link creation.  

##### `unlinkItemFromChannel(itemName: str, channelUID: str) -> dict`

Removes a link between an item and a channel.

- `itemName` *(str)* – The name of the item.  
- `channelUID` *(str)* – The UID of the channel.  

**Returns:** The API response confirming the link removal.  

##### `deleteAllLinks(object: str) -> dict`

Deletes all links that refer to a specific item or thing.

- `object` *(str)* – The name of the item or the UID of the thing.  

**Returns:** The API response confirming the deletion.  

##### `getOrphanLinks() -> list`

Retrieves orphaned links, which refer to items connected to non-existent or broken channels.

**Returns:** A list of orphaned links.

##### `purgeUnusedLinks() -> dict`

Removes all unused or orphaned links.

**Returns:** The API response confirming the removal.  

### Logging

The `Logging` class provides methods to manage loggers in OpenHAB via the REST API.

#### Methods

##### `getAllLoggers() -> dict`

Retrieves all available loggers.

**Returns:** A dictionary containing all loggers with their names and logging levels.  

##### `getSingleLogger(loggerName: str) -> dict`

Retrieves a specific logger.

- `loggerName` *(str)* – The name of the logger.