Ring API
An unofficial, friendly Javascript API for ring doorbells, cameras, etc.
- Happy in node or browsers
- Promised-based
- Glosses over ring's API weirdness
- Hides http polling behind an event-driven interface
Requires a JS runtime that supports ES6 async/await or else traspilation
usage
const RingApi = ; // note that RingApi returns a promise - the promise resolves when you are authenticated/// authorised and have a session ready to start interacting with your ring deviecs. This// promise will reject if for some reason you are not able to log inconst ringApi = await ;
Listening for activity on your ring devices
const logActivity = console; ringApievents;
The event will be fired on rings and motion detected. To distinguish between then, use the activity.kind property.
Where the activity object looks like:
kind: 'motion' // 'motion' or 'ring', // note - id will be a string - Javascript Number can't do large integers id: '6500907085284961754' id_str: '6500907085284961754' // same as id state: 'ringing' protocol: 'sip' doorbot_id: 3861978 // id of the device that is ringing doorbot_description: 'Back garden' device_kind: 'hp_cam_v1' motion: true snapshot_url: '' // seems to always be blank expires_in: 175 now: Date // js Date object optimization_level: 1 // various sip-related fields for the video: sip_server_ip: '...' sip_server_port: 15063 sip_server_tls: true sip_session_id: '...' sip_from: '...' sip_to: '..' audio_jitter_buffer_ms: 300 video_jitter_buffer_ms: 300 sip_endpoints: null sip_token: 'long hex token' sip_ding_id: '6500907085284961754' // seems to always be the same as the id
Getting a list of devices
// returns a promiseringApi;
Where the promise will resolve to an object like:
all: /* all your devices in one array */ doorbells: /* array of doorbells */ authorizedDoorbells: // other people's doorbells you are authorised for chimes: /* array of chimes */ cameras: /* array of cameras, floodlight cams, spotlight cams etc */ baseStations: // presumably if you have a chime pro with the wifi hotspot built in
Turning lights on and off
const prompt = prompt; { const devices = await ringApi; console; // note that .lightOn() returns a promise // with the magic of promises we can turn them all on asynchronously await Promiseall devicescameras ; await ; await Promiseall devicescameras ; console;}; ;
Getting device history and videos
{ const history = await ringApihistory; const firstVideoUrl = await history0; console; const allRecentVideos = Promiseall history ; console; };
starting a livestream
So far this only works so far as getting the SIP details of the stream. To get this, can do:
// returns a promise that will resolve to the livestream SIP information:devicesdoorbells0;
getting device health
{ const strength = await devicelatest_signal_strength; console;} // asynchronously print the health of the first of each kind of device,// without worrying about the order they are printed in:const devices = await ringApi;;;;
debugging
To get extended debugging info, since ring-api uses https://www.npmjs.com/package/debug you
can set the DEBUG
environment variable to ring-api
(or add ring-api to it if it is already set)
For example, to run the example script from bash with debugging you might do:
env DEBUG="$DEBUG ring-api" ./examples/example-script
Thanks to
- The doorbot source for getting me started
- This python API
- mitm proxy