Repository files navigation

This repository contains the Python client SDK forEclipse Ditto.

• Installation
• Creating and connecting a client
• Working with features
  • Creating a new feature instance
  • Modifying a feature's property
  • Deleting a feature's property
  • Deleting a feature
• Subscribing and handling messages
• Logging

Download the sources and execute the following command:

make install

NOTE: Python >=3.6 is required in order to use the library.

It is a good practice to have a defined behaviour after connecting or disconnecting the client.

defon_connect(ditto_client:Client):print("Ditto client connected")defon_disconnect(ditto_client:Client):print("Ditto client disconnected")

With these configurations a client instance can be created.

client=Client(on_connect=on_connect,on_disconnect=on_disconnect)

After the client is created, it's ready to be connected.

client.connect(host="localhost")

The client can be also connected with custom connection configurations.

client.connect(host="localhost",port=1883,keep_alive=60)

Full example of the basic client connection can be foundhere.

NOTE: It is possible to create a client instance by inheriting the Client class. Theon_connect andon_disconnect callback methods should be overridden in order to be configured. A separate method can be created in order to connect the client. This allows the client to be connected with custom configurations. Full example of the client connection as a class can be foundhere.

NOTE: It is also possible to provide an external Paho instance for communication by using thepaho_client property of the Client class. Full example of the client connection using an external Paho client can be foundhere.

Before sending any commands regarding features, there must be a client connected.

A feature instance can be created with definition ID, properties, and/or desired properties.

myFeature=Feature()    .with_definition_from("my.model.namespace:FeatureModel:1.0.0")    .with_property("myProperty","myValue")

Then a Ditto command can be created. Modify acts as an upsert - it either creates a feature or updates it if it already exists.The ID provided infeature() is used to recognize the feature which will be created/updated.

command=Command(NamespacedID().from_string("test.ns:test-name"))    .feature("МyFeatureID")    .twin()    .modify(myFeature)

The command can be now wrapped in an envelope and sent.

envelope=command.envelope(response_required=False)client.send(envelope)

Modify overrides the current feature's property.

command=Command(NamespacedID().from_string("test.ns:test-name"))    .feature_property("МyFeatureID","myProperty")    .twin()    .modify("myModifiedValue")

The command can be now wrapped in an envelope and sent.

envelope=command.envelope(response_required=False)client.send(envelope)

Delete command is created using the feature's ID and the property's name.

command=Command(NamespacedID().from_string("test.ns:test-name"))    .feature_property("МyFeatureID","myProperty")    .twin()    .delete()

The command can now be wrapped in an envelope and sent.

envelope=command.envelope(response_required=False)client.send(envelope)

A feature can be deleted with a command with the appropriate feature's ID.

command=Command(NamespacedID().from_string("test.ns:test-name"))    .feature("МyFeatureID")    .twin()    .delete()

The command can now be wrapped in an envelope and sent.

envelope=command.envelope(response_required=False)client.send(envelope)

Full example of working with features can be foundhere.

Every client instance can subscribe for incoming Ditto messages. This usually happens right after the client is connected.

defon_connect(ditto_client:Client):print("Ditto client connected")# Subscribe for incoming messagesditto_client.subscribe(on_message)

NOTE: Multiple handlers can be added for Ditto messages processing.

It is a good practice to clear all subscriptions if the client gets disconnected.

defon_disconnect(ditto_client:Client):ditto_client.unsubscribe(on_message)

NOTE: If no message handlers are provided tounsubscribe() then all will be removed.

Now when a message is received it can be handled and replied to.

defon_message(request_id:str,message:Envelope):# get the thing id from the topic of the incoming messageincoming_thing_id=NamespacedID(message.topic.namespace,message.topic.entity_id)# create an example outbox message and replylive_message=Message(incoming_thing_id).outbox(message_subject).with_payload(dict(a="b",x=2))# generate the respective Enveloperesponse_envelope=live_message.envelope(correlation_id=message.headers.correlation_id,response_required=False).with_status(200)# send the replyself.reply(request_id,response_envelope)

Full example of the subscribing and handling messages can be foundhere.

The default logger can be used in order to log events, regarding the client.

client.enable_logger(True)

Alternatively, an external logger can be also provided.

logging.basicConfig(level=logging.DEBUG)logger=logging.getLogger(__name__)client.enable_logger(True,logger)

NOTE: The logger must be enabled before connecting the client.