API for sgframework

This page shows the public part of the API. For a more detailed documentation on all objects, see the sgframework page: sgframework.framework

class sgframework.App(name, host, port=1883, certificate_directory=None)

App framework for the Secure Gateway

Sends commands to any resource. Handles incoming MQTT messages (data) from any resource.

It does not have any ‘last will’. Typically sends (non retained=non persistent) commands to:

command/resource_to_be_controlled/signalname

and listens to data on topic:

data/dataproducing_resource/signalname

Parameters:

• name (str) – Name of the app/resource. For resources, it is also used in the MQTT topic hierarchy.
• host (str) – Broker host name.
• port (int) – Broker port number.
• certificate_directory (str or None) – Full path to the directory of the certificate files.

protocol

enum in the Paho module

MQTT protocol version, defaults to MQTTv31, as older versions of the Mosquitto broker can not handle MQTTv311.

tls_version

enum in the ssl module

SSL protocol version, defaults to ssl.PROTOCOL_TLSv1

qos

int

MQTT quality of service. 0, 1 or 2. See Paho documentation. Default value DEFAULT_QOS is set in sgframework.constants.

timeout

numerical

MQTT socket timeout, when running the loop() method. Default value DEFAULT_TIMEOUT.

keepalive

numerical

MQTT keepalive message interval. Default value DEFAULT_KEEPALIVE_TIME.

Also the parameters appear as attributes. The public attributes are used when calling start(). Any changes are valid from next start().

References to sub-objects:

• mqttclient (object): See Paho documentation
• logger (object): See Python standard library documentation
• userdata (whatever): Convenience object that is available for user code in callbacks. Not used by the framework itself.
• on_broker_connectionstatus_info: Implement this callback if you would like notifications on broker connection status changes. See below.

Callback to the user application on changed broker connection status:

on_broker_connectionstatus_info(app_or_resource, broker_connected)

Where app_or_resource is the app or resource object, and broker_connected (bool) is True if the user application is connected to the broker.

Callbacks to the user application on incoming information are registered using separate methods. The callbacks should have this interface:

callbackname(resource_or_app, messagetype, servicename, signalname, inputpayload)

where messagetype, servicename, signalname and inputpayload are strings. The callback is protected by try/except. The strings to the callback have been through .strip().

When using echo and the returnvalue of the callback is None, the command payload is used in the echo. For returnvalues other then None, the echo payload will be str(returnvalue). More than one input signal can use the same callback.

The certificate files should be named according to CA_CERTS, CERTFILE and KEYFILE.

get_descriptive_ascii_art()

Display an overview with registered incoming and outgoing topics.

Returns:A multi-line string.

loop()

Run network activities.

This function needs to be called frequently to keep the network traffic alive, if not using threaded networking. It will block until a message is received, or until the self.timeout value.

If not connected to the broker, it will try to connect once.

Do not use this function when running threaded networking.

register_incoming_availability(prefix, servicename, signalname, callback)

Register a callback for incoming availability information (incoming MQTT message).

Primarily useful for apps (but is useful for resources to receive data etc from other resources).

Parameters:

• prefix (str) – one of PREFIX_COMMANDAVAILABLE, PREFIX_DATAAVAILABLE (or maybe PREFIX_RESOURCEAVAILABLE)
• servicename (str) – name of the service sending the availability info
• signalname (str) – name of the data or command
• callback (function) – Callback that will be used when availability information is received.

When registering a callback for RESOURCEAVAILABLE the actual value of the signalname is not used. Just pass in any string.

For details on the callback, see the class documentation.

Subscribes to: prefix/servicename/signalname

for example: dataavailable/climateservice/actualindoortemperature.

register_incoming_data(servicename, signalname, callback, callback_on_change_only=False)

Register a callback for incoming data (incoming MQTT message).

Primarily useful for apps (but is useful for resources to receive data from other resources).

Parameters:

• servicename (str) – name of the service sending the data
• signalname (str) – name of the signal
• callback (function) – Callback that will be used when data is received.
• callback_on_change_only (bool) – Trigger callback only for changed payload.

For details on the callback, see the class documentation.

