<!-- HILSTER htf 4.3.1 -->
**htf 4.3.1** · [HTML](../xentara.html) · [Complete PDF manual](../_downloads/htf-4.3.1.pdf)

<a id="xentara"></a>

# Xentara — Real-Time Automation Platform

## Introduction

Xentara is a modular, secure and powerful Real-Time Automation Platform.
You can find more information at the [Xentara website](https://xentara.io).

`htf` includes a websocket-client to interact with the Xentara runtime.
Thus, users can for example deploy tests on their machines and execute tests remotely.

The Xentara-client is async-only.

## Open a Connection

To open a connection, instantiate [`XentaraClient`](#htf.xentara.XentaraClient) and await it.

```python
client = await XentaraClient(
    url="wss://xentara-host/api/ws",
    root_element="Hardware",
)
```

#### NOTE
Don’t forget the `await` statement!

Alternatively use [`create`](#htf.xentara.XentaraClient.create).

```python
client = await XentaraClient.create(
    url="wss://xentara-host/api/ws",
    root_element="Hardware",
)
```

The root element (`root_element`) must match the configuration Xentara was started with.
The contents are browsed and fetched automatically on instantiation.

## Authentication

The Xentara-client supports basic authentication.

The credentials are simply added to the url, i.e.:

```python
client = await XentaraClient(
    url="wss://<user>:<password>@xentara-host/api/ws",
)
```

where `<username>` is the username and `<password>` is the password to be used.

## TLS/SSL

Use `wss://` in the url for a TLS/SSL secured connection and `ws://` for an unsafe and unencrypted connection.

## Self-signed certificates

To disable the TLS/SSL certificate verification, just add `verify_ssl=False`.

```python
client = await XentaraClient(
    url="wss://<user>:<password>@xentara-host/api/ws",
    root_element="Hardware",
    verify_ssl=False,
)
```

## Close a Connection

To close an open connection, simply run:

```python
await client.close()
```

## Reading values

To read a value, call [`read`](#htf.xentara.XentaraClient.read):

```python
value = await client.read("<element>")
```

`<element>` is a descriptor of a Xentara element, for example `"Hardware.EtherCAT Bus.EL2624.Output 1"`.

In addition, the Xentara-client can be used like a dictionary to read values.

```python
value = await client["<element>"].read()
```

## Writing values

To write a value, call [`write`](#htf.xentara.XentaraClient.write):

```python
await client.write("<element>", value)
```

`<element>` is a descriptor of a Xentara element, for example `"Hardware.EtherCAT Bus.EL2624.Output 1"`.

The Xentara-client can be used like a dictionary to write values.

```python
await client["<element>"].write(value)
```

## Subscriptions

To subscribe to changes, use the `subscribe` function that returns a
[`Subscription`](#htf.xentara.Subscription).

The [`htf.xentara.Subscription`](#htf.xentara.Subscription) returns an async iterable that can be used in different ways.
Each iteration yields an [`Event`](#htf.xentara.Event).

The easiest way to use a subscription is:

```python
async with client.subscribe("<element>") as subscription:
    for i in range(5):
        event = await subscription.receive()
        value = event.value
        print(f"{i}: {event=}")
```

[`aiter`](https://docs.python.org/3/builtins/functions.html#aiter) can also be used explicitly:

```python
async with client.subscribe("<element>") as subscription:
    iterator = aiter(subscription)
    for i in range(5):
        event = await iterator.__anext__()
        value = event.value
        print(f"{i}: {event=}")
```

For an infinite number of received values, `async for` can be used.

```python
subscription = client.subscribe("<element>")

async with subscription as subscription:
    async for event in subscription:
        value = event.value
        print(f"{i}: {event=}")
```

## String Representation

The Xentara client can be printed to get information about it.

```python
print(client)
```

## Use the Client like a Dictionary

To get the available elements, the [`XentaraClient`](#htf.xentara.XentaraClient) can be used like a dictionary.

```python
keys = client.keys()
values = client.values()
items = client.items()
length = len(client)
```

## XentaraClient

### *class* htf.xentara.XentaraClient(url: [str](https://docs.python.org/3/builtins/stdtypes.html#str), root_element: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = 'Hardware', verify_ssl: [bool](https://docs.python.org/3/builtins/functions.html#bool) = True)

The Xentara websocket client.

* **Parameters:**
  * **url** – The url to connect to the Xentara server.
  * **root_element** – The root element to browse for elements. This is set in the Xentara configuration.
  * **verify_ssl** – if set to `False` TLS/SSL certificate verification is switched off. Default is `True`.

#### *async* close() → [None](https://docs.python.org/3/builtins/constants.html#None)

Close the connection.

#### *async* copy() → [XentaraClient](#htf.xentara.XentaraClient)

Return a copy of the instance with a new websocket connection.

#### *async classmethod* create(url: [str](https://docs.python.org/3/builtins/stdtypes.html#str), root_element: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = 'Hardware', verify_ssl: [bool](https://docs.python.org/3/builtins/functions.html#bool) = True) → [XentaraClient](#htf.xentara.XentaraClient)

Create the Xentara client. Is called when the class instance is awaited, too.

* **Parameters:**
  * **url** – The url to connect to the Xentara server.
  * **root_element** – The root element to browse for elements. This is set in the Xentara configuration.
  * **verify_ssl** – if set to `False` TLS/SSL certificate verification is switched off. Default is `True`.

#### *async* read(element: [str](https://docs.python.org/3/builtins/stdtypes.html#str)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Read the current value.

* **Returns:**
  the current value
* **Return type:**
  Any

#### subscribe(element: [str](https://docs.python.org/3/builtins/stdtypes.html#str), maximum_update_interval: [int](https://docs.python.org/3/builtins/functions.html#int) = 500, minimum_update_interval: [int](https://docs.python.org/3/builtins/functions.html#int) = 1000) → [Subscription](#htf.xentara.Subscription)

Create a subscription.

* **Parameters:**
  * **element** – The element to be subscribed.
  * **maximum_update_interval** – the maximum update interval in milliseconds (default: 500)
  * **minimum_update_interval** – the minimum update interval in milliseconds (default: 1000)
* **Returns:**
  the instance of the subscription
* **Return type:**
  [Subscription](#htf.xentara.Subscription)

#### *async* write(element: [str](https://docs.python.org/3/builtins/stdtypes.html#str), value: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Write a value.

* **Parameters:**
  **value** – the value to be written

## Element

### *class* htf.xentara.Element(client: [XentaraClient](#htf.xentara.XentaraClient), name: [str](https://docs.python.org/3/builtins/stdtypes.html#str))

An element to read and write values. Used when :class:~\`htf.xentara.XentaraClient\` is used like a dictionary.

#### *async* read() → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Read the current value.

* **Returns:**
  the current value
* **Return type:**
  Any

#### *async* write(value: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Write a value.

* **Parameters:**
  **value** – the value to be written

## Subscription

### *class* htf.xentara.Subscription(client: [XentaraClient](#htf.xentara.XentaraClient), element: [str](https://docs.python.org/3/builtins/stdtypes.html#str), maximum_update_interval: [int](https://docs.python.org/3/builtins/functions.html#int) = 500, minimum_update_interval: [int](https://docs.python.org/3/builtins/functions.html#int) = 1000)

Subscriptions for Xentara elements.

Users will never call this method directly.

* **Parameters:**
  * **client** – the current Xentara client’s instance (passed automatically)
  * **element** – the name of the element the subscription is for
  * **maximum_update_interval** – the maximum update interval in milliseconds (default: 500)
  * **minimum_update_interval** – the minimum update interval in milliseconds (default: 1000)

#### *async* receive() → [Event](#htf.xentara.Event)

Receive the next event in the subscription.

#### *async* start() → [None](https://docs.python.org/3/builtins/constants.html#None)

Start the subscription.

#### *async* stop() → [None](https://docs.python.org/3/builtins/constants.html#None)

Stop the subscription.

## Event

### *class* htf.xentara.Event(timestamp: [float](https://docs.python.org/3/builtins/functions.html#float), name: [str](https://docs.python.org/3/builtins/stdtypes.html#str), uuid: [UUID](https://docs.python.org/3/library/uuid.html#uuid.UUID), value: [Any](https://docs.python.org/3/library/typing.html#typing.Any))

Yielded in [`Subscription`](#htf.xentara.Subscription) when used as an async iterator.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

the name of the element

#### timestamp *: [float](https://docs.python.org/3/builtins/functions.html#float)*

the timestamp as a float

#### uuid *: [UUID](https://docs.python.org/3/library/uuid.html#uuid.UUID)*

the uuid of the element

#### value *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)*

the current value of the element
