If the user has an active session on the remote Canopy server (for example if they went to https://sandbox.canopy.link and logging in), you can initialize the library with:

Canopy.initUserClient({
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        // An error occured.
        // If the user is not logged in then result==CANOPY_ERROR_NOT_LOGGED_IN
        alert(responseData.errorMsg);
        return;
    }

    // Success!
    // responseData.user contains the CanopyUser object for the
    // signed in user.
    var user = responseData.user;
    ...
});

You may want to change http://sandbox.canopy.link in the above example to your Canopy remote.

The Canopy.initUserClient() call accepts many additional parameters described in the documentation for (CanopyContext).initRemote().

To instead use BASIC AUTH to interact with the remote Canopy server on behalf of a User, provide ther User's credentials to Canopy.initUserClient():

Canopy.initUserClient({
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        // An error occurred.
        // If the credentials are incorrect then result==CANOPY_ERROR_BAD_CREDENTIALS
        alert(responseData.errorMsg);
        return;
    }

    // Success!
    // responseData.user contains the CanopyUser object for the
    // authenticated user.
    var user = responseData.user;
    ...
});

To instead use the library on behalf of a Device, use Canopy.initDeviceClient() and provide the Device's ID and Secret Key.

Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's ID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        // An error occurred.
        // If the credentials are incorrect then result==CANOPY_ERROR_BAD_CREDENTIALS
        alert(responseData.errorMsg);
        return;
    }

    // Success!
    // responseData.device contains the CanopyDevice object for the
    // authenticated device.
    var device = responseData.device;
    ...
});

var ctx = Canopy.initContext();

var remote = ctx.initRemote({
    "host" : "sandbox.canopy.link"
});

// You can now call remote.createUser({...}) for example.

Canopy.initContext()

var ctx = Canopy.initContext();

Canopy.initDeviceClient(params)

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("Hi " + responseData.device.name());
});

Canopy.initUserClient(params)

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

Canopy.initUserClient({
    "auth-username" : "myUsername", 
    "auth-password" : "myPassword",
    "host" : "dev02.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("Hi " + responseData.user.username());
});

Canopy.initRemote(params)

Takes a single object as its only parameter. This object may have the following members:

var ctx = Canopy.initContext();

(CanopyContext).shutdown()

// Silly example:
Canopy.initContext().shutdown();

(CanopyRemote).apiBaseUrl()

(CanopyRemote).baseUrl()

(CanopyRemote).createUser(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

(CanopyRemote).getSelfUser()

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

var ctx = Canopy.initContext();

var remote = ctx.initRemote({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's ID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
});

remote.getSelfDevice().onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("You are a device named " + responseData.device.name());
});

(CanopyRemote).getSelfUser()

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

var ctx = Canopy.initContext();

var remote = ctx.initRemote({
    "auth_type" : "basic",
    "auth_username" : "myUsername",
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
});

remote.getSelfUser().onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("Hi " + responseData.user.username());
});

(CanopyRemote).login()

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

var ctx = Canopy.initContext();

var remote = ctx.initRemote({
    "auth_username" : "myUsername",
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
});

remote.login().onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("Hi " + responseData.user.username());
});

(CanopyRemote).logout()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

var ctx = Canopy.initContext();

var remote = ctx.initRemote({
    "host" : "sandbox.canopy.link"
});

remote.logout().onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    alert("You've been logged out ");
});

(CanopyRemote).requestPasswordReset(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyRemote).resetPassword(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyUser).changePassword(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyUser).createDevices(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

// Initialize library and authenticate
Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    // Create 3 new devices
    responseData.user.createDevices({
        quantity: 3,
        names: ["Toaster", "Lightbulb", "Refridgerator"]
    }).onDone(function(result, responseData) {
        if (result != CANOPY_SUCCESS) {
            alert("Error creating devices: " + responseData.errorMsg);
            return;
        }

        alert("Devices created!");
    }
}

(CanopyUser).devices()

Canopy.initUserClient({
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }
    responseData.user.devices().getMany(0, 10).onDone(function(result, deviceData) {
        if (result != CANOPY_SUCCESS) {
            alert(deviceData.errorMsg);
            return;
        }
        for (var i = 0; i < deviceData.devices.length; i++) {
            var device = deviceData.devices[i];
            console.log(device.name() + "(" + device.id() + ")");
        }
    });
});

