sgframework package¶
sgframework.framework module¶
-
class
sgframework.framework.
App
(name, host, port=1883, certificate_directory=None)[source]¶ Bases:
sgframework.framework.BaseFramework
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/
signalnameand listens to data on topic:
data/
dataproducing_resource/
signalnameParameters: - 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 handleMQTTv311
.
-
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 insgframework.constants
.
-
timeout
¶ numerical
MQTT socket timeout, when running the
loop()
method. Default valueDEFAULT_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 nextstart()
.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 thenNone
, the echo payload will bestr(returnvalue)
. More than one input signal can use the same callback.The certificate files should be named according to
CA_CERTS
,CERTFILE
andKEYFILE
.
-
class
sgframework.framework.
BaseFramework
(name, host, port=1883, certificate_directory=None)[source]¶ Bases:
object
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 handleMQTTv311
.
-
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 insgframework.constants
.
-
timeout
¶ numerical
MQTT socket timeout, when running the
loop()
method. Default valueDEFAULT_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 nextstart()
.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 thenNone
, the echo payload will bestr(returnvalue)
. More than one input signal can use the same callback.The certificate files should be named according to
CA_CERTS
,CERTFILE
andKEYFILE
.-
CA_CERTS
= 'ca_public_certificate.pem'¶
-
CERTFILE
= 'public_certificate.pem'¶
-
KEYFILE
= 'private_key.pem'¶
-
PAYLOAD_FALSE
= 'False'¶
-
PAYLOAD_TRUE
= 'True'¶
-
PREFIX_RESOURCEAVAILABLE
= 'resourceavailable'¶
-
_on_connect
(mqttclient, userdata, flags, rc)[source]¶ MQTT callback at connection attempts.
This callback is responsible for doing the subscriptions, and to publish capabilities and default values.
Method signature according to Paho documentation.
-
_on_disconnect
(mqttclient, userdata, rc)[source]¶ MQTT callback at disconnect.
Method signature according to Paho documentation.
-
_on_incoming_message
(mqttclient, userdata, message)[source]¶ MQTT callback at incoming messages.
Executes a preregistered callback, and publishes an echo (if configured).
Updates the default value for echoed signals if configured.
Method signature according to Paho documentation.
-
_on_mqttclient_log_event
(mqttclient, userdata, level, buf)[source]¶ MQTT callback at log event.
Method signature according to Paho documentation.
-
_on_publish
(mqttclient, userdata, mid)[source]¶ MQTT callback at publication confirmation.
Method signature according to Paho documentation.
-
_on_subscribe
(mqttclient, userdata, mid, granted_qos)[source]¶ MQTT callback at subscribe.
Method signature according to Paho documentation.
-
_on_unsubscribe
(mqttclient, userdata, mid)[source]¶ MQTT callback at unsubscribe.
Method signature according to Paho documentation.
-
_register_inputsignal
(messagetype, servicename, signalname, callback, callback_on_change_only=False, echo=False, send_echo_as_retained=False, defaultvalue=None)[source]¶ Register a callback for an incoming MQTT message.
Parameters: - messagetype (str) – One of the predefined message types (also known as prefix).
- servicename (str) – service name
- signalname (str) – signal name
- callback (function) – Callback that will be used when a signal is received.
- callback_on_change_only (bool) – Trigger callback only for changed payload.
- echo (bool) – True if the incoming signal 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. Set to None to avoid sending. The value is converted to a string before sending. It will be updated by _on_incoming_message().
For details on the callback, see the class documentation.
Subscribes to: messagetype
/
servicename/
signalnameThe messagetype can be
data
,dataavailable
,command
,commandavailable
,resourceavailable
.For example:
data/climateservice/actualindoortemperature
.
-
_register_outputsignal
(messagetype, servicename, signalname, defaultvalue, send_as_retained)[source]¶ Registering outgoing MQTT messages.
This is typically used for automatically send availability information.
Parameters: - messagetype (str) – One of the predefined message types (also known as prefix),
most often
data
. - servicename (str) – service name, most often
self.name
. - signalname (str) – signal name
- defaultvalue – Value to be sent on startup. Set to None to avoid sending. The value is converted to a string before sending.
- send_as_retained (bool) – True if the signal should be published as retained.
Publishes to: messagetype
/
servicename/
signalnamefor example:
data/climateservice/actualindoortemperature
.There is also a mechanism to automatically publish availability topics, for example:
dataavailable/climateservice/actualindoortemperature
.- messagetype (str) – One of the predefined message types (also known as prefix),
most often
-
_set_broker_connectionstatus
(broker_connected)[source]¶ Set information whether the broker is connected. This is triggering a callback to the user script.
The information is not stored in the framework, it is the responsibility of the user script.
Parameters: broker_connected (bool) – Indicates whether the broker is connected or not
-
get_descriptive_ascii_art
()[source]¶ Display an overview with registered incoming and outgoing topics.
Returns: A multi-line string.
-
loop
()[source]¶ 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)[source]¶ 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/
signalnamefor example:
dataavailable/climateservice/actualindoortemperature
.
-
register_incoming_data
(servicename, signalname, callback, callback_on_change_only=False)[source]¶ 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/
signalnamefor example:
data/climateservice/actualindoortemperature
.
-
send_command
(servicename, signalname, value, send_command_as_retained=False)[source]¶ 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/
signalnamefor example
command/climateservice/aircondition
.Most often commands are sent as non-retained messages.
-
start
(use_threaded_networking=False, use_clean_session=True)[source]¶ 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.
-
class
sgframework.framework.
Inputsignalinfo
(messagetype, servicename, signalname, callback, callback_on_change_only, echo, send_echo_as_retained, defaultvalue)[source]¶ Bases:
object
Object for storing configuration information about incoming MQTT messages.
Storage of incoming signal definitions that should be subscribed to. It can be data, dataavailable, command, commandavailable, resourceavailable. Also holds the callback to be used at incoming signals, and possibly a copy of last received payload.
Arguments are described in the
BaseFramework._register_inputsignal()
method.For details on the callback signature, see the
BaseFramework
documentation.TODO: .messagetype should be a property.
-
class
sgframework.framework.
Outputsignalinfo
(messagetype, servicename, signalname, defaultvalue, send_as_retained)[source]¶ Bases:
object
Object for storing configuration information about (some of the) outgoing MQTT messages, typically outgoing data (not outgoing commands).
Arguments are described in the
BaseFramework._register_outputsignal()
method.TODO: .messagetype should be a property.
-
class
sgframework.framework.
Resource
(name, host, port=1883, certificate_directory=None)[source]¶ Bases:
sgframework.framework.BaseFramework
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/
signalnamedata/
myresourcename/
signalnameAlso publishes availability of commands and data, using retained messages:
commandavailable/
myresourcename/
signalnamedataavailable/
myresourcename/
signalnameWhen 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 handleMQTTv311
.
-
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 insgframework.constants
.
-
timeout
¶ numerical
MQTT socket timeout, when running the
loop()
method. Default valueDEFAULT_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 nextstart()
.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 thenNone
, the echo payload will bestr(returnvalue)
. More than one input signal can use the same callback.The certificate files should be named according to
CA_CERTS
,CERTFILE
andKEYFILE
.-
_publish_capablities_and_defaultvalues
()[source]¶ Sends ‘True’ to the topic:
resourceavailable/
myresourcename/presence
For data in outputsignal storage:
- Sends
dataavailable/
myresourcename/
signalname - If configured, sends defaultvalue
data/
myresourcename/
signalname
For commands in inputsignal storage:
- Sends
commandavailable/
myresourcename/
signalname - If echo configured, sends
dataavailable/
myresourcename/
signalname - If configured, sends defaultvalue
data/
myresourcename/
signalname
- Sends
-
register_incoming_command
(signalname, callback, callback_on_change_only=False, echo=True, send_echo_as_retained=False, defaultvalue=None)[source]¶ 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/
signalnameWhen the resource is starting, it is publishing a retained message to:
commandavailable/
myresourcename/
signalname
-
register_outgoing_data
(signalname, defaultvalue=None, send_data_as_retained=False)[source]¶ 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/
signalnameUpon sending data, the topic is:
data/
myresourcename/
signalnamefor example:
data/climateservice/actualindoortemperature
.Typically the data is published using non-retained messages.
-
send_data
(signalname, value)[source]¶ 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/
signalnamefor 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.