The main goal of athom-api is to provide easy access to Homeys and their functions. Athom-api can be used in most javascript enabled environments, like webbrowsers, node.js applications, but also inside Homey Apps and react-native applications.
Connecting to Homey (remotely)
Connecting to Homey is a two-step process. First of all we need our user to log-in using their Athom Account using AthomCloudAPI, then we can retrieve the Homeys we have access to (usually the user grants access to exactly 1 Homey). And finally, we can start an authenticated session on this Homey. An authenticated session on Homey is represented by HomeyAPI.
//Web-side
//When using the CDN script include, all top-level exports are globally
// available, so no includes are neccesarry.
//When using a package manager such as npm or yarn and mjs and a transpiler,
// we need to install athom-api and use the following import:
//import {AthomCloudAPI, AthomStorageAdapter} from 'athom-api';
//When using cjs and a transpiler we need to use the following import:
//const {AthomCloudAPI, AthomStorageAdapter} = require('athom-api');
//This sets a global config
// Alternatively these values can be supplied to the constructor
AthomCloudAPI.setConfig({
clientId: "_client_id_", //Obtained through the developer portal/Athom
clientSecret: "_client_secret_", //Obtained through the developer portal/Athom
redirectUrl: 'http://localhost:8080' //Configured through developer portal
});
//Create a new AthomCloudAPI instance
const cloudAPI = new AthomCloudAPI({
//CloudAPI can use a store to persist and cache session data.
// In this example we want to use HTML5 localStorage to do this.
// Alternatively you can extend AthomStorageAdapter and implement
// your own storage engine instead.
// If no store is specified, and HTML5 local storage is available,
// it is selected automatically.
store: new AthomStorageAdapter.LocalStorage('_athom_cloud_api')
});
//This function attempts to log-in to a specific homey and returns a HomeyAPI
async function login() {
//Check if we are logged in
if(!await cloudAPI.isLoggedIn()) {
//If we are not logged in but do have an OAuth2 authorization code
// parameter in our URL, use it to authenticate
if(cloudAPI.hasAuthorizationCode()) {
await cloudAPI.authenticateWithAuthorizationCode();
} else {
//Redirect the user to the OAuth2 login page
window.location.href = cloudAPI.getLoginUrl([
'account.homeys.readonly', //required to access homey
'homey.manager.flows.readonly' //required to read flows
]);
}
}
//Retrieve information about the currently logged in user
//In some cases you may want to prefer a locally cached
// version using getAuthenticatedUserCached.
// Using a cached user is useful in situations where
// internet connectivitity is not always available
const user = await cloudAPI.getAuthenticatedUser();
console.info('User', user.fullname, 'Authenticated');
//Get the first homey of this user
const homey = user.getFirstHomey();
//Start a session on this Homey
console.info('Logging in to:', homey.name);
const homeyAPI = await homey.authenticate();
console.info('homeyAPI created');
//Example: Make the Homey say something to prove we're authenticated
await homeyAPI.speechOutput.say({text: 'Hello: '+user.fullname});
return homeyAPI;
}
login();
Connecting to Homey in a Homey app
It is also possible to use the web API inside an Homey app. This gives you access to a HomeyAPI that has access to the Homey the app is currently running on. In order to use this functionality, please make sure to include the homey:manager:api
permission in your app.
const HomeyAPI = require('athom-api');
async function login() {
//Authenticate against the current Homey.
const homeyAPI = await HomeyAPI.forCurrentHomey();
//Example: Make the Homey say something to prove we're authenticated
await homeyAPI.speechOutput.say({text: 'Hello: '+user.fullname});
return homeyAPI;
}
login();