Subscribes to: data/servicename/signalname

for example: data/climateservice/actualindoortemperature.

send_command(servicename, signalname, value, send_command_as_retained=False)

Send a command.

Primarily useful for apps (but is useful for resources to control other resources).

Parameters:

• servicename (str) – destination service name
• signalname (str) – destination signal name
• value – Value to be sent. Is converted to a string before sending.
• send_command_as_retained (bool) – Publish the command as retained.

Sends messages on topic: command/servicename/signalname

for example command/climateservice/aircondition.

Most often commands are sent as non-retained messages.

start(use_threaded_networking=False, use_clean_session=True)

Connect to the broker.

Parameters:

• use_threaded_networking (bool) – Start MQTT networking activity in a separate thread.
• use_clean_session (bool) – Connect to broker using a clean session.

If not using threaded networking, you need to call the loop() method frequently.

If using a clean session, also the client name is changed to include the process ID. This in order to avoid client name collisions in the broker.

stop()

Disconnect from the broker

class sgframework.Resource(name, host, port=1883, certificate_directory=None)

Resource framework for the Secure Gateway

Receives commands from apps (incoming MQTT messages). Sends data to apps (outgoing MQTT messages).

It can also recieve incoming data from other resources, and can send commands to other resources.

The resource name is typically part of incoming and outgoing message topics:

command/myresourcename/signalname

data/myresourcename/signalname

Also publishes availability of commands and data, using retained messages:

commandavailable/myresourcename/signalname

dataavailable/myresourcename/signalname

When starting up, it sends ‘True’ to the ‘last will’ topic in a retained message:

resourceavailable/myresourcename/presence

The broker is automatically broadcasting ‘False’ on ‘last will’ topic at lost connection.

Parameters:

• name (str) – Name of the app/resource. For resources, it is also used in the MQTT topic hierarchy.
• host (str) – Broker host name.
• port (int) – Broker port number.
• certificate_directory (str or None) – Full path to the directory of the certificate files.

protocol

enum in the Paho module

MQTT protocol version, defaults to MQTTv31, as older versions of the Mosquitto broker can not handle MQTTv311.

tls_version

enum in the ssl module

SSL protocol version, defaults to ssl.PROTOCOL_TLSv1

qos

int

MQTT quality of service. 0, 1 or 2. See Paho documentation. Default value DEFAULT_QOS is set in sgframework.constants.

timeout

numerical

MQTT socket timeout, when running the loop() method. Default value DEFAULT_TIMEOUT.

keepalive

numerical

MQTT keepalive message interval. Default value DEFAULT_KEEPALIVE_TIME.

Also the parameters appear as attributes. The public attributes are used when calling start(). Any changes are valid from next start().

References to sub-objects:

• mqttclient (object): See Paho documentation
• logger (object): See Python standard library documentation
• userdata (whatever): Convenience object that is available for user code in callbacks. Not used by the framework itself.
• on_broker_connectionstatus_info: Implement this callback if you would like notifications on broker connection status changes. See below.

Callback to the user application on changed broker connection status:

on_broker_connectionstatus_info(app_or_resource, broker_connected)

Where app_or_resource is the app or resource object, and broker_connected (bool) is True if the user application is connected to the broker.

Callbacks to the user application on incoming information are registered using separate methods. The callbacks should have this interface:

callbackname(resource_or_app, messagetype, servicename, signalname, inputpayload)

where messagetype, servicename, signalname and inputpayload are strings. The callback is protected by try/except. The strings to the callback have been through .strip().

When using echo and the returnvalue of the callback is None, the command payload is used in the echo. For returnvalues other then None, the echo payload will be str(returnvalue). More than one input signal can use the same callback.

The certificate files should be named according to CA_CERTS, CERTFILE and KEYFILE.

get_descriptive_ascii_art()

Display an overview with registered incoming and outgoing topics.

Returns:A multi-line string.

loop()

Run network activities.

This function needs to be called frequently to keep the network traffic alive, if not using threaded networking. It will block until a message is received, or until the self.timeout value.

If not connected to the broker, it will try to connect once.

Do not use this function when running threaded networking.

