Getting Started with Zymbit Connect

Zymbit Connect

Zymbit Connect is a service that allows easy communication between your devices. At its core Connect is a publish / subscribe engine, which simply means it’s a mechanism for devices to send, or publish, messages and other devices to receive, or subscribe, to them.

Here we will install Zymbit Connect on a laptop, followed by installing it on a Raspberry Pi running Raspbian.

Installation

Zymbit Connect is written in Python and the zymbit package is available on Pypi. It can be installed with the command:

sudo pip install zymbit

If you get the error below you need to install pip:

$ sudo pip
-bash: pip: command not found

pip can be installed with the command:

sudo easy_install pip

Account creation

To get started, create an account.

zymbit signup <email address>

You will then receive an email at the address provided with a confirmation code. Copy the verification code from the email and run the following command:

zymbit confirm <confirmation code>

Now you’re ready to add devices to your account.

Adding Devices

Your account includes a key for adding devices to the account. The key can be printed to the screen with the command:

zymbit provisioning_key | pbcopy

On a Mac the | pbcopy part of the command above sticks the key into your paste buffer so you can cmd+v it where you really need it. Not on a Mac? Remove | pbcopy. If there’s a similar trick on your system of choice, let us know and we’ll update the docs!

Provision the device

With they key in hand, provision your device. We have instructions for provisioning Raspbian on Raspberry Pi and Arduino Yún.

Listing devices

Once you have provisioned a device, you can get a list with the zymbit devices command:

$ zymbit devices
hostname    client_id          uuid
----------  -----------------  --------------------------------
lappie      80:cf:41:b4:bd:47  d7c9182b4e354b569bbef8d12ee49533
mediapi     b8:27:eb:a9:06:5b  7407ac45af9a447f86ddb07619239fb7

Publishing

With the connector installed and a device provisioned, devices can publish data and other systems can subscribe to it.

Publishing data from the device can be accomplished with a single line:

echo 3 | nc localhost 9628

The command above published the value 3 from this device.

Subscribing

To see subscribed data, let’s publish some random data from our device every 30 seconds:

while [ 1 ]; do echo ${RANDOM} | nc localhost 9628; sleep 30; done;

Each data stream has its own routing_key. The routing key uniquely identifies the data coming from each device. To see all the published streams run the zymbit streams command:

$ zymbit streams
zymbot    routing_key
--------  -------------------------------------------------
mediapi   data.7407ac45af9a447f86ddb07619239fb7.sensor

The routing key, data.7407ac45af9a447f86ddb07619239fb7.sensor, is a combination of the device’s UUID (from the zymbit devices command above) and a stream-specific key, which is sensor by default. To see the data as it’s published run the zymbit subscribe command:

[berto@g6]$ zymbit subscribe data.7407ac45af9a447f86ddb07619239fb7.sensor
{"action": "config", "timestamp": "2015-08-05T17:23:20.632037", [...]}
{"action": "connection", "timestamp": "2015-08-05T17:23:20.632529", "params": {"routing_key": "connection_id", "connection_id": "96f9d2ec-1be4-47fb-8fcb-9157e97d2a64", "remote_ip": "192.168.1.19"}, "message_id": "f506de1b-e56e-4ac2-9ee6-774450b6cc92"}
{"action": "subscribe", "timestamp": "2015-08-05T17:23:20.637142", "params": {"queue": "b02746db-f4fd-4d26-ad72-7b5573966b45", "organization": null, "exchange": "data", "consumer_tag": "ctag1.b2a5ce67052541cdb5455aba240c6d35", "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "message_id": "cce4167e-ddfa-4f0f-a4ac-8a11886a58e1"}
{"action": "data", "timestamp": "2015-08-05T17:23:42.543304", "meta": {"subscription": {"routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "client": {"uuid": "7407ac45af9a447f86ddb07619239fb7"}, "connection_id": "641fdc2a-39d4-4ce4-a1e3-881cc18dbb79", "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "params": {"value": 27458, "key": "sensor"}, "message_id": "13bb5b13-4bc4-42a8-827a-600c1fddf5e3"}
{"action": "data", "timestamp": "2015-08-05T17:24:12.610225", "meta": {"subscription": {"routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "client": {"uuid": "7407ac45af9a447f86ddb07619239fb7"}, "connection_id": "641fdc2a-39d4-4ce4-a1e3-881cc18dbb79", "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "params": {"value": 27737, "key": "sensor"}, "message_id": "e5847428-c8a1-4732-92f6-c9f7156d5099"}
{"action": "data", "timestamp": "2015-08-05T17:24:42.670854", "meta": {"subscription": {"routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "client": {"uuid": "7407ac45af9a447f86ddb07619239fb7"}, "connection_id": "641fdc2a-39d4-4ce4-a1e3-881cc18dbb79", "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"}, "params": {"value": 11860, "key": "sensor"}, "message_id": "cdc9e949-41bf-45ce-b9f8-2abcc6ad4ab0"}

The subscribe command is provides a quick way to see what data is being published. We will have more information on programmatically processing data soon.

A closer look at the data

Published data is delivered in a JSON string we call an “envelope”. The command that published a 3 in our example above produced the envelope below:

{
    "message_id": "21ea89ad-64c4-41b3-a81e-fa3f2756b550",
    "timestamp": "2015-08-05T14:28:48.735122",
    "action": "data",
    "params": {
        "key": "sensor",
        "value": 3
    },
    "meta": {
        "client": {
            "uuid": "7407ac45af9a447f86ddb07619239fb7"
        },
        "connection_id": "641fdc2a-39d4-4ce4-a1e3-881cc18dbb79",
        "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor",
        "subscription": {
            "routing_key": "data.7407ac45af9a447f86ddb07619239fb7.sensor"
        }
    }
}

The data, 3, is under value within the JSON’s params key; in other words data['params']['value'].

The label value is a default and a more meaningful name can be given. For example, if the data being published is temperature, we can give the value a label of temp like so:

echo temp=3 | nc localhost 9628

Which produces:

[...]
    "params": {
        "key": "sensor",
        "temp": 3
    }
[...]

Similarly, by default the stream’s key is sensor and can be changed by defining key:

echo key=living_room,temp=3 | nc localhost 9628
[...]
"params": {
    "key": "living_room",
    "temp": 3
}
[...]

A stream can also be comprised of multiple values. Say temperature and humidity readings are being collected. Both readings can be published together:

echo key=living_room,temp=3,hum=84 | nc localhost 9628
[...]
"params": {
    "key": "living_room",
    "hum": 84,
    "temp": 3
}
[...]

Hope you find this useful! Please let us know what we can do to make your projects easier by replying or sending us an email at info@zymbit.com.