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}}
