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