First Steps: API Overview

Mario Schreiner edited this page Jan 13, 2015 · 43 revisions

TOC

Include the API

In order to use any Connichwa functions, you need the following in your <head>:

<script src="/connichiwa/scripts/gyro.min.js"></script>
<script src="/connichiwa/scripts/jquery.js"></script> <!-- You can also use your own jQuery -->
<script src="/connichiwa/connichiwa.min.js"></script>

Detection & Connecting

There are numerous events related to device detection and connection. You can attach one ore more callback functions to a device using Connichiwa.on(event, callback), for example:

Connichiwa.on("deviceConnected", function(device) {
    /* Do something with the connected device */
});

Every such callback will receive a single argument of type CWDevice. See the API Documentation to learn the details of CWDevice.

Detection

When a device running a Connichiwa application (currently iOS or Mac OS X devices) is near your device, it will be detected using Bluetooth and trigger the deviceDetected event. When the Connichiwa application is terminated, Bluetooth is switched off or the device moves out of range, it will trigger the deviceLost event.

Please note that devices that connect directly through a web browser will not trigger detection events, but only connection-related events.

Example:

Connichiwa.on("deviceDetected", function(device) {
    //Create a div that represents the device and add it to the body.
    //This way, we will see a list of all nearby devices
    var deviceDiv = $("<div></div>");
    deviceDiv.attr("id", "device-"+device.getIdentifier());
    deviceDiv.html("<b>"+device.getName()+"</b>");
    $("body").append(deviceDiv);
});

Connichiwa.on("deviceLost", function(device) {
    $("#device-"+device.getIdentifier()).remove();
});

Distance Approximation

The distance to detected devices is approximated and accessible through the CWDevice's distance property. The distance if given in meters. Changes in the distance trigger the deviceDistanceChanged event. Please be aware that this distance is an approximation based on the bluetooth signal strength. This approximation can be inaccurate, in particular with many Bluetooth devices nearby. Your application should never rely on exact values.

Example:

Connichiwa.on("deviceDistanceChanged", function(device) {
    //Update the device's div to include the current distance
    $("#device-"+device.getIdentifier()).html("<b>"+device.getName()+"</b><br/>"+device.distance+"m");
});

Connections

Your application can connect detected devices by calling the CWDevice's connect() method. Devices that use a web browser will automatically connect without your application having to call any method. However a device is connected, the connection process will either trigger the deviceConnected event on success or the connectFailed event on failure.

After a device was successfully connected it can be used by your application. This means that your application can execute JavaScript on it, show or update content, receive and send messages etc.

Example:

var devices = [];

Connichiwa.on("deviceDetected", function(device) {
    device.connect();
});

Connichiwa.on("deviceConnected", function(device) {
    //We can finally do something with the device, for example show content
    device.insert("<b>Connected!</b>");

    //We can also execute custom JavaScript on the device. The JavaScript 
    //can use the Connichiwa API, which is auto-loaded on remote devices.
    //Obviously, this line assumes there is a file "customScript.js" in the
    //root of your web application.
    device.loadScript("/customScript.js");

    //We can also sent custom messages to the device that it can subscribe to
    device.send("doRotate", { degrees: 90 });

    //Obviously, we can also remember the device for use somewhere else in the application
    devices.push(device);
});

Executing JavaScript on remote devices

Connected devices only gets really useful if you can execute JavaScript on them. Remote devices automatically include the Connichiwa library, so you can use the Connichiwa API. There are three ways to execute JS:

  1. Insert a <script> tag using Connichiwa.insert(). device is a CWDevice object.

    Connichiwa.insert(device, "<script>alert('custom javascript on remote devices!');</scr"+"ipt>");
  2. Using Connichiwa.loadScript method to load an entire file. device is a CWDevice object. The callback is optional and is called after the JavaScript was loaded:

    Connichiwa.loadScript(device, "/myScript.js", function() {
        alert("myScript.js was loaded and can be used!");
    });
  3. Connichiwa automatically loads any scripts in the Connichiwa.autoLoadScripts array on any newly connected device:

        if (Connichiwa.isMaster()) Connichiwa.autoLoadScripts = [ "/firstScript.js", "secondScript.js" ];

Send & Receive Custom Messages

To communicate between devices, Connichiwa offers several functions for message exchange. In general, you can create a message and send it to one or more devices. You can also set up message handlers that execute a callback function when a certain message is received.

Connichiwa.send(device, name, message) is the main way of sending messages. It sends a message to a single device. The device is a CWDevice or the string "master". name is the message name and message is an arbitrary object that will be sent to the device. Please note that message should not contain keys that begin with an underscore _, these are reserved by Connichiwa.

Connichiwa.broadcast(name, message, sendToSelf) works like send(), but sends the message to all other devices. If sendToSelf is set to true, the message will also be sent to the device from which the message originates.

Connichiwa.respond(originalMessage, name, message) is a convenience function to send a message back to the device from which originalMessage originated from.

Connichiwa.onMessage(name, callback) will install callback as a handler for messages with name name. Whenever a message with the name name is received, callback will be called and the received message will be passed to it. Multiple callbacks can be installed for messages with the same name by calling onMessage multiple times.

Example:

//We will add the file containing this code to the autoLoadScripts. This
//is a common pattern where we use a single JavaScript file on the master and
//all remote devices. 

//This script also makes use of Connichiwa.autoConnect, which will connect any
//detected device automatically. It is a shortcut for:
//Connichiwa.on("deviceDetected", function(device) { device.connect(); });

if (Connichiwa.isMaster()) {
    Connichiwa.autoLoadScripts = [ "/main.js" ];
    Connichiwa.autoConnect = true;
    Connichiwa.on("deviceConnected", function(device) {
        device.insert("<b>I am connected!</b>");

        //Rotate the content of every connected device
        Connichiwa.send(device, "doRotate", { angle: 45 });
    });
}

//Setup the message handler. We do this on all devices (master and remotes)
Connichiwa.onMessage("doRotate", function(message) {
    $("body").css("transform-origin", "0 0");
    $("body").css("transform", "rotate("+message.angle+"deg)");
});

A common problem is that you need to know where a message came from. Connichiwa adds a _source property to every message. It contains the unique string identifier of the source device:

var lastRotate = {};
Connichiwa.onMessage("doRotate", function(message) {
    //If we receive multiple "doRotate" messages from the same device 
    //in quick succession, ignore them
    if (message._source in lastRotate && (Date.now() - lastRotate[message._source]) < 100) {
        return;
    }

    $("body").css("transform-origin", "0 0");
    $("body").css("transform", "rotate("+message.angle+"deg)");
    lastRotate[message._source] = Date.now();
});

Device Stitching

Connichiwa supports "device stitching", which means determining the relative position of two devices using a cross-device gesture. The documentation for this will be coming soon :-)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.