WattsonClient#

class wattson.cosimulation.control.interface.wattson_client.WattsonClient(query_server_socket_string: str = 'tcp://127.0.0.1:51000', publish_server_socket_string: str = 'tcp://127.0.0.1:51001', client_name: str = 'generic-client', namespace: str | Namespace | None = None, wait_for_namespace: bool = False, wattson_socket_ip: str | None = None)#

Bases: Thread

WattsonClient is a threading-based Python client for connecting to a Wattson Co-Simulation environment. It provides mechanisms for handling queries, publishing notifications, and managing communication with the Wattson server.

Example

wattson_client = WattsonClient(client_name="test_application", namespace="auto", wait_for_namespace=True)
wattson_client.register() (Default value = None)
response = wattson_client.query(
    query=WattsonQuery(query_type=WattsonQueryType.ECHO)),
    block=True
)
print(response.is_successful())

Methods

`__init__`	Creates a new WattsonClient instance to connect to a running Wattson Co-Simulation.
`async_query`	Performs a query, but explicitly does not block.
`event_clear`	Clears the specified event and sends an asynchronous query to clear it.
`event_is_known`	Checks if the given event name is in the list of known events.
`event_is_set`	Checks if the specified event is set.
`event_set`	Sets an event by its name and initiates an asynchronous query to confirm the event's status.
`event_wait`	Waits for an event with the specified name to be set or until the timeout is reached.
`get_notification_history`
`get_remote_network_emulator`
`get_remote_network_interface`
`get_remote_network_interface_by_id`
`get_remote_network_link`
`get_remote_network_links`
`get_remote_network_node`
`get_remote_network_nodes`
`get_remote_service`	Returns a remote representation of a WattsonService existing in the simulation.
`get_simulators`
`get_wattson_time`	Retrieves the current WattsonTime from the WattsonServer.
`has_simulator`
`node_action`	Handles commands related to nodes such as starting or stopping their associated services.
`notify`	Sends the specified notification object to the server to be forwarded to all subscribed clients.
`on_receive_notification`	Handles the receipt of a notification and invokes appropriate callbacks based on the subscription topic.
`primitive_query`	Executes a primitive query by creating a WattsonQuery object, setting its type and data, and passing it to the query handler.
`query`	Handles a query by placing it into a queue for processing and optionally blocking until a response is obtained.
`register`	Registers this client with the server based on the given ID, indicating its connection and availability.
`request_shutdown`	Requests a co-simulation shutdown.
`require_connection`	Waits for the connection to the server to be established by repeatedly sending ECHO requests.
`run`	Method representing the thread's activity.
`set_wattson_time`	Sets the Wattson time by creating and sending a WattsonQuery of type SET_TIME.
`start`	Start the thread's activity.
`stop`
`subscribe`	Subscribes a callback function to a specific topic.
`unsubscribe_all`	Removes all subscriptions for all topics for this client.
`unsubscribe_topic`	param topic: The topic to unsubscribe from, provided as a string. This will clear all subscriptions associated with the specified topic.

Attributes

`client_id`	The system-wide unique identifier of this client.
`is_registered`
`is_started`
`name`	The user-defined name of this client.

__init__(query_server_socket_string: str = 'tcp://127.0.0.1:51000', publish_server_socket_string: str = 'tcp://127.0.0.1:51001', client_name: str = 'generic-client', namespace: str | Namespace | None = None, wait_for_namespace: bool = False, wattson_socket_ip: str | None = None)#

Creates a new WattsonClient instance to connect to a running Wattson Co-Simulation.

Parameters:

query_server_socket_string (str, optional) – The socket to connect to for query handling. Defaults to localhost.
publish_server_socket_string (str, optional) – The socket to connect to for notification handling. Defaults to localhost.
client_name (str, optional) – A name of the client. (Default value = “generic-client”)
namespace (Optional[Union[str, Namespace]], optional) – If given, the client moves itself to a Networking Namespace. This allows you to use the client from outside the simulation (i.e., without direct access to the management network). It can either be the name of the networking namespace or the corresponding Namespace object. Use ``auto`` to move the client to Wattson’s primary namespace - this is most likely what you want to do (Default value = None)
wait_for_namespace (bool, optional) – If True, the client waits for the namespace to exist. This is useful if the WattsonClient is instantiated during the startup of the Co-Simulation. (Default value = False)
wattson_socket_ip (Optional[str], optional) – Instead of providing individual socket strings, the IP of the server can be passed. This overrides both socket_string parameters! (Default value = None)

async_query(query: WattsonQuery) → WattsonResponsePromise#

Performs a query, but explicitly does not block. Shorthand with correct type hint for query(query, block=False)

Parameters:: query (WattsonQuery) –

property client_id: str | None#: The system-wide unique identifier of this client. This is given by the WattsonServer.

event_clear(event_name: str)#

Clears the specified event and sends an asynchronous query to clear it.

Parameters:: event_name (str) – The name of the event to clear.

event_is_known(event_name: str) → bool#

Checks if the given event name is in the list of known events.

Parameters:: event_name (str) – The name of the event to check.
Returns:: True if the event name is known, otherwise False.
Return type:: bool

event_is_set(event_name: str) → bool#

Checks if the specified event is set.

Parameters:: event_name (str) – The name of the event to check.
Returns:: A boolean indicating whether the event is set.

event_set(event_name: str)#

Sets an event by its name and initiates an asynchronous query to confirm the event’s status.

Parameters:: event_name (str) – The name of the event to set.

