Yale Sync & Smart Home Alarm API

API wrapper for the undocumented API used by the Yale Sync Smart Home Alarm and Yale Smart Home Alarm.

The state of the alarm system (the panel) is exposed, along with contact and motion sensors.

Installation

npm install --save yalesyncalarm

Usage

Typescript

The NPM module ships pre-compiled js files, and d.ts files so it still can be used from typescript directly.

// File.ts

import { Yale } from 'yalesyncalarm'

const yale = new Yale(username, password)
await yale.update() // fetches panel and sensor state

const panel = await yale.panel()
const panelState = await yale.getPanelState()
const updatedPanelState = await yale.setPanelState(Panel.State.Armed)

const motionSensors = await yale.motionSensors()
const contactSensors = await yale.contactSensors()

const updatedMotionSensor = await yale.updateMotionSensor(motionSensor)
const updatedContactSensor = await yale.updateMotionSensor(contactSensor)

Yale.AccessToken contains both the token itself and an expiry date, after which the token is no longer valid. Clients are expected to verify the token is valid before calling other methods, or handle errors thrown by API calls that use the access token.

Yale.Panel.Mode is an enum consisting of .arm, .disarm and .home cases. The Yale alarms do not discrimiate between home and night modes as some other alarm systems do.

Yale.Devices.Sensor is a discriminated union for Door Contact Sensors and Passive IR Sensors. The states of these are conveniently expressed as enums. Each sensor has an identifier which can be used to track the state of a sensor across multiple calls to Yale.Devices.getSensors().

Javascript

The installed NPM module ships pre-compiled js files. Therefore you are not required to build the js from the original typescript source in order to use the package.

// File.js

var Yale = require('yalesyncalarm')

var yale = new Yale.Yale(username, password)
await yale.update() // fetches panel and sensor state

var panel = await yale.panel()
var panelState = await yale.getPanelState()
var updatedPanelState = await yale.setPanelState('arm)

var motionSensors = await yale.motionSensors()
var contactSensors = await yale.contactSensors()

var updatedMotionSensor = await yale.updateMotionSensor(motionSensor)
var updatedContactSensor = await yale.updateMotionSensor(contactSensor)

Limitations

The undocumented Yale API can change on a whim, so this may break at any time. If it does, please submit a pull request if you can work out what right changes should be to make it work again.

My best guess is that the Yale Home app itself uses a non-HTTP-based protocol like XMPP/MQTT to both send and recieve state changes. The HTTP API used in this project works for pulling state for Yale Sync and Yale Smart Home APIs, but there's no way (yet) to subscribe to state changes.

Building from Source

git clone https://github.com/jonathandann/yalesyncalarm.git && cd yalesyncalarm && npm install

After running npm install, npm should automatically run npm run build, which runs node_modules/typescript/bin/tsc to compile the typescript files. If it doesn't then you can run either node_modules/typescript/bin/tsc or npm run build.

There are useful configs already included for prettier and Visual Studio Code.

Visual Studio Code is configured to use the version of typescript installed as a development dependency in the npm package.