├── .gitignore ├── README.md ├── package.json └── seed-cloudbit-reader └── index.js /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # littleBits cloudBit API 2 | 3 | ## Example Lessons to Get Started 4 | 5 | ##### Developed for a ⧮ Hardware workshop at [NodeConf EU 2014](http://nodeconfeu.com/) 6 | 7 | 8 | 9 | ## Prerequisites 10 | 1. Have a littleBits account to associate your cloudBit to; [Create account](https://littlebits.cc/signup). 11 | 2. Have a Heroku account to host a webhook endpoint for your cloudBit (also, the heroku gem). 12 | 3. Visit Colin, tell him the email used for your littleBits account, get a cloudBit. 13 | 4. Get `ACCESS_TOKEN` and `CLOUDBIT_ID` from [Cloud Control](control.littlebitscloud.cc) 14 | 15 | 16 | 17 | ## Lessons 18 | 19 | ##### Lesson 1: Write to cloudBit 20 | 21 | 1. Try default output 22 | ```sh 23 | $ curl -i -XPOST \ 24 | -H "Authorization: Bearer ACCESS_TOKEN" \ 25 | https://api-http.littlebitscloud.cc/v3/devices/CLOUDBIT_ID/output 26 | ``` 27 | 28 | 2. Try 50% output for 5 seconds 29 | ```sh 30 | $ curl -i -XPOST \ 31 | -H "Authorization: Bearer ACCESS_TOKEN" \ 32 | https://api-http.littlebitscloud.cc/v3/devices/CLOUDBIT_ID/output \ 33 | -d percent=50 \ 34 | -d duration_ms=5000 35 | ``` 36 | 37 | 3. Investigate the HTTP API docs for how you can send a perpetual output percentage to your cloudBit 38 | 39 | 40 | ##### Lesson 2: Read from cloudBit 41 | 42 | 1. Get the cloudBit's current input voltage 43 | 44 | ```sh 45 | $ curl -i \ 46 | -H "Authorization: Bearer ACCESS_TOKEN" \ 47 | https://api-http.littlebitscloud.cc/v3/devices/CLOUDBIT_ID/input 48 | ``` 49 | 50 | This will start a stream of values, you can stop by hitting `ctrl-c`. Each value 51 | will be a `json` object with a bunch of metadata. The most useful one in most cases being: 52 | 53 | `data.percent` 54 | 55 | You will see the `percent` value near the end of the response, in the below example, `"percent":69` 56 | 57 | ``` 58 | 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}} 59 | ``` 60 | 95 | 96 | ##### Lesson 3: Read from cloudBit with remote app 97 | 98 | Replace `YOUR_APP` with the application name you would like. 99 | 100 | 1. Deploy the demo cloudBit reader app to Heroku 101 | 102 | ```sh 103 | $ git clone git@github.com:littlebits/cloud-api-lessons.git \ 104 | && cd cloud-api-lessons \ 105 | && heroku apps:create YOUR_APP \ 106 | && git push heroku 107 | ``` 108 | 109 | 2. Tell the app to read from your cloudBit 110 | 111 | ```sh 112 | $ curl -i -XPOST \ 113 | -H "Authorization: Bearer ACCESS_TOKEN" \ 114 | https://api-http.littlebitscloud.cc/v2/subscriptions \ 115 | -d publisher_id=CLOUDBIT_ID \ 116 | -d subscriber_id=http://YOUR_APP.herokuapp.com 117 | ``` 118 | 119 | 3. Inspect your cloudBit's current "readers" (AKA subscribers) 120 | 121 | ```sh 122 | $ curl -H \ 123 | "Authorization: Bearer ACCESS_TOKEN" \ 124 | https://api-http.littlebitscloud.cc/v2/subscriptions?publisher_id=CLOUDBIT_ID 125 | ``` 126 | 127 | 4. Stop reading 128 | 129 | ```sh 130 | $ curl -H -XDELETE \ 131 | "Authorization: Bearer ACCESS_TOKEN" \ 132 | https://api-http.littlebitscloud.cc/v2/subscriptions \ 133 | -d publisher_id=CLOUDBIT_ID \ 134 | -d subscriber_id=http://YOUR_APP.herokuapp.com 135 | ``` 136 | 137 | 5. Investigate the HTTP API docs for how you can make one cloudBit read from another 138 | 139 | 140 | #### Lesson 4: Make a mash-up! 141 | 142 | Ok, not really a lesson. Create an original mashup between your cloudBit and 143 | another service that does something awesome. Best mash-up wins some littleBits 144 | including a cloudBit :) 145 | 146 | ## Resources 147 | - cloudBit Cloud Control app: http://littlebits.cc/cloudstart 148 | - littleBits Cloud HTTP API docs: http://developer.littlebitscloud.cc 149 | - HTTP API library: https://github.com/littlebits/cloud-client-api-http 150 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "littlebits-nodeconfeu-demo", 3 | "version": "0.0.1", 4 | "description": "littleBits NodeConf EU demo", 5 | "main": "./seed-cloudbit-reader/index.js", 6 | "engines": { 7 | "node": ">= 0.11.13" 8 | }, 9 | "scripts": { 10 | "start": "node --harmony ./seed-cloudbit-reader/index.js", 11 | "dev": "NODE_ENV=dev node-dev --harmony ./seed-cloudbit-reader/index.js" 12 | }, 13 | "repository": { 14 | "type": "git", 15 | "url": "git@github.com:littlebitselectronics/nodeconfeu" 16 | }, 17 | "devDependencies": { 18 | "node-dev": "~2.1.6" 19 | }, 20 | "dependencies": { 21 | "koa": "^0.14.0", 22 | "koa-parse-json": "^1.0.0", 23 | "koa-route": "^2.4.0" 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /seed-cloudbit-reader/index.js: -------------------------------------------------------------------------------- 1 | var koa = require('koa') 2 | var koaParseJson = require('koa-parse-json') 3 | var route = require('koa-route') 4 | 5 | 6 | 7 | var port = Number(process.env.PORT) || 7800 8 | var app = koa() 9 | 10 | 11 | 12 | app.use(koaParseJson()) 13 | 14 | 15 | 16 | /* On a root GET respond with a friendly message explaining that this 17 | application has no interesting client-side component. */ 18 | 19 | app.use(route.get('/', function *() { 20 | 21 | this.body = 'Hello, this is a trivial cloudBit Reader App. Nothing else to see here; all the action happens server-side. To see any recent input activity from webhook-registered cloudBits do this on the command line: `heroku logs --tail`.' 22 | 23 | })) 24 | 25 | 26 | 27 | /* On a root POST log info about the (should be) cloudBit event. */ 28 | 29 | app.use(route.post('/', function *() { 30 | 31 | console.log('received POST: %j', this.request.body) 32 | 33 | if (this.request.body && this.request.body.type) { 34 | handleCloudbitEvent(this.request.body) 35 | } 36 | 37 | this.body = 'OK' 38 | 39 | })) 40 | 41 | 42 | 43 | app.listen(port) 44 | console.log('App booted on port %d', port) 45 | 46 | 47 | 48 | // Helpers 49 | 50 | function handleCloudbitEvent(event) { 51 | switch (event.type) { 52 | case 'amplitude': 53 | // Do whatever you want with the amplitde 54 | console.log('cloudBit input received: %d%', event.payload.percent) 55 | break 56 | case 'connectionChange': 57 | // One day, cloudBits will emit this event too, but not yet. 58 | break 59 | default: 60 | console.warn('cloudBit sent an unexpected event: %j', event) 61 | break 62 | } 63 | } 64 | --------------------------------------------------------------------------------