(CanopyUser).email()

To set the User's email address:

(CanopyUser).email(newEmail)

Returns the newly-assigned email address if any.

var myNewEmail = "canopytest@mailinator.com";

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    var user = responseData.user;
    var oldEmail = user.email();
    user.email(myNewEmail);

    // Push change to remote:
    user.updateToRemote().onDone(function(result, responseData) {
        if (result != CANOPY_SUCCESS) {
            alert("Error changing email: " + responseData.errorMsg);
            return;
        }

        alert("Email changed from " + oldEmail + " to " + newEmail);
    }
}

(CanopyUser).isValidated()

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }
    if (responseData.user.isValidated()) {
        alert("You're a good person!"));
    } else {
        alert("Please check your email!"));
    }
}

(CanopyUser).remote()

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    var remote = canopy.user.remote();
}

(CanopyUser).syncWithRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyUser).updateFromRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyUser).updateToRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

var myNewEmail = "canopytest@mailinator.com";

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    var user = responseData.user;
    var oldEmail = user.email();
    user.email(myNewEmail);

    // Push change to remote:
    user.updateToRemote().onDone(function(result, responseData) {
        if (result != CANOPY_SUCCESS) {
            alert("Error changing email: " + responseData.errorMsg);
            return;
        }

        alert("Email changed from " + oldEmail + " to " + newEmail);
    }
}

(CanopyUser).username()

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    alert("Hello " + responseData.user.username());
}

(CanopyUser).validate(params)

Takes a single object as its only parameter. This object must have the following members:

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyDevice).id()

Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert("Error: " + responseData.errorMsg);
        return;
    }

    alert(responseData.device.id());
    /* OUTPUT: 8f0dad00-2f45-4726-bd08-ceb0530f70c8 */
}

(CanopyDevice).isActive()

• true if this CanopyDevice has interacted with the remote Canopy server within the past 60 seconds, as of the most recent synchronization with the remote Canopy server.
• false otherwise.

(CanopyDevice).isInactive()

• false if this CanopyDevice has interacted with the remote Canopy server within the past 60 seconds, as of the most recent synchronization with the remote Canopy server.
• true otherwise.

(CanopyDevice).isNewlyCreated()

• true if this CanopyDevice is newly created, meaning it has never interacted with the remote Canopy server, as of the most recent synchronization with the remote Canopy server.
• false otherwise.

(CanopyDevice).lastActivitySecondsAgo()

(CanopyDevice).lastActivityTime()

(CanopyDevice).locationNote()

To set the device's location note:

(CanopyDevice).locationNote(newLocationNote)

Returns the newly-assigned location note if any.

(CanopyDevice).name()

To set the device's name:

(CanopyDevice).name(newName)

Returns the newly-assigned name if any.

(CanopyDevice).secretKey()

(CanopyDevice).syncWithRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyDevice).updateFromRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyDevice).updateToRemote()

On success, the responseData parameter of the Barrier's .onDone() callback will contain an empty object {}.

(CanopyDeviceQuery).count()

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        $("#main").html("Error: " + responseData.errorMsg)
        return;
    }

    responseData.user.devices().count().onDone(function(result, countData) {
        if (result != CANOPY_SUCCESS) {
            $("#main").html("Error: " + countData.errorMsg)
            return;
        }

        alert("You have access to " + countData.count + " devices");
    });
})

(CanopyDeviceQuery).filter(expr)

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        $("#main").html("Error: " + responseData.errorMsg)
        return;
    }

    dq = responseData.user.devices();
    dq = dq.filter("HAS latitude").filter("HAS longitude");
    dq.count().onDone(function(result, countData) {
        if (result != CANOPY_SUCCESS) {
            $("#main").html("Error: " + countData.errorMsg)
            return;
        }

        alert(" " + countData.count + " devices are reporting geo coords");
    });
})

