cloudBit API guide

#cloudBit API guide

If you’ve been using IFTTT with the cloudBit you might have noticed that not all of your favorite services have channels yet. Or you would like integrate the cloudBit into your own service and need some examples to get you going.

This guide is meant to accompany the API documentation found on here: http://developer.littlebitscloud.cc/.

You can also find all some examples at: https://github.com/littlebits/cloud-api-lessons

##Couple of things to note:

cloudBit does not work locally and needs to be connected to the Internet. All of these examples assume that your cloudBit is connected and has a green status light.

##Output

The quickest way to get started is make some output to your cloudBit. All you have to do is POST to our endpoint and it’ll trigger output for 3 seconds at 100%.

Output to your cloudBit:

You’ll need to be using a unix command line tool curl, if you’re on a mac/linux you can just hop into terminal:

$ curl -i -XPOST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api-http.littlebitscloud.cc/v2/devices/CLOUDBIT_ID/output

CLOUDBIT_ID

Is the ID or MAC ADDRESS of your cloudBit, each cloud bit has a unique ID, you can find this in the settings tab of Cloud Control.

ACCESS_TOKEN
Is your authorization token, which you can also find under the “Advanced Section”.

You’ll notice that we are using an HTTP header to pass our token (that’s what the line -H "Authorization: Bearer ACCESS_TOKEN" is doing). You can set a custom http header with your http request, here are some examples in python: http://stackoverflow.com/questions/7933417/how-do-i-set-headers-using-pythons-urllib

Output parameters
Now if you’d like to change the amount of output and how long you’d like it to go you’ll need send these parameters in your request:

$ curl -i -XPOST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api-http.littlebitscloud.cc/v2/devices/CLOUDBIT_ID/output \
-d '{"percent":50 , "duration_ms":5000}'

This will send two more header parameters that tell the cloudBit to send an output for 5 seconds at 50% amplitude.

Here’s a fun gif of a Minecraft mod outputting signal from redstone:

##Input

There a few ways for you to read input from your device, Webhook, Server-Side Events(SSE) or WebSockets. We’ll cover the first two below.

###Webhook

With a webhook you’re basically saying that one web application/shim of yours should received an input event every time your cloudBit generates one. It’s a kind of pub/sub model where the web shim will receive a POST from the cloudBit, and from there you can do whatever you want with your input value.

$ curl -i -XPOST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api-http.littlebitscloud.cc/v2/subscriptions \
-d '{"publisher_id":"<CLOUDBIT_ID>" , "subscriber_id":"https://YOUR_APP.com"}'

###Server-Side Events (SSE)

Here’s a really cool feature that we implemented recently that lets us stream input events via SSE so you can get a live view how values are coming in to your circuit. Objects that are being streamed will be come in as JSON objects prepended with a string, data. Here’s an example of the output:

$ curl -i -XGET\
-H "Authorization: Bearer ACCESS_TOKEN" \
https://api-http.littlebitscloud.cc/v2/devices/CLOUDBIT_ID/input

data:{"type":"input","timestamp":1415472471048,"from":{"user":{"id":1323},"device":{"id":"1a2b3c4d5e6f","device":"littlebits-module-cloud","setup_version":"1.0.0","protocol_version":"1.1.0","firmware_version":"1.0.140820b","mac":"1a2b3c4d5e6f","hash":"XXXXXXXXXXXXXXXXXXXXXXXXXXX","ap":{"ssid":"MySuperInternet!","mac":"AA:BB:CC:DD:EE:FF","strength":100}},"server":{"id":"QkZVqqe"}},"percent":69,"absolute":709,"name":"amplitude","payload":{"percent":69,"absolute":709}}

The cloudbit is really one of the greatest and potentially most amazing LBs and I appreciate the API documentation but it’s too technical and terse to be of much use to your core target demographic which includes amateur enthusiasts and parents learning along with their kids like myself. This is written for network engineers.

How hard would it be to write a simple well documented python wrapper? I’ve been waiting for one for more than a year. Users have posted some scripts to github but if you read through the Issue tickets at https://github.com/littlebits/cloud-platform/issues and you can see that the small group of enthusiasts who were trying to make this work didn’t get far past the littlebits team’s seeming lack of interest in making this any more user friendly or refashioned to user needs.

I can get python to read the JSON stream from the input device but it has been a challenge to parse and tame because the stream object and its associated byte formats are difficult to understand and work with (and handling changes from python 2 to 3). All I ever wanted to do was to be able to poll the device to get one number to tell me the current reading of the input.

