Skip to content

Usage

Jump to bottom
Jon Hall edited this page Jul 14, 2018 · 5 revisions

Swill SDK can be used as both a Node module and a client-side library. When npm install is run, the client sdk is automatically bundled into lib/swill-sdk.min.js.

Keep in mind, you will always need a running CraftBeerPi3 instance for Swill SDK to talk to.

Client-side

All that is needed to use Swill SDK in the browser is to include it in a script tag in your app:

<script src="swill-sdk.min.js"></script>

The SDK itself will be available on the on global scope via window.SwillSDK.

Node.js

Install the sdk as a dependency of your node project:

 npm i -D https://github.com/jonrhall/swill-sdk

Require it as part of your project:

const SwillSDK = require('swill-sdk');

... do something

Example SDK client

// Import the library
const SwillSDK = require('swill-sdk');

// Instantiate SDK
const sdk = SwillSDK();

// Do basic things, like listen for events you think you'd like to do something with.
sdk.resources.sensors.onUpdate((event, data) =>
    console.log('A sensor update occurred! ${event}, ${data}'));

// Control specific resources, like actors, and get their configuration.
// Get the actors available:
const actors = await sdk.resources.actors.getActors();

// Perform more advanced tasks, like setting a kettle's target temperature.
// Get the kettles list, and set the target temperature to 132. Assume old temp is 100.
const kettles = await sdk.resources.kettles.getKettles(),
  promise = kettles[0].setState({target_temp: 132});
// Before the promise resolves, the temperature will not be updated
console.log(kettles[0].target_temp) // 100
console.log(await promise) // {agitator: "", automatic: null, config: {…}, target_temp: "132", id: 1, …} (the updated sensor object itself)
console.log(kettles[0].target_temp) // 132

Development server

Inside of the install location for Swill SDK, if you run the command npm run dev:server you will spawn a continuously running development server. Open your browser to http://<ip-address>:8080/index.html and open the browser's development console. Here is a sample set of commands you can run:

> const sdk = SwillSDK({socketAddress:`http://${window.location.hostname}:5000`,httpAddress:`http://${window.location.hostname}:5000`});
> undefined
> await sdk.resources.actors.getActors();
> // See what happens next :)

Deploying your app with Swill SDK

If you use Swill SDK as a Node app, you can ignore this section.

If you plan on making your app available in a web browser, you'll either need to host/deploy it to your own personal server, or use your Raspberry Pi and CraftBeerPi to do it for you. Keep in mind that if you go deploy it yourself, you will need to install CORS for CraftBeerPi in order for any web clients to accept responses from the CBPi server in the first place.

It is generally recommended that you run your code bundled with the SDK, copied into the same folder that CraftBeerPi3 hosts its resources from (normally something like /path/to/craftbeerpi3/modules/ui/static). Files dropped into that location are available from the same host and port URL that you access CraftBeerPi3 from, by default http://<raspi-address:5000/ui/static.

Gotchas

CORS

If you are using the client-side SDK and you are not running your resources on the same host and port as CraftBeerPi3 (generally by dropping your files directly in the craftbeerpi3/modules/ui/static/ folder), you will run into CORS (Cross-Origin Resource Sharing) request issues with the CraftBeerPi3 server.

For example, this will happen when you attempt to run the development server.

By default, CraftBeerPi3 does not support requests from origins other than its own. This can be remedied a few ways. Either move your files to the folder mentioned above so that they run on the same host and port as CBPi, or do the following to enable CORS support in CraftBeerPi3.

We also take the time to expose the 'Content-Length' header in CraftBeerPi3 responses, so that logs can be queried for size before being downloaded by clients (officially supported via sdk.logs.getDetails function).

Installing Flask-CORS

  1. From inside your CraftBeerPi3 directory (normally something like ~/craftbeerpi3/), install Flask-CORS 
 pip install -U flask-cors
  1. Edit your modules/__init__.py file and add the following
import json
import pprint
import sys, os
from flask import Flask, render_template, redirect
from flask_socketio import SocketIO, emit
from flask_cors import CORS # ****** ADD THIS ********

...

from modules.core.db import get_db

CORS(app, expose_headers=['Content-Length']) # ***** AND ALSO ADD THIS ******

@app.route('/')
def index():
    return redirect('ui')

...
  1. Restart your CBPi instance:
sudo /etc/init.d/craftbeerpiboot stop && sudo /etc/init.d/craftbeerpiboot start
  1. CORS should now be supported, connect your clients

Clone this wiki locally