Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: ring alarm api #14

Closed
wants to merge 12 commits into from
7 changes: 7 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[*]
end_of_line = lf
charset = utf-8
indent_style = space
indent_size = 4
trim_trailing_whitespace = true
insert_final_newline = true
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ node_modules/
.idea
.vscode/
*.code-workspace
.DS_Store
31 changes: 31 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,37 @@ printHealth( devices.chimes[0] );
printHealth( devices.cameras[0] );
```

Ring Alarm
----------
### Fetching Alarms
```js
const alarms = await ringApi.alarms();
```
`alarms` will be an array of alarms based on the locations you have set
up in Ring. Each location has it's own alarm that can be armed or disarmed,
and used to interact with alarm devices in that location.
### Arming/Disarming Alarms
```js
const alarm = alarms[0]
alarm.disarm()
alarm.armHome([/* optional array of zids for devices to bypass */])
alarm.armAway([/* bypass zids */])
const rooms = await alarm.getRooms() // array of rooms { id: number, name: string }
```
### Devices
Once you have acquired the alarm for you desired location, you can start
to interact with associated devices.
```js
const devices = await alarm.getDevices()
const baseStation = devices.find(device => device.data.deviceType === 'hub.redsky')
baseStation.setVolume(.75) // base station and keyboard support volume settings between 0 and 1
console.log(baseStation.data) // object containing properties like zid, name, roomId, faulted, tamperStatus, etc.
baseStation.onData.subscribe(data => {
// this will be called any time data is updated for this specific device
})
```


debugging
---------

Expand Down
4 changes: 4 additions & 0 deletions api-urls.js
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,10 @@ function apiUrls( options ) {
},

})
},

connections() {
return 'https://app.ring.com/api/v1/rs/connections'
}

})
Expand Down
6 changes: 3 additions & 3 deletions examples/example-script.js
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ const colors = require( 'colors/safe' )
const prompt = require( 'node-ask' ).prompt

// edit here, or use the RING_USER and RING_PASSWORD environment variables:
const username = undefined
const email = undefined
const password = undefined

const main = async() => {
Expand All @@ -19,8 +19,8 @@ const main = async() => {
try {
ring = await ringApi({
// we'll use the default options for this example. Maks sure you have the
// username and password as RING_USER or RING_PASSWORD or place them above
username, password
// email and password as RING_USER or RING_PASSWORD or place them above
email, password
})
} catch ( e ) {
console.error( e )
Expand Down
292 changes: 292 additions & 0 deletions get-alarms.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,292 @@
'use strict'

const io = require( 'socket.io-client' )
const { Subject, BehaviorSubject } = require( 'rxjs' )
const { filter, take, map, concatMap, distinctUntilChanged, publishReplay, scan } = require( 'rxjs/operators' )
const unique = require( 'lodash.uniq' )
const delay = require( 'timeout-as-promise' )

module.exports = bottle => bottle.service( 'getAlarms', getAlarms,
'restClient',
'apiUrls',
'getDevicesList',
'logger'
)

const DeviceType = {
BaseStation: 'hub.redsky',
Keypad: 'security-keypad',
SecurityPanel: 'security-panel',
ContactSensor: 'sensor.contact',
MotionSensor: 'sensor.motion',
RangeExtender: 'range-extender.zwave',
ZigbeeAdapter: 'adapter.zigbee',
AccessCodeVault: 'access-code.vault',
AccessCode: 'access-code',
SmokeAlarm: 'alarm.smoke',
CoAlarm: 'alarm.co',
SmokeCoListener: 'listener.smoke-co',
},
deviceListMessageType = 'DeviceInfoDocGetList'

module.exports.AlarmDeviceType = DeviceType

const deviceTypesWithVolume = [ DeviceType.BaseStation, DeviceType.Keypad ]

function flattenDeviceData( data ) {
return Object.assign(
{},
data.general && data.general.v2,
data.device && data.device.v1
)
}

function getAlarms( restClient, apiUrls, getDeviceList, logger ) {

class Device {
constructor( initialData, alarm ) {
this.zid = initialData.zid
this.onData = new BehaviorSubject( initialData )
this.alarm = alarm

alarm.onDeviceDataUpdate
.pipe(
filter( update => {
return update.zid === this.zid
})
)
.subscribe( update => this.updateData( update ))
}

updateData( update ) {
this.onData.next( Object.assign({}, this.data, update ))
}

get data() {
return this.onData.getValue()
}

get supportsVolume() {
return deviceTypesWithVolume.includes( this.data.deviceType )
&& this.data.volume !== undefined
}


setVolume( volume ) {
if ( isNaN( volume ) || volume < 0 || volume > 1 ) {
throw new Error( 'Volume must be between 0 and 1' )
}

if ( !this.supportsVolume ) {
throw new Error( `Volume can only be set on ${deviceTypesWithVolume.join( ', ' )}` )
}

this.alarm.setDeviceInfo( this.zid, { device: { v1: { volume } } })
}

toString() {
return this.toJSON()
}

toJSON() {
return JSON.stringify({
data: this.data
}, null, 2 )
}
}

class Alarm {
constructor( locationId ) {
this.locationId = locationId
this.seq = 1
this.onMessage = new Subject()
this.onDataUpdate = new Subject()
this.onDeviceDataUpdate = this.onDataUpdate
.pipe(
filter( message => {
return message.datatype === 'DeviceInfoDocType' && Boolean( message.body )
}),
concatMap( message => message.body ),
map( flattenDeviceData )
)
this.onDeviceList = this.onMessage
.pipe(
filter( m => m.msg === deviceListMessageType ),
map( m => m.body )
)
this.onDevices = this.onDeviceList
.pipe(
scan(( devices, deviceList ) => {
return deviceList.reduce(( updatedDevices, data ) => {
const flatData = flattenDeviceData( data ),
existingDevice = updatedDevices.find( x => x.zid === flatData.zid )

if ( existingDevice ) {
existingDevice.updateData( flatData )
return updatedDevices
}

return [ ...updatedDevices, new Device( flatData, this ) ]
}, devices )
}, []),
distinctUntilChanged(( a, b ) => a.length === b.length ),
publishReplay( 1 )
)

// start listening for devices immediately
this.onDevices.connect()
}

async createConnection() {
logger( 'Creating alarm socket.io connection' )
const connectionDetails = await restClient.oauthRequest( 'POST', apiUrls.connections(), {
accountId: this.locationId
})

const connection = io.connect( `wss://${connectionDetails.server}/?authcode=${connectionDetails.authCode}` )
const reconnect = () => {
if ( this.reconnecting && this.connectionPromise ) {
return this.connectionPromise
}

logger( 'Reconnecting alarm socket.io connection' )
this.reconnecting = true
connection.close()
return this.connectionPromise = delay( 1000 ).then(() => this.createConnection())
}