event_wait(event_name: str, timeout: float | None = None) → bool#

Waits for an event with the specified name to be set or until the timeout is reached.

Parameters:

event_name (str) – Name of the event to wait for.
timeout (Optional[float], optional) – Maximum time in seconds to wait for the event. If None, waits indefinitely. (Default value = None)

Returns:

True if the event is set, False if the timeout is reached before the event is set.

Return type:

bool

get_remote_service(service_id: int) → WattsonRemoteService#

Returns a remote representation of a WattsonService existing in the simulation.

Parameters:: service_id (int) – The ID of the service to return.
Returns:: The WattsonRemoteService instance.
Return type:: WattsonRemoteService

get_wattson_time(enable_synchronization: bool = False) → WattsonTime#

Retrieves the current WattsonTime from the WattsonServer.

Parameters:: enable_synchronization (bool, optional) – If set to True, the returned WattsonTime instance will enable synchronization with the central WattsonTime from the server. (Default value = False)
Returns:: A WattsonTime instance representing the current time from the WattsonServer.
Raises:: WattsonClientException – If the time could not be retrieved successfully from the WattsonServer.

property name: str#: The user-defined name of this client.

node_action(entity_id: str, action: str, block: bool = True) → bool | WattsonResponsePromise#

Handles commands related to nodes such as starting or stopping their associated services.

Parameters:

entity_id (str) – The entity ID of the node
action (str) – The action to perform.
block (bool, optional) – Whether to block while waiting for a response. (Default value = True)

Returns:

A boolean indicating the queries success if block is True, else a WattsonResponsePromise: to resolve later on

Return type:

Union[bool,WattsonResponsePromise]

notify(notification: WattsonNotification) → bool#

Sends the specified notification object to the server to be forwarded to all subscribed clients.

Parameters:: notification (WattsonNotification) – The notification object to be sent.
Returns:: True if the notification was sent successfully, False otherwise.
Return type:: bool

on_receive_notification(notification: WattsonNotification)#

Handles the receipt of a notification and invokes appropriate callbacks based on the subscription topic.

Parameters:: notification (WattsonNotification) – An instance of WattsonNotification containing the notification’s details. The notification includes a list of recipients and a notification topic. If the message contains a wildcard recipient “*” or matches the client’s ID, the notification is processed. Otherwise, it is ignored.

primitive_query(query_type: str, query_data: Any, block: bool = True) → WattsonResponse#

Executes a primitive query by creating a WattsonQuery object, setting its type and data, and passing it to the query handler.

Parameters:

query_type (str) – The type of the query to be executed.
query_data (Any) – The data or payload associated with the query.
block (bool, optional) – A flag indicating whether the query should be executed in blocking mode. Defaults to True.

Returns:

The response generated after executing the query.

Return type:

WattsonResponse

query(query: WattsonQuery, block: bool = True) → WattsonResponse#

Handles a query by placing it into a queue for processing and optionally blocking until a response is obtained.

Parameters:

query (WattsonQuery) – An instance of WattsonQuery containing the query to be processed.
block (bool, optional) – A boolean indicating whether the method should wait for the query response or return immediately. (Default value = True)

Returns:

If block is True, returns a WattsonResponse containing the result of the processed query.: If the query fails or the client shuts down during processing, returns a FailedQueryResponse. If block is False, returns a WattsonResponsePromise that allows tracking the query’s completion status asynchronously.

register(client_name: str | None = None, force_new_id: bool = False) → bool#

Registers this client with the server based on the given ID, indicating its connection and availability. Returns True, iff the registration is acknowledged.

Parameters:

client_name (Optional[str], optional) – If given, the current name of this client will be changed. (Default value = None)
force_new_id (bool, optional) – If True, the client explicitly requests a new ID (even if already registered). (Default value = False)

Returns:

True iff the registration was successful.

Return type:

bool

request_shutdown() → bool#

Requests a co-simulation shutdown.

This method sends a shutdown request query to the Wattson CoSimulationController and returns whether the request was successful.

Returns:: True if the shutdown request was successful, False otherwise.
Return type:: bool

require_connection(timeout_seconds: float | None = None) → bool#

Waits for the connection to the server to be established by repeatedly sending ECHO requests. When a timeout is given, the attempt to connect is stopped after this interval. When the connection is not established after the timeout, a TimeoutError is raised. Otherwise, the function returns with no return value or Exception.

This function regularly checks for termination requests and stops its blocking behavior accordingly.

Parameters:: timeout_seconds (Optional[float], optional) – (Default value = None)

run() → None#

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

set_wattson_time(wattson_time: WattsonTime) → bool#

Sets the Wattson time by creating and sending a WattsonQuery of type SET_TIME.

Parameters:: wattson_time ('WattsonTime') – A WattsonTime object representing the time to be set. It is copied safely before being included in the query.
Returns:: True if the operation was successful, False otherwise.
Return type:: bool

start(timeout: float | None = None) → None#

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

subscribe(topic: str, callback: Callable[[WattsonNotification], None])#

Subscribes a callback function to a specific topic. When a notification for the topic is received, the callback function will be executed.

Parameters:

topic (str) – The name of the topic to subscribe to.
callback (Callable[[WattsonNotification], None]) – The function to be executed when a notification for the subscribed topic is received. Receives a WattsonNotification as its argument.

unsubscribe_all()#: Removes all subscriptions for all topics for this client.

unsubscribe_topic(topic: str)#

Parameters:: topic (str) – The topic to unsubscribe from, provided as a string. This will clear all subscriptions associated with the specified topic.