borud/spanqtt repository overview

⁠SpanQTT

This is a testbed for experimenting with possible MQTT broker embedded into Span. For now this is an adapter that will consume the output from a collection and distribute the messages into an MQTT broker.

In order to run it you need a Span API token and you need to know the Span collection ID.

⁠Docker

The image is hosted on Docker Hub:

docker pull borud/spanqtt:latest

Please set the environment variables for SPANQTT_TOKEN and SPANQTT_COLLECTION_ID before running these commands.

If you want to run SpanQTT in a temporary Docker container:

docker run --rm  --name spanqtt --env SPANQTT_TOKEN --env SPANQTT_COLLECTION_ID -p 1883:1883 borud/spanqtt:latest

If you want to run it as a daemon and have it restart:

docker run -d  --restart on-failure --name spanqtt --env SPANQTT_TOKEN --env SPANQTT_COLLECTION_ID -p 1883:1883 borud/spanqtt:latest

⁠Client Authentication

• Username set to Span collection ID
• Password set to Span API token

The reason we have done it this way is that we want to experiment with a dynamic broker configuration that can serve any number of Span collections. Re-using the collection ID and Span token in this manner is convenient because we are using information that is already available to API users and not introducing any new layers of management.

⁠Subscription

The server makes sure that the only namespace you can subscribe to is the namespace for the collection you are listening to. The namespace for SpanQTT is <collectionID>/<deviceID>.

You can use MQTT wildcards to subscribe to the whole collection <collectionID>/#. If you want to subscribe to just a set of devices you use the whole topic as described in the above paragraph.

⁠Publishing

At the moment the broker does not allow clients to publish anything. In the future we will add support for downstream messaging. Clients can publish messages to <collectionID>/<deviceID>/downstream.

⁠mosquitto_sub example

If you have the Mosquitto client binaries installed you can attach a client and subscribe by using the following command. This example just uses the environment variables described earlier to specify the parameters to the mosquitto_sub program.

mosquitto_sub -v -t  "$SPANQTT_COLLECTION_ID/#" -u $SPANQTT_COLLECTION_ID -P $SPANQTT_TOKEN 

⁠MQTTness

Since this interface can be thought of as a projection of Span and mobile devices, with which you communicate asynchronously, we might have to take some liberties with MQTT semantics here and there.