(CanopyDeviceQuery).get(idOrIndex)

• String - to select by device ID, or
• Integer - to select by row index into this CanopyDeviceQuery's selection.

On success, if the requested device is found, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

If the device is not found as part of this CanopyDeviceQuery's selection, then the result parameter will be CANOPY_ERROR_NOT_FOUND.

Canopy.initUserClient({
    "auth_type" : "basic",
    "auth_username" : "myUsername", 
    "auth_password" : "myPassword",
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        $("#main").html("Error: " + responseData.errorMsg)
        return;
    }

    // Get user's first device
    responseData.user.devices().get(0).onDone(function(result, deviceData) {
        if (result != CANOPY_SUCCESS) {
            $("#main").html("Error: " + countData.errorMsg)
            return;
        }

        alert("Your first device is:" + deviceData.device.name());
    });
})

(CanopyDeviceQuery).getMany(start, count)

On success the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

(CanopyVariable).datatype()

Will be one of the following:

// Initialize library and authenticate device
Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }

    // Loop over cloud variables and say their datatypes
    var cloudVars = responseData.device.vars();
    for (var i = 0; i < cloudVars.length; i++) {
        alert("Cloud Var " + cloudVars[i].name() + "has datatype " + cloudVars[i].datatype());
    }
});

(CanopyVariable).device()

// Initialize library and authenticate device
Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }

    // Loop over cloud variables and confirm their device object is
    // correct.
    var cloudVars = responseData.device.vars();
    for (var i = 0; i < cloudVars.length; i++) {
        if (cloudVars[i].device() != responseData.device) {
            // This will never happen
            alert("Something is seriously broken!");
        }
    }
});

(CanopyVariable).direction()

// Initialize library and authenticate device
Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }

    // Loop over cloud variables and say their directions
    var cloudVars = responseData.device.vars();
    for (var i = 0; i < cloudVars.length; i++) {
        alert("Cloud Var " + cloudVars[i].name() + "has direction " + cloudVars[i].direction());
    }
});

(CanopyVariable).historicData(startTime, endTime)

On success, the responseData parameter of the Barrier's .onDone() callback will contain the following fields:

[{
    t : "2015-04-15T04:32:02Z",
    v : 143.2
}, ...]

// Initialize library and authenticate device
Canopy.initDeviceClient({
    "auth_username" : "8f0dad00-2f45-4726-bd08-ceb0530f70c8", /* Your Device's UUID */
    "auth_password" : "h/1zaP3SrYGqCE2/Ior7ZbMDNVkIExVp",     /* Your Devices' Secret Key */
    "host" : "sandbox.canopy.link"
}).onDone(function(result, responseData) {
    if (result != CANOPY_SUCCESS) {
        alert(responseData.errorMsg);
        return;
    }

    // Get temperature cloud variable, if any.
    var temperature = responseData.device.varByName("temperature");
    if (!temperature) {
        console.log("This device does not have cloud var \"temperature\"");
        return;
    }

    // Fetch historic temperature data for this device
    temperature.historicData().onDone(function(result, historicData) {
        if (result != CANOPY_SUCCESS) {
            console.log("Error: " + historicData.errorMsg);
            return;
        }

        // Dump all samples:
        for (var i = 0; i < historicData.samples.length; i++) {
            console.log("Time: " + historicData.samples[i].t);
            console.log("Value: " + historicData.samples[i].v);
        }
    });
});

(CanopyVariable).isModified()

• true - This Cloud Variable has been set locally since the last synchronization with the remote.
• false - Otherwise.

(CanopyVariable).lastRemoteUpdateTime()

(CanopyVariable).lastRemoteValue()

The datatype of the return value depends on the Cloud Variable's datatype.

(CanopyVariable).lastRemoteUpdateSecondsAgo()

(CanopyVariable).name()

(CanopyVariable).value()

To set the Cloud Variable's value:

(CanopyVariable).value(newValue)

(CanopyBarrier).onDone(function(result, responseData) { ... })

Takes a single callback function as a parameter. This callback must accept two parameters: