Connections

Multiple protocols and APIs are supported by eta_utility. Most functionality is common to all connectors, some of the connectors also offer specific functionality, which only applies to the protocol or API they implement.

A simple example using the EnEffCo connection:

# Create the connection object
connection = EnEffCoConnection.from_ids(
    ["CH1.Elek_U.L1-N", "Pu3.425.ThHy_Q"],
    url="https://someurl.com/",
    usr="username",
    pwd="password",
    api_token="your_server_auth_token",
)

# Read series data within a specified time interval
from_time = datetime.fromisoformat("2019-01-01 00:00:00")
to_time = datetime.fromisoformat("2019-01-02 00:00:00")
data = connection.read_series(from_time, to_time, interval=900)

class eta_utility.connectors.OpcUaConnection(url: str, usr: str | None = None, pwd: str | None = None, *, nodes: Nodes | None = None, key_cert: KeyCertPair | None = None, **kwargs: Any)[source]

The OPC UA Connection class allows reading and writing from and to OPC UA servers. Additionally, it implements a subscription method, which reads continuously in a specified interval.

Parameters:

url – URL of the OPC UA Server.
usr – Username in OPC UA for login.
pwd – Password in OPC UA for login.
nodes – List of nodes to use for all operations.

classmethod from_ids(ids: Sequence[str], url: str, usr: str | None = None, pwd: str | None = None) → OpcUaConnection[source]

Initialize the connection object from an OPC UA protocol through the node IDs.

Parameters:

ids – Identification of the Node.
url – URL for connection.
usr – Username in OPC UA for login.
pwd – Password in OPC UA for login.

Returns:

OpcUaConnection object.

read(nodes: Nodes | None = None) → pd.DataFrame[source]

Read some manually selected values from OPC UA capable controller.

Parameters:: nodes – List of nodes to read from.
Returns:: pandas.DataFrame containing current values of the OPC UA-variables.
Raises:: ConnectionError – When an error occurs during reading.

write(values: Mapping[AnyNode, Any]) → None[source]

Writes some manually selected values on OPC UA capable controller.

Parameters:: values – Dictionary of nodes and data to write {node: value}.
Raises:: ConnectionError – When an error occurs during reading.

create_nodes(nodes: Nodes) → None[source]

Create nodes on the server from a list of nodes. This will try to create the entire node path.

Parameters:: nodes – List or set of nodes to create.
Raises:: ConnectionError – When an error occurs during node creation.

delete_nodes(nodes: Nodes) → None[source]

Delete the given nodes and their parents (if the parents do not have other children).

Parameters:: nodes – List or set of nodes to be deleted.
Raises:: ConnectionError – If deletion of nodes fails.

