Setup

For this tutorial you will need to sign up for a set of accounts:

• Ship IoT
• LittleBits Cloud Control
• Slack

You will also need to acquire a CloudBit, based around a Freescale i.MX23 ARM 926EJ-S processor, from LittleBits. The parts we will use for this tutorial are:

• a 5V 2amp USB power supply
• a micro USB cable
• p3 usb power
• i3 button
• w20 cloud
• o9 bargraph

They should be assembled in series as follows:

Instructions for connecting the Cloudbit to your local WiFi network for the first time can be found on the Cloudbit Getting Started page. If you have already setup your Cloudbit, you can change the WiFi settings by going to your Cloudbit's page and going to Settings and selecting the following option:

If you don't already have a Slack account, you can create a new team and setup your own #littlebits channel for testing:

So by now, you have signed up for Ship IoT, have a CloudBit sitting on your desk, a Slack channel, and are wondering what's next?

Creating our first Bip

When you first Sign In to Ship IoT, you will encounter a friendly green button that looks like this:

Clicking that button will take you to a blank canvas onto which you can install an Event Source:

By clicking on the target in the middle, you will be presented with an Event selection screen:

We'll select "Incoming Web Hook" to provision a URL to which our CloudBit will send messages. In the field that say "Untitled":

Enter a path of "littlebits" for our Event Source, and we
should now have an event trigger on our canvas:

Next we will "Add An Action" which will bring us to an action selection screen:

If you scroll down a bit you will find a Slack pod which we can activate. Your first time through, it will request you to sign into your Slack account and authorize Ship IoT to access your Slack account. In the background it will provision a new access token and send you an email notifying you of that. In the future, you can deactivate this token through the Slack interface.

After you have activated the pod, you will be asked to select an action to perform:

In this case, our only option is to "Post to Channel". Selecting this action will result in another node in our bip:

Double click on the Slack icon to open up the action's preferences:

We can give the bip.io bot a name of "LittleBits":

We can select the "Channel ID" either using the "Use Preset" button which will attempt to discover the list of channels you have created, or you can supply a custom channel id:

Finally, we need to specify the "Message Text", and for this we will send the full message sent by the CloudBit by selecting "Incoming Web Hook Object":

After clicking OK, we can now link these together by dragging and dropping from the purple Event Source to the Slack action:

Now whenever a message is sent to https://yourname.api.shipiot.net/bip/http/littlebits it will be sent to our "Post to Channel" action!

Well not exactly. We still need allow LittleBits to send us messages. Under the "Auth" header, we can change the authentication type to "None":

Turning off auth makes our URL a shared secret that we should only share with LittleBits. Anyone with that URL will be able to send messages to our Slack channel, so some care should be taken not to share it!

Configuring a LittleBits Subscription

Configuring your CloudBit to talk to bip.io requires using the command line for a little bit. First we will need a little information from our Settings panel:

We will need to record both the Device ID and the AccessToken. These are needed to setup the subscription to our bip.iob application.

To setup a subscription requires a bit more black magic on our part. The CloudBit API Documentation describes how to make a HTTP request to register our device with a 3rd party subscriber. In our case, we would like to register our Incoming Web Hook URL as a subscriber to our CloudBit. To do so, we'll write a small bash shell script use curl in a script we'll name "subscribe":

#!/bin/bash

DeviceID=$1

AccessToken=$2

URL=$3

EVENTS=$4

curl -XPOST \

-H "Accept: application/vnd.littlebits.v2+json" \

-H "Authorization: bearer $AccessToken" \

https://api-http.littlebitscloud.cc/subscriptions \

-d publisher_id=$DeviceID \

-d subscriber_id=$URL \

-d publisher_events=$EVENTS

To use this script we need only make it executeable and run it:

$ chmod u+x subscribe

$ ./subscribe yourDeviceId yourAccessToken yourUrl "amplitude:delta:ignite"

This will cause the the URL you supply to be contacted each time the amplitude changes from low to high. If you want to have the value periodically reported instead you can just use the value of "amplitude" to get a message roughly every 750ms.

If the script works you will get a message back like:

{"publisherid":"xxxxxxxxxx","subscriberid":"http://yourname.api.shipiot.net/bip/http/littlebits","publisher_events":[{"name":"amplitude:delta:ignite"}]

This means your subscription has been registered and events are now flowing through the system.

Testing it out

If you push the button now:

A message should show up in your #littlebits channel:

You can use this same technique to drive any number of workflows through bip.io. All at the press of a button.