The philosophy behind littlebits I thought was to bring technology to the amateur enthusiasts and encourage them to learn and explore. Your Arduino documentation is so much better and allows the user to start making projects immediately.

There are hundreds of easy to use and well documented python API wrappers that companies such as google and facebook have promoted because they’ve understood how it’s led to more customers, demand-side feedback and innovation. Why not littlebits? How long would it take you to write a simpler python wrapper and clearer documentation and maybe a sample project? I guarantee you that you’d expand your user base and make many of your existing customers happy.

1 Like

Thank you! I absolutely agree. +1 :slight_smile: LittleBits, are you listening?

Also, API v3 was hinted at in this post this summer but still hasn’t been released yet, and my tests showed that the v3 API doesn’t even work anymore as this article describes. I can’t wait for v3 to come out, so I hope it hasn’t been abandoned. :frowning:

I’ve built a website that exists to solve this kind of problem. Your project needs an HTTP server, but the number of layers you need to learn to make that happen is daunting. Here’s an app (PC only) that builds a slightly different version of the existing CloudBit controller. Paste in your AccessToken and you’re good to go. It will also turn your Littlebits signals into an RSS feed that you can view elsewhere, and it makes it easy to share the page so others can view it.

The point of this is that all the code that powers that app is built in a single language and editable right in the website. You can see the code here.

If you want to learn more or add features like SMS messaging, I’m happy to answer questions and help out. The tool still needs improvements and additions, but if you want to create an HTTP listener I don’t know of a shorter path to get there.

I have been able to successfully POST into my device’s OUTPUT path.

As long as I do not specify an http request body, then the default of 100 percent for 3000ms is invoked and my LED will light up at full strength for 3 seconds.

If, however, I specify my custom percentage and duration, then I get a status code 400 bad request. I even copied the JSON request body exactly as shown in the api documentation.

Can you tell me why my httpRequest body of {"percent":100, "duration_ms":3000} is being denied?

So I just solved my own problem but to me, the documentation was misleading. The documentation shows the request body in json format. But the content-type header cannot be set to json. So I set my content-type header to application/x-www-form-urlencoded and set my httpRequest body to be percent=100&duration_ms=3000 and all is well in the world!

@rtstrunk Thanks for that insight. Could a longer sample of code to see how it works?

Sure thing. Here is the full Apex Class I wrote to perform the call. Apex is a proprietary cloud based programming language that is very similar to Java.

    public with sharing class Cloudbits_Callout {

    public Http transporter;
    public HttpRequest payload;
    public HttpResponse outcome;

    public void doCall(){

        payload = new HttpRequest();
        payload.setHeader('Authorization','Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
        payload.setHeader('Accept','application/vnd.littlebits.v2+json');
        payload.setBody('percent=100&duration_ms=10000');
        payload.setEndpoint('https://api-http.littlebitscloud.cc/devices/XXXXXXXXXXX/output');
        payload.setMethod('POST');

        transporter = new Http();
        outcome = transporter.send(payload);

        System.debug(outcome.getStatusCode());
        System.debug(outcome.getStatus());
        System.debug(outcome.getBody());
        System.debug('Body was :::'+payload.getBody());
    }

    public class Output{Integer percent;Integer duration_ms;}
    public class error{String code;String error;String message;}
}

The v3 and master versions of the api stopped working sometime in the last couple of days. These examples no longer work - they return a 404 error:

curl -i -H "Authorization: Bearer MY_TOKEN" https://api-http.littlebitscloud.cc/v3/devices
curl -i -H "Authorization: Bearer MY_TOKEN" https://api-http.littlebitscloud.cc/master/devices

Only the v2 versions seems to work now.

I have code that works for the v3 and master versions of the api that no longer works.

Is this a temporary issue?

Yes, we are listening. And while SDK libraries are on our mind, we haven’t got ETA yet. Bear with us!

Hi Carl,

Thank you for raising this issue!

v3 and master endpoints were terminated this week. I am sorry we haven’t communicated this properly! However, the behavior you’re looking for works with v2. I have updated this post to mirror that fact. Would you try it and let me know?

Thank you once more! You guys rock our world :slight_smile:

UPDATE: Guys, we’ve been deprecating our form-based API in favor or the JSON one. I have updated the post accordingly. We are researching new, better APIs and we’re confident we’ll have news in a couple quarters time.

Thanks @pires. I love me a good four-syllable word in an online forum! :heart_eyes:

1 Like

According to some of the API documentations, the Cloudbit API supports a PUT command, to update the device remotely.

I able to access it, and it returns HTTP status code 200 - but it doesn’t update say the label of the device.

Is this end-point available? If yes, what does it take to get it working?