this.reconnecting = false
connection.on( 'DataUpdate', message => {
if ( message.datatype === 'HubDisconnectionEventType' ) {
logger( 'Alarm connection told to reconnect' )
return reconnect()
}

this.onDataUpdate.next( message )
})
connection.on( 'message', message => this.onMessage.next( message ))
connection.on( 'error', reconnect )
return new Promise(( resolve, reject ) => {
connection.once( 'connect', () => {
resolve( connection )
logger( 'Ring alarm connected to socket.io server' )
this.requestList( deviceListMessageType )
})
connection.once( 'error', reject )
}).catch( reconnect )
}

async getConnection() {
if ( this.connectionPromise ) {
return this.connectionPromise
}

return this.connectionPromise = this.createConnection()
}

async sendMessage( message ) {
const connection = await this.getConnection()
message.seq = this.seq++
connection.emit( 'message', message )
}

setDeviceInfo( zid, body ) {
return this.sendMessage({
msg: 'DeviceInfoSet',
datatype: 'DeviceInfoSetType',
body: [
{
zid,
...body
}
]
})
}

async setAlarmMode( alarmMode, bypassSensorZids ) {
const zid = await this.getSecurityPanelZid()
return this.setDeviceInfo( zid, {
command: {
v1: [
{
commandType: 'security-panel.switch-mode',
data: {
mode: alarmMode,
bypass: bypassSensorZids
}
}
]
}
})
}

getNextMessageOfType( type ) {
return this.onMessage.pipe(
filter( m => m.msg === type ),
map( m => m.body ),
take( 1 )
).toPromise()
}

requestList( listType ) {
this.sendMessage({ msg: listType })
}

getList( listType ) {
this.requestList( listType )
return this.getNextMessageOfType( listType )
}

getDevices() {
if ( !this.connectionPromise ) {
this.getConnection()
}

return this.onDevices.pipe(
take( 1 )
).toPromise()
}

getRoomList() {
return this.getList( 'RoomGetList' )
}

async getSecurityPanelZid() {
if ( this.securityPanelZid ) {
return this.securityPanelZid
}

const devices = await this.getDevices()
const securityPanel = devices.find( device => {
return device.data.deviceType === DeviceType.SecurityPanel
})

if ( !securityPanel ) {
throw new Error( `Could not find a security panel for location ${this.locationId}` )
}

return this.securityPanelZid = securityPanel.zid
}

disarm() {
return this.setAlarmMode( 'none' )
}

armHome( bypassSensorZids ) {
return this.setAlarmMode( 'some', bypassSensorZids )
}

armAway( bypassSensorZids ) {
return this.setAlarmMode( 'all', bypassSensorZids )
}
}

return async() => {
const devices = await getDeviceList()
const baseStations = devices.baseStations
const locationIds = baseStations.map( baseStation => baseStation.location_id )

return unique( locationIds ).map( locationId => new Alarm( locationId ))
}
}

Loading