wozzit

A simple communications system for the Internet of Things

View the Project on GitHub mrpjevans/wozzit

Wozzit Server Reference

Requirements

External Dependancies

Creating an Instance

import wozzit

svr = wozzit.Server(opts)

Server.listen([opts])

Start the server and await connections.

opts = Dictionary of options as follows. All are optional.

Key Values
ip IPv4 Address on which to listen. Omit to listen on all.
port Port on which to listen. Default is 10207.
smtp.host SMTP host for sending email
smtp.port SMTP server port
smtp.SSL Demand SSL connection? True/False
smtp.username If required, authentication username
smtp.password If required, authentication password
smtp.fromName Friendly name of originator
smtp.fromEmail Email address of originator
onError Callback to be called if a trappable error occurs

Server.setOptions(opts)

Sets the server options as detailed in listen() but does not start the server.

Server.send(msg, to)

Send a message to another Wozzit node.

Argument Description
msg A Wozzit Message instance
to The full URL to to send to

A Wozzit server will issue a message which is returned by this method if the transmission was received. A message of schema ‘wozzit.receipt’ can be considered successful. If the schema is ‘wozzit.error’, the payload should be inspected to discover the problem.

Example
import wozzit

svr = wozzit.Server()
msg = wozzit.Message()
msg.schema = "wozzit.test"
response = svr.send(msg, "http://192.168.0.2:10207/")
print(response.schema)

Listener Methods

The following methods add ‘hooks’ that are called when a message is received. Each method takes a match argument which determines whether that hook is processed against the received message.

match is a dictionary that echoes items in the message envelope.

Listener methods have no return values.

Examples

match = {
	"schema": "wozzit.rain"
}

The listener will only be called for messages that have the schema ‘wozzit.rain’.

match = {
	"schema": "wozzit.rain",
	"psk": "jskdq87rehfyg837ofnj"
}

For added security, this will only run if the schema is ‘wozzit.rain’ and the correct pre-shared key has been provided.

match = {
	"schema": "wozzit.rain",
	"psk": "jskdq87rehfyg837ofnj",
	"ip": "192.168.0.1"
}

Same again, but not the IPv4 address must match as well (this header is set by the receiving node, not by the client).

You are free to add your own arbitary headers provided they are prefixed with ‘x-‘. If match is omitted, all messages match.

Server.addLog([match])

Print the message contents to the console whenever a message matches the criteria in match.

Server.addListener([match], callback)

Where callback is a defined function. The function is called if the message is matched. This allows you to run your own code when a message is received, so you can do whatever you like.

The called function is passed the match dictionary and the full message instance for processing.

Example
import wozzit

def myFunction(match, message):
	-- Do exciting stuff here--

svr = wozzit.Server()
svr.addListener({"schema": "wozzit.test"}, myFunction)
svr.listen()

Now myFunction will be called whenever a message of schema ‘wozzit.test’ is received.

Server.addForwarder([match], to)

Automatically forward any matched message to another server. ‘to’ must contain the full URL including port.

Example
import wozzit

svr = wozzit.Server()
svr.addListener({"schema": "wozzit.test"}, "http://192.168.0.2:10207/")
svr.listen()

This is a ‘best efforts’ attempt with no queuing or retries. If you need to ensure the message is sent, you can implement your own system using addListener().

Server.addDesktopNotification([match], message)

Display a simple notification the recipient’s desktop. Uses different libraries to support Linux, Mac and Windows. If a message is matched, the contents of message are displayed as a pop-up notification. Great for testing, but more complicated messages can be created using addListener() and your own functions.

Server.addDesktopNotification([match], toName, toEmail, subject, message)

If a message is matched, send a simple email.

Argument Description
toName The friendly name of the recipient
toEmail The email address of the recipient
subject The subject line for the email
message The body content of the email

For this function to work, SMTP options must have been set using listen() or setOptions(). If not, the event is ignored.

For more complicated requirements, you can implement your own callback using addListener() with the helper method sendEmail().

Server.sendEmail(toName, toEmail, subject, body)

As sending emails is a common task in the Wozzit world, this internal method is exposed for the implementer’s convenience. If you wish, you can include this call in your callback methods to allow you to inspect the contents of a message and customise your response accordingly.

Argument Description
toName The friendly name of the recipient
toEmail The email address of the recipient
subject The subject line for the email
message The body content of the email

For this function to work, SMTP options must have been set using listen() or setOptions(). If not, the event is ignored.

Returns True or False depending on whether the message was successfully sent.

Server.desktopNotification(title, message)

Display an on-screen notification. This is used by the addDesktopNotification listener, but can also be used by your own callbacks, so you customise the notification based on the received message.

Argument Description
title The main heading of the message
message The notification content

This method uses the following libraries per platform:

Library Platform
pync macOS
toaster Windows
notify2 Linux Desktop

The appropriate library will need to be installed for notifications to work.