Skip to content Skip to main navigation Skip to footer

Omlet Type Script SDK

This SDK is designed to facilitate seamless authentication with Omlet and provide interaction with devices. With our SDK, developers can easily retrieve device information, and execute actions tailored to their devices and groups.

Introduction

Getting Started

To use this SDK the user will already be registered with omlet as you will use the same email and password credentials to authenticate. We will go through the steps for including this SDK in your application and how to interact with your devices.

Installation

To install the SmartCoop SDK, ensure you have npm installed on your system. Then, create or navigate to your project directory and execute the following command:

npm install smartcoop-sdk

Create an API Key

To generate an API key you'll need to login to the developer console with the email and password that use for the App. Once logged in navigate to "API Keys" and click "Generate Key". Take note of this key.

Omlet

The Omlet object offers the ability to retrieve all of your devices, get a single device, create a group handler and create a user handler.

Creating an Instance

Use the apiKey you created to start omlet.

import { createOmlet } from 'smartcoop-sdk';

const omlet = createOmlet('CfYA8___key_from_above');

Retrieving Devices

const devices: DeviceHandler[] = await omlet.getDevices();

const device: DeviceHandler[] = await omlet.getDeviceById('1234567');

These functions will return a Device Handler that will allow you to interact with individual devices.

Create a Group

const group = omlet.createGroup('New Group Name');

Retrieving Groups

const groups: GroupHandler[] = await omlet.getGroups();

const group: GroupHandler[] = await omlet.getGroupById('123456');

Retrieving the User

const userHandler: UserHandler = await omlet.getUser();

Device Handler

The Device Handler offers a way to interact with a specific device and also see the Device data. The Device Handler will hold a data object with the latest state and configuration of the device. You can access each of the attributes through getter methods.

Device Actions

Device actions are used to interact with the device. A list of available actions is present on the device data. We can perform actions on the device by retrieving one from the list:

const device : DeviceHandler = omlet.getDeviceById('123456');
const actions = device.getActions();

The action object contains a description of the action. To perform an action, filter out the action you want to perform, such as opening the door and pass it to the action function

const openAction: Action|undefined = device.getActions().find((action: Action) => action.name === 'open');
if (openAction) {
await device.action(openAction)
}

Updating Device Configuration

To update the devices configuration, we will need to interact with the Configuration object.

const deviceData: Device = device.getData();
const configuration: Configuration = deviceData.configuration;
const newConfiguration = {
...configuration,
door: {
...configuration.door,
openTime: "07:30"
}
} as Configuration;

await device.updateConfiguration(newConfiguration);

Group Handler

The Group Handler offers a way to interact with a specific group and also see the group data. The Group Handler will hold a data object with group information, users, admins and devices belonging to the group

Update Group Name

We can update a single groups name.

await group.updateGroupName('New Name');

Delete Group

We can remove the group associated with the handler.

await group.deleteGroup();

Invite User

We can invite users to the current group by email and specify their access.

// invite a user with User access
await group.inviteUser("user@example.com", 'User');

// invite a user with Admin access
await group.inviteUser("user@example.com", 'Admin');

Remove User

We can remove users from the group by their email address.

await group.removeUser("user@example.com");

Update User Access

We can update the users access level by their email address.

await group.updateUserAccess("user@example.com", 'Admin');

User Handler

The User Handler offers a way to interact with features for the authenticated user. The User Handler will hold a data object with users information and invites.

Accept Invite

We can accept an invite by retrieving one from the data objects invites array"

import {GroupSubset} from "./group.subset";

const data: User = user.getData();

// invites is an array containing GroupSubset objects. Pass one of these
// to acceptInvite
const invites: GroupSubset[] = data.invites;

// pass one of these to acceptInvite
await user.acceptInvite(invite);

Reject Invite

We can reject an invite by retrieving one from the data objects invites array:

await user.rejectInvite(invite);

Types

We have the following data types that we use response and request from the Omlet API

Action

The Action object provides the following details

interface Action {
name: string;
description: string;
value: string;
pending?: string | null;
url: string;
}

Configuration

The Configuration object will give you an overview of the current configuration of the device after retrieval

interface Configuration {
general: ConfigurationGeneral;
connectivity: ConfigurationConnectivity;
door?: ConfigurationDoor | null;
light?: ConfigurationLight | null;
}

Configuration Connectivity

The Configuration Connectivity object provides the following details

interface ConfigurationConnectivity {
wifiState: string;
}

Configuration Door

The Configuration Door object provides the following details

interface ConfigurationDoor {
doorType: string;
openMode: string;
openDelay: number;
openLightLevel: number;
openTime: string;
closeMode: string;
closeDelay: number;
closeLightLevel: number;
closeTime: string;
colour: string;
}

Configuration General

The Configuration General object provides the following details

interface ConfigurationGeneral {
datetime: string;
timezone: string;
useDst?: boolean | null;
updateFrequency: number;
language: string;
overnightSleepEnable: boolean;
overnightSleepStart: string;
overnightSleepEnd: string;
pollFreq: number;
stayAliveTime: number;
statusUpdatePeriod: number;
}

Configuration Light

The Configuration Light object provides the following details

interface ConfigurationLight {
mode: string;
minutesBeforeClose: number;
maxOnTime: number;
equipped: number;
}

Device

The Device object represents an individual SmartCoop device.

interface Device {
deviceId: string;
name: string;
deviceType: string;
state: State;
configuration: Configuration;
actions: Action[];
}

Group

The Group object represents a group the user belongs to.

interface Group {
groupId: string;
groupName: string;
access?: string | null;
devices: Device[];
admins: User[];
users: User[];
}

Group Subset

interface GroupSubset {
groupId: string;
groupName: string;
access: string;
}

Group User

interface GroupUser {
emailAddress: string;
firstName: string;
lastName: string;
access: string;
}

State

The State object will give you an overview of the current state of the device after retrieval

interface State {
general: StateGeneral;
connectivity: StateConnectivity;
door?: StateDoor;
light?: StateLight;
}

State Connectivity

The State Connectivity object provides the following details

interface StateConnectivity {
ssid: string;
wifiStrength: string;
}

State Door

The State Door object provides the following details

interface StateDoor {
state: string;
lastOpenTime: string;
lastCloseTime: string;
fault: string;
lightLevel: number;
}

State General

The State General object provides the following details

interface StateGeneral {
firmwareVersionCurrent: string;
firmwareVersionPrevious: string;
firmwareLastCheck: string;
batteryLevel: number;
powerSource: string;
uptime: number;
displayLine1: string;
displayLine2: string;
}

State Light

The State Light object provides the following details

interface StateLight {
state: string;
}

User

The User object represents the authenticated user.

interface User {
userId?: string;
firstName: string;
lastName: string;
emailAddress?: string | null;
siteLink?: string | null;
invites?: GroupSubset[] | null;
}