subscribe(handler: SubscriptionHandler, nodes: Nodes | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. Basic architecture of the subscription is the client- server communication via subscription notify. This function works asynchronously. Subscriptions must always be closed using the close_sub function (use try, finally!).

Parameters:

nodes – Identifiers for the nodes to subscribe to.
handler – SubscriptionHandler object with a push method that accepts node, value pairs.
interval – Interval for receiving new data. It is interpreted as seconds when given as an integer.

close_sub() → None[source]: Close an open subscription.

class eta_utility.connectors.ModbusConnection(url: str, usr: str | None = None, pwd: str | None = None, *, nodes: Nodes | None = None)[source]

The Modbus Connection class allows reading and writing from and to Modbus servers and clients. Additionally, it implements a subscription service, which reads continuously in a specified interval.

Parameters:

url – URL of the Modbus Server.
usr – No login supported, only here to satisfy the interface
pwd – No login supported, only here to satisfy the interface
nodes – List of nodes to use for all operations.

read(nodes: Nodes | None = None) → pd.DataFrame[source]

Read some manually selected nodes from Modbus server.

Parameters:: nodes – List of nodes to read from.
Returns:: Dictionary containing current values of the Modbus variables.

write(values: Mapping[AnyNode, Any]) → None[source]

Write some manually selected values on Modbus capable controller.

Warning

This is not implemented.

Parameters:: values – Dictionary of nodes and data to write {node: value}.

subscribe(handler: SubscriptionHandler, nodes: Nodes | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. Basic architecture of the subscription is the client- server communication. This function works asynchronously.

Parameters:

nodes – Identifiers for the nodes to subscribe to.
handler – SubscriptionHandler object with a push method that accepts node, value pairs.
interval – Interval for receiving new data. It is interpreted as seconds when given as an integer.

close_sub() → None[source]: Close the subsription.

class eta_utility.connectors.EnEffCoConnection(url: str, usr: str | None, pwd: str | None, *, api_token: str, nodes: Nodes | None = None)[source]

EnEffCoConnection is a class to download and upload multiple features from and to the EnEffCo database as timeseries.

Parameters:

url – URL of the server with scheme (https://).
usr – Username in EnEffco for login.
pwd – Password in EnEffco for login.
api_token – Token for API authentication.
nodes – Nodes to select in connection.

API_PATH: str = '/API/v1.0'

classmethod from_ids(ids: Sequence[str], url: str, usr: str, pwd: str, api_token: str) → EnEffCoConnection[source]

Initialize the connection object from an EnEffCo protocol through the node IDs

Parameters:

ids – Identification of the Node.
url – URL for EnEffco connection.
usr – Username for EnEffCo login.
pwd – Password for EnEffCo login.
api_token – Token for API authentication.

Returns:

EnEffCoConnection object.

read(nodes: Nodes | None = None) → pd.DataFrame[source]

Download current value from the EnEffCo Database

Parameters:: nodes – List of nodes to read values from.
Returns:: pandas.DataFrame containing the data read from the connection.

write(values: Mapping[AnyNode, Any] | pd.Series[datetime, Any], time_interval: timedelta | None = None) → None[source]

Writes some values to the EnEffCo Database

Parameters:

values – Dictionary of nodes and data to write {node: value}.
time_interval – Interval between datapoints (i.e. between “From” and “To” in EnEffCo Upload) (default 1s).

read_info(nodes: Nodes | None = None) → pd.DataFrame[source]

Read additional datapoint information from Database.

Parameters:: nodes – List of nodes to read values from.
Returns:: pandas.DataFrame containing the data read from the connection.

subscribe(handler: SubscriptionHandler, nodes: Nodes | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. This will return only the last available values.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs.
interval – Interval for receiving new data. It is interpreted as seconds when given as an integer.
nodes – Identifiers for the nodes to subscribe to.

read_series(from_time: datetime, to_time: datetime, nodes: Nodes | None = None, interval: TimeStep = 1, **kwargs: Any) → pd.DataFrame[source]

Download timeseries data from the EnEffCo Database

Parameters:

nodes – List of nodes to read values from.
from_time – Starting time to begin reading (included in output).
to_time – Time to stop reading at (not included in output).
interval – Interval between time steps. It is interpreted as seconds if given as integer.
kwargs – Other parameters (ignored by this connector).

Returns:

Pandas DataFrame containing the data read from the connection.

subscribe_series(handler: SubscriptionHandler, req_interval: TimeStep, offset: TimeStep | None = None, nodes: Nodes | None = None, interval: TimeStep = 1, data_interval: TimeStep = 1, **kwargs: Any) → None[source]

Subscribe to nodes and call handler when new data is available. This will always return a series of values. If nodes with different intervals should be subscribed, multiple connection objects are needed.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs.
req_interval – Duration covered by requested data (time interval). Interpreted as seconds if given as int.
offset – Offset from datetime.now from which to start requesting data (time interval). Interpreted as seconds if given as int. Use negative values to go to past timestamps.
data_interval – Time interval between values in returned data. Interpreted as seconds if given as int.
interval – interval (between requests) for receiving new data. It is interpreted as seconds when given as an integer.
nodes – Identifiers for the nodes to subscribe to.
kwargs – Other, ignored parameters.

close_sub() → None[source]: Close an open subscription.

id_from_code(code: str, raw_datapoint: bool = False) → str[source]

Function to get the raw EnEffCo ID corresponding to a specific (raw) datapoint

Parameters:

code – Exact EnEffCo code.
raw_datapoint – Returns raw datapoint ID.

timestr_from_datetime(dt: datetime) → str[source]

Create an EnEffCo compatible time string.

Parameters:: dt – Datetime object to convert to string.
Returns:: EnEffCo compatible time string.

usr: str | None: Username fot login to server

pwd: str | None: Password for login to server

exc: BaseException | None

An example using the ENTSO-E connection:

# Define your ENTSO-E Token
entsoe_token = ""

# Check out NodeEntsoE documentation for endpoint and bidding zone information
node = Node(
    "CH1.Elek_U.L1-N",
    "https://transparency.entsoe.eu/",
    "entsoe",
    endpoint="Price",
    bidding_zone="DEU-LUX",
)

# start connection from one or multiple nodes
server = ENTSOEConnection.from_node(node, api_token=entsoe_token)

# Define time interval as datetime values
from_datetime = datetime.strptime("2022-02-15T13:18:12", "%Y-%m-%dT%H:%M:%S")
to_datetime = datetime.strptime("2022-02-15T14:00:00", "%Y-%m-%dT%H:%M:%S")

# read_series will request data from specified connection and time interval
# The DataFrame will have index with time delta of the specified interval in seconds
if isinstance(server, ENTSOEConnection):
    df = server.read_series(from_time=from_datetime, to_time=to_datetime, interval=1)
else:
    raise TypeError("The connection must be an ENTSOEConnection, to be able to call read_series.")

class eta_utility.connectors.ENTSOEConnection(url: str = 'https://web-api.tp.entsoe.eu/', *, api_token: str, nodes: Nodes | None = None)[source]

ENTSOEConnection is a class to download and upload multiple features from and to the ENTSO-E transparency platform database as timeseries. The platform contains data about the european electricity markets.

Parameters:

url – Url of the server with scheme (https://web-api.tp.entsoe.eu/)
usr – Username for login to the platform (usually not required - default: None)
pwd – Password for login to the platform (usually not required - default: None)
api_token – Token for API authentication
nodes – Nodes to select in connection

API_PATH: str = '/api'

read(nodes: Nodes | None = None) → pd.DataFrame[source]

Warning

Cannot read single values from ENTSO-E transparency platform. Use read_series instead

Parameters:: nodes – List of nodes to read values from
Returns:: Pandas DataFrame containing the data read from the connection

write(values: Mapping[AnyNode, Mapping[datetime, Any]], time_interval: timedelta | None = None) → None[source]

Warning

Cannot write to ENTSO-E transparency platform.

Parameters:

values – Dictionary of nodes and data to write. {node: value}
time_interval – Interval between datapoints (i.e. between “From” and “To” in EnEffCo Upload), default 1s

subscribe(handler: SubscriptionHandler, nodes: Nodes | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. This will return only the last available values.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs
interval – interval for receiving new data. It is interpreted as seconds when given as an integer.
nodes – identifiers for the nodes to subscribe to

read_series(from_time: datetime, to_time: datetime, nodes: Nodes | None = None, interval: TimeStep = 1, **kwargs: Any) → pd.DataFrame[source]

Download timeseries data from the ENTSO-E Database

Parameters:

nodes – List of nodes to read values from
from_time – Starting time to begin reading (included in output)
to_time – Time to stop reading at (not included in output)
interval – interval between time steps. It is interpreted as seconds if given as integer.

Returns:

Pandas DataFrame containing the data read from the connection

subscribe_series(handler: SubscriptionHandler, req_interval: TimeStep, offset: TimeStep | None = None, nodes: Nodes | None = None, interval: TimeStep = 1, data_interval: TimeStep = 1, **kwargs: Any) → None[source]

Warning

Not implemented: Cannot subscribe to data from the ENTSO-E transparency platform.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs
req_interval – Duration covered by requested data (time interval). Interpreted as seconds if given as int
offset – Offset from datetime.now from which to start requesting data (time interval). Interpreted as seconds if given as int. Use negative values to go to past timestamps.
data_interval – Time interval between values in returned data. Interpreted as seconds if given as int.
interval – interval (between requests) for receiving new data. It it interpreted as seconds when given as an integer.
nodes – identifiers for the nodes to subscribe to

close_sub() → None[source]: Warning

Not implemented: Cannot subscribe to data from the ENTSO-E transparency platform.

usr: str | None: Username fot login to server

pwd: str | None: Password for login to server

exc: BaseException | None