Subscriptions

In the Conductor/Airfinder python library, any UplinkSubject can be subscribed to. While this would naturally include all Conductor Devices and Airfinder af-devices. It also includes some other subjects such as Account/User, Application Tokens, and Asset Groups.

To instantiate the sub (subscription) object, you must first choose which type of subscription to instantiate.

Polling Subscription

While not being true “subscription”, the PollingSubscription provides a quick and easy way to receive uplink events in the same paradigm as the other subscription subclasses. All that is required to instantiate a polling subscription is the UplinkSubject and the polling interval.

u = conductor.airfinder.User("[email protected]")
ap = u.get_access_point("xx:xx:xx:xx:xx:xx")
sub = ap.build_polling_sub(polling_int_s=5)

Then, retrieving the uplink events would be the same as previously described from the SubscriptionBase class. In this example, the polling interval is set to 5 seconds. This indicates that the subscription thread will issue an HTTP GET call every 5 seconds, then notify the user when a new message is detected.

This is a good subscription mechanism for prototyping as it does not require any external dependencies or network setups, while using the same paradigm as more production-ready subscription models offered by the Conductor/Airfinder Library.

ZeroMQ 2 Subscription

Important

ZeroMQ Subscriptions require port-forwarding on the machine that is executing the subscription, as well as sufficient firewall permissions given the port number of choice.

ZeroMQ offers a more faster, more efficient and more reliable subscription mechanism to retrieve uplink events. However, networking must be configured on the machine of operation to utilize the subscription.

To utilize the ZeroMQ subscription, one must first install the zmq library

pip install pyzmq

With the library installed, only the selected open port is required to setup the subscription

u = conductor.airfinder.User("[email protected]")
ap = u.get_access_point("xx:xx:xx:xx:xx:xx")
sub = ap.build_zmq_sub(port=11101)

Retrieving uplink events would be the same as previously described from the SubscriptionBase class.

WebSocket Subscription

Danger

Websockets are currently proxied in the Conductor backend, which the websocket library we used does not currently support!

The workaround here is to manually install this fork of the library for the proxy work-around: https://github.com/mdymike/websockets.

While more data efficient than the PollingSubscription, the WebsocketSubscription is slightly less reliable. They will occasionally close need to be reopened behind the scenes. However, they do not require any firewall or port-forwarding modifications. To enable the websocket subscription, the following dependency is required

pip install websockets

No further arguments are required to instanciate a websocket subscription.

u = conductor.airfinder.User("[email protected]")
ap = u.get_access_point("xx:xx:xx:xx:xx:xx")
sub = ap.build_ws_sub()

MQTT Subscription

Danger

Not Implemented!

Stay tuned.

pip install paho-mqtt

Recieving Messages from Subscriptions

All subscriptions are based off the SubscriptionBase, which offers both asynchronous and blocking methods for receiving subscription events.

Here is a generic example of using callbacks to asynchronously receive subscription events

sub.start()  # Start Subscription Thread

while True:
    # Do other stuff
    continue

sub.stop()  # Kill Subscription Thread

Here is a generic example of using an iterator to receive subscription events while blocking

sub.start()  # Start Subscription Thread

for msg in sub.iter():  # Iterate through each rxed message
    # Do other stuff.
    print(msg)

sub.stop()  # Kill Subscription Thread