Getting Started

Before you start

With SpaceBunny you exchange messages on channels that can be connected with plugins that enable specific features while handling your data.

foto1

  1. Connect any device with an Internet connection. It’ll be able to send and receive data at any time.
  2. The messages are queued and delivered as soon as possible. Even when the device is offline, we make sure that no packet is lost.
  3. You can specify different data “topics“, and enable specific features on them, like data persistence, email, push or SMS notifications.
  4. Our web UI offers a real time live stream of your data flow, and enables you to send messages to your devices. You always have a real time picture of your devices’ state, and can remotely control them with ease.
  5. SpaceBunny is an open platform, you can use our SDK and APIs to customize the way your data is handled and visualized.

Before looking at examples, let’s go over some Platform’s basic concepts to help you getting started in no time.

Devices

“Devices” are the entities, either physical or virtual, that can send data. A Device has also an ‘inbox’ through which it can receive messages from the outside.

foto2

 

* A real life accurate representation of devices

 

Channels

A channel is a semantic representation of a data stream, that can be selectively enabled for a given device. You can think of them as conversation topics on which you can enable specific functionalities through our Plugins system. For example, you can create a channel named input that stores the data it receives, and a channel named alarms that triggers a push notification or an email every time it receives a packet.

foto3

 

 

Plugins

Plugins are specific functionalities that power up your data streams You can tie one or multiple plugins to a channel to enable new features like Persistence, Notifications and Post Processing.foto4

Users

Users are the basic entities of your organization. You can create as many users as you want, and assign them a role.foto5

Access Keys

Each user can be provided with access keys that enable a quick and easy way to authenticate API calls, without exposing the basic credentials. Access Keys are also used for authentication for Live Stream, that we’re going to see shortly. There’s no limit to the number of access keys that can be created for a user.foto6

Getting started

In this section you can learn how to use the basic features of SpaceBunny. We’ll be using the Web interface and SpaceBunny’s SDK to guide you through simple tutorials. Since SpaceBunny is an open platform, you can do all these operations with our API. Check out the API documentation if you want to learn more.

Get the SDK

We’ll be using our SDK in the following samples, so make sure to head to our GitHub page to download the SDK for your favourite language.

Creating a Device

A device represents the ‘thing’ you want to connect. Everything revolves around devices, let’s start by creating one by choosing New Device from the SpaceBunny’s Devices section:1

Enter a name for your device and select the channels you wish to write on. By default we create a couple of useful channels: data and alarm . You can create as many channels as you want in the Channels section.2

Here’s your brand new device:3

Select SHOW CONFIGURATION to get its configurations:4

You can use the provided API Key with the SpaceBunny SDK to automatically authenticate and provision your device, or you can manually set up a connection using the parameters in the Full Configuration field.

Sending data from a device

Now that our new device is ready we can connect it to the platform and start sending data right away. As an example we’ll be using the Ruby SDK:

require 'spacebunny'
device = Spacebunny::Device.new 'device_key'
device.connect

Once the device is ready and authenticated sending a message is easy, we just need the name of the
channel ( data in this example) and a payload (in this case a JSON object with a value key
containing some random numbers):

require 'json'
# Publish one message every second for a minute on the ‘data’ channel
60.times do
  payload = { value: rand( 0 .. 100.0 ) }.to_json

  device.publish :data , payload
  
  puts "Published #{payload}"

  sleep 1
end

Reading live data from the device

While the previous script is running head back to the web interface and open the live data section:5

Select the appropriate channel, enter the key (or comma separated keys) that you want to plot (in our example it’s value ), and hit start:6

As long as the device is sending data, you’ll be able to see the graph updating live:7

Sending data to a device

In this example we’ll be using the web interface to send a message to a single device. If you want to learn how to send data between devices, check the [Sending message between devices] section. Open the device list and identify the device you want to send data to, then click on the SEND DATA option:5

Enter the message and press Send:9

The message will be delivered right away to the device. If the device is offline, the message is queued and will be delivered as soon as the device is back online.

Reading a message from the device

Using the SpaceBunny SDK you can set a callback fired each time the device receives a message:

require 'spacebunny'

device = Spacebunny::Device.new 'device_key'
device.connect

puts 'Waiting...'

device.inbox(wait: true, ack: :auto) do |message|
  puts "Received: #{message.payload}"
end

When you send a message from the interface you’ll see it right away. Note that if you sent
messages before enabling the reading script on the client, those messages are not lost, but they’ll be
received as soon as the device goes online.

Storing data

Until now we took advantage of the standard channels provided with the platform. As discussed in the [Before you start] section, channels are a way to separate data in different topics, but they also are a great way to enable specific features for a specific set of data streams. The data sent in the previous example is routed through the platform, but it’s not stored. Since we use channels, enabling the storage couldn’t be easier. First of, let’s make sure to enable the Persistence Plugin in the Plugins section:10

If the plugin was already enabled you should see a green light. Now we can head to the Channels section, and pick the Plugin option for the data channel (note that you can do the same for any channel you created):11

Now we can turn on the Data Persistence plugin for this channel:12

From now on every message sent to this channel will be also routed to the Data Persistence plugin, therefore it will be safely stored.

Retrieving stored data

Once the data is stored by the Data Persistence plugin, you can check the messages sent by a single device in the devices section:5

By selecting SHOW DATA you can see a raw representation of the messages sent:14

P. IVA: 01910420387