This Document has been moved over to Google Drive

Summary

The GitHub repository contains three important folders, omnibus, sources and sinks. This sections concerns the omnibus folder, which houses the core library.

Note, this document is not meant to detail the working of python’s library features, but if you want to know more about it, look here. Instead, this document shall detail what the library provides.

Omnibus works by using the library Zero MQ to send messages over sockets. Messages are sent over channels to allow receivers to filter what messages they receive.

Omnibus.py

Omnibus.py provides a few core classes. Message and subclasses of OmnibusCommunicator. Omnibus Communicator is a super class of the two most important classes in Omnibus; Sender and Receiver .

Message

This class has three fields. Channel; the channel the message was sent on, Timestamp; the time the message was sent and Payload; the contents of the message. It is worth noting that this class is designed to be turned into a sequence of bytes to be sent over the Socket. This process is described in the “Sender” section.

Omnibus Communicator

The sole purpose of this class is the manage the shared state between Sender and Receiver. This includes the ZMQ context and the server IP. Both of these are used by ZMQ’s socket interface to send and receive.

This class is not intended to be used by developers writing sources or sinks. It is only an internal class made to assist Sender and Receiver.

Sender

This class is used by sources to send information over omnibus. Most sources include these lines, which include Sender in a project and make use of it.

from omnibus import Sender

sender = Sender()
CHANNEL = "Your Channel" # omnibus channel

...

sender.send(CHANNEL, data)

This class has two methods, Sender.send_message(self, message), which accepts a Message type and sends it over the channel message.channel. To simplify this process slightly, the method Sender.send(self, CHANNEL, data) simply accepts a channel and a payload and constructs a message type to provide send message.

Receiver

Receiver is the complement to Sender. Its purpose is to receive messages sent over omnibus. Here is an example of its use.

from omnibus import Receiver

channel = "" # Receiver channel
receiver = Receiver(channel)

while True:
    data = receiver.recv()
    ...

The methods on receiver correspond to the ones on sender. Note, both Receiver.recv_message(self, timeout=None) and Receiver.recv(self, timeout=None) listen to a channel for timeout milliseconds until a message is received. If one is found, it stops and returns it, else it fails. If the timeout is set to None, then the Receiver will wait until it receives a message.

An important note is that the receiver does not only listen on the channel it is initialized with. It listens to all channel’s whose name has its channel has a prefix. An example is illuminating.

Say we define rec = Receiver("a"), then rec will listen to messages sent on channels "a", "abcd" or "actuator board". However, it would not listen to messages sent over "b". A nice result of this feature is that if you want to listen to all messages sent over omnibus, you can initialize your receiver on the channel "".

This is largely a hold over from the ZMQ library.

Waterloo Rocketry

Core Library