Usage introduction for the ‘sgframework’ package

With the sgframework you can implement the ‘apps’ and ‘resources’ described in the previous section. Below are some minimal examples to get you started.

Minimal ‘resource’ example

This is an example of a ‘resource’ implemented using the Secure Gateway framework. It is a taxi sign listening to commands on the MQTT topic command/taxisignservice/state. When the received payload is True the text “Turning on my taxi sign.” is printed.

../examples/minimal/minimaltaxisign.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import time

import sgframework


def on_taxisign_state_command(resource, messagetype, servicename,
                              commandname, commandpayload):
    if commandpayload.strip() == 'True':
        print("Turning on my taxi sign.", flush=True)
        return 'True'
    else:
        print("Turning off my taxi sign.", flush=True)
        return 'False'


resource = sgframework.Resource('taxisignservice', 'localhost')
resource.register_incoming_command('state',
                                   on_taxisign_state_command,
                                   defaultvalue='False',
                                   send_echo_as_retained=True)
resource.start(use_threaded_networking=True)
while True:
    time.sleep(1)

This example resource is using threaded networking, meaning that the MQTT communication is done in a separate thread.

It is also possible to run the resource in a single thread, but then you need to call resource.loop() regularly.

Minimal ‘app’ example

This example ‘app’ controls the taxi sign by sending MQTT commands on the appropriate topic. It also listens to the echo from the taxi sign, and shows the current taxi sign state.

../examples/minimal/minimaltaxiapp.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import time

import sgframework


def on_taxisign_state_data(app, messagetype, servicename, signalname, payload):
    if payload.strip() == 'True':
        print("The taxi sign is now on.", flush=True)
    else:
        print("The taxi sign is now off.", flush=True)


app = sgframework.App('taxiapp', 'localhost')
app.register_incoming_data('taxisignservice', 'state', on_taxisign_state_data)
app.start()  # Not using threaded networking

starttime = time.time()
command_sent = False
while True:
    app.loop()

    if time.time() - starttime > 4 and not command_sent:
        print("Turning on the taxi sign from script...", flush=True)
        app.send_command('taxisignservice', 'state', 'True')
        command_sent = True

This app is an example implementation not using threaded networking. Apps can also use threaded networking, as described in the API documentation (see another section).

Usage recommendations

It is recommended to use the threaded networking. However when using for example the TK graphics library, it is not possible to run it in another thread. Instead you need to call the loop() method regularly.

Developing your own Resources

If you are to develop your own resource for the Secure Gateway network, you could use the available resource framework (which runs under Python3).

The main API object is the Resource, and you should use these public methods to get your resource up and running:

  • register_incoming_command()
  • register_outgoing_data()
  • start()
  • send_data()

and:

  • stop()
  • loop() (if not using the threaded networking interface)

Have a look on the source code for the taxisign service (in the distributed examples) to have inspiration for the usage of the Secure Gateway resource framework.

Of course, Secure Gateway resources can be implemented in any programming language having a proper MQTT library with TLS support.

Developing your own Apps

Similarly, there is Secure Gateway app framework, for usage when implementing custom Python3 apps.

The main API object is the App, and use these public methods to get it running:

  • register_incoming_availability()
  • register_incoming_data()
  • start()
  • send_command()

and:

  • stop()
  • loop() (if not using the threaded networking interface)

The taxisign app source code should be used for inspiration.