register_incoming_availability(prefix, servicename, signalname, callback)

Register a callback for incoming availability information (incoming MQTT message).

Primarily useful for apps (but is useful for resources to receive data etc from other resources).

Parameters:

• prefix (str) – one of PREFIX_COMMANDAVAILABLE, PREFIX_DATAAVAILABLE (or maybe PREFIX_RESOURCEAVAILABLE)
• servicename (str) – name of the service sending the availability info
• signalname (str) – name of the data or command
• callback (function) – Callback that will be used when availability information is received.

When registering a callback for RESOURCEAVAILABLE the actual value of the signalname is not used. Just pass in any string.

For details on the callback, see the class documentation.

Subscribes to: prefix/servicename/signalname

for example: dataavailable/climateservice/actualindoortemperature.

register_incoming_command(signalname, callback, callback_on_change_only=False, echo=True, send_echo_as_retained=False, defaultvalue=None)

Register a callback for an incoming command (incoming MQTT message).

Parameters:

• signalname (str) – command name
• callback (function) – Callback that will be used when a command is received.
• callback_on_change_only (bool) – Trigger callback only for changed payload.
• echo (bool) – True if the incoming command should be echoed back (as “data”)
• send_echo_as_retained (bool) – True if the echo should be published as retained.
• defaultvalue – Value to be echoed on startup and reconnect. Set to None to avoid sending. The value is converted to a string before sending. It will be updated by the internal _on_incoming_message() callback for incoming MQTT messages.

For details on the callback, see the class documentation.

Subscribes to: command/myresourcename/signalname

When the resource is starting, it is publishing a retained message to:

commandavailable/myresourcename/signalname

register_incoming_data(servicename, signalname, callback, callback_on_change_only=False)

Register a callback for incoming data (incoming MQTT message).

Primarily useful for apps (but is useful for resources to receive data from other resources).

Parameters:

• servicename (str) – name of the service sending the data
• signalname (str) – name of the signal
• callback (function) – Callback that will be used when data is received.
• callback_on_change_only (bool) – Trigger callback only for changed payload.

For details on the callback, see the class documentation.

Subscribes to: data/servicename/signalname

for example: data/climateservice/actualindoortemperature.

register_outgoing_data(signalname, defaultvalue=None, send_data_as_retained=False)

Pre-register information on a outgoing data topic (MQTT messages). Note that the actual data sending is later done with the send_data() method.

Parameters:

• signalname (str) – signal name
• defaultvalue – Value to be sent on startup and reconnect. Set to None to avoid sending. The value is converted to a string before sending. It will be updated by send_data().
• send_data_as_retained (bool) – Whether the data should be published as retained

When the resource is starting, it is publishing a retained message to:

dataavailable/myresourcename/signalname

Upon sending data, the topic is: data/myresourcename/signalname

for example: data/climateservice/actualindoortemperature.

Typically the data is published using non-retained messages.

send_command(servicename, signalname, value, send_command_as_retained=False)

Send a command.

Primarily useful for apps (but is useful for resources to control other resources).

Parameters:

• servicename (str) – destination service name
• signalname (str) – destination signal name
• value – Value to be sent. Is converted to a string before sending.
• send_command_as_retained (bool) – Publish the command as retained.

Sends messages on topic: command/servicename/signalname

for example command/climateservice/aircondition.

Most often commands are sent as non-retained messages.

send_data(signalname, value)

Send data on a pre-registered topic.

Parameters:

• signalname (str) – signal name
• value – Value to be sent. Is convered to a string before sending.

Sends to the topic: data/myresourcename/signalname

for example: data/climateservice/actualindoortemperature.

Updates the defaultvalue for this signal.

Whether the signal should be sent as retained or not is set already during registration.

start(use_threaded_networking=False, use_clean_session=True)

Connect to the broker.

Parameters:

• use_threaded_networking (bool) – Start MQTT networking activity in a separate thread.
• use_clean_session (bool) – Connect to broker using a clean session.

If not using threaded networking, you need to call the loop() method frequently.

If using a clean session, also the client name is changed to include the process ID. This in order to avoid client name collisions in the broker.

stop()

Disconnect from the broker