Python Ring Door Bell

Python Ring Door Bell is a library written for Python that exposes the Ring.com devices as Python objects.

There is also a command line interface that is work in progress. Contributors welcome.

Currently Ring.com does not provide an official API. The results of this project are merely from reverse engineering.

Documentation: http://python-ring-doorbell.readthedocs.io/

Installation

# Installing from PyPi
$ pip install ring_doorbell
# Installing latest development
$ pip install \
git+https://github.com/python-ring-doorbell/python-ring-doorbell@master

Using the CLI

The CLI is work in progress and currently has the following commands:

1. Show your devices:

   $ ring-doorbell
   

   Or:

   $ ring-doorbell show
   

2. List your device names (with device kind):

   $ ring-doorbell list
   

3. Either count or download your vidoes or both:

   $ ring-doorbell videos --count --download-all
   

4. Enable disable motion detection:

   $ ring-doorbell motion-detection --device-name "DEVICENAME" --on
   $ ring-doorbell motion-detection --device-name "DEVICENAME" --off
   

5. Listen for push notifications like the ones sent to your phone:

   $ ring-doorbell listen
   

6. List your ring groups:

   $ ring-doorbell groups
   

7. Show your ding history:

   $ ring-doorbell history --device-name "Front Door"
   

8. Show your currently active dings:

   $ ring-doorbell dings
   

9. See or manage your doorbell in-home chime settings:

   $ ring-doorbell in-home-chime --device-name "Front Door"
   $ ring-doorbell in-home-chime --device-name "Front Door" type Mechanical
   $ ring-doorbell in-home-chime --device-name "Front Door" enabled True
   $ ring-doorbell in-home-chime --device-name "Front Door" duration 5
   

10. Query a ring api url directly:

    $ ring-doorbell raw-query --url /clients_api/dings/active
    

11. Run ring-doorbell --help or ring-doorbell <command> --help for full options

Using the API

The API has an async interface and a sync interface. All api calls starting async are asynchronous. This is the preferred method of interacting with the ring api and the sync versions are maintained for backwards compatability.

You cannot call sync api functions from inside a running event loop.

Initializing your Ring object

This code example is in the test.py file. For the deprecated sync example see test_sync.py.

importgetpassimportasyncioimportjsonfrompathlibimportPathfromring_doorbellimportAuth, AuthenticationError, Requires2FAError, Ringuser_agent="YourProjectName-1.0"# Change thiscache_file=Path(user_agent+".token.cache")
deftoken_updated(token):
cache_file.write_text(json.dumps(token))
defotp_callback():
auth_code=input("2FA code: ")
returnauth_codeasyncdefdo_auth():
username=input("Username: ")
password=getpass.getpass("Password: ")
auth=Auth(user_agent, None, token_updated)
try:
awaitauth.async_fetch_token(username, password)
exceptRequires2FAError:
awaitauth.async_fetch_token(username, password, otp_callback())
returnauthasyncdefmain():
ifcache_file.is_file(): # auth token is cachedauth=Auth(user_agent, json.loads(cache_file.read_text()), token_updated)
ring=Ring(auth)
try:
awaitring.async_create_session() # auth token still validexceptAuthenticationError: # auth token has expiredauth=awaitdo_auth()
else:
auth=awaitdo_auth() # Get new auth tokenring=Ring(auth)
awaitring.async_update_data()
devices=ring.devices()
pprint(devices.devices_combined)
awaitauth.async_close()
if__name__=="__main__":
asyncio.run(main())

Event Listener

event_listener=RingEventListener(ring, credentials, credentials_updated_callback)
event_listener.add_notification_callback(_event_handler(ring).on_event)
awaitevent_listener.start()

Listing devices linked to your account

# All devicesdevices=ring.devices()
{'chimes': [<RingChime: Downstairs>],
'doorbots': [<RingDoorBell: FrontDoor>]}
# All doorbellsdoorbells=devices['doorbots']
[<RingDoorBell: FrontDoor>]
# All chimeschimes=devices['chimes']
[<RingChime: Downstairs>]
# All stickup camsstickup_cams=devices['stickup_cams']
[<RingStickUpCam: Driveway>]

Playing with the attributes and functions

devices=ring.devices()
fordevinlist(devices['stickup_cams'] +devices['chimes'] +devices['doorbots']):
awaitdev.async_update_health_data()
print('Address: %s'%dev.address)
print('Family: %s'%dev.family)
print('ID: %s'%dev.id)
print('Name: %s'%dev.name)
print('Timezone: %s'%dev.timezone)
print('Wifi Name: %s'%dev.wifi_name)
print('Wifi RSSI: %s'%dev.wifi_signal_strength)
# setting dev volumeprint('Volume: %s'%dev.volume)
awaitdev.async_set_volume(5)
print('Volume: %s'%dev.volume)
# play dev test shoundifdev.family=='chimes':
awaitdev.async_test_sound(kind='ding')
awaitdev.async_test_sound(kind='motion')
# turn on lights on floodlight camifdev.family=='stickup_cams'anddev.lights:
awaitdev.async_lights('on')

Showing door bell events

devices=ring.devices()
fordoorbellindevices['doorbots']:
# listing the last 15 events of any kindforeventinawaitdoorbell.async_history(limit=15):
print('ID: %s'%event['id'])
print('Kind: %s'%event['kind'])
print('Answered: %s'%event['answered'])
print('When: %s'%event['created_at'])
print('--'*50)
# get a event list only the triggered by motionevents=awaitdoorbell.async_history(kind='motion')

Downloading the last video triggered by a ding or motion event

devices=ring.devices()
doorbell=devices['doorbots'][0]
awaitdoorbell.async_recording_download(
awaitdoorbell.async_history(limit=100, kind='ding')[0]['id'],
filename='last_ding.mp4',
override=True)

Displaying the last video capture URL

print(awaitdoorbell.async_recording_url(awaitdoorbell.async_last_recording_id()))
'https://ring-transcoded-videos.s3.amazonaws.com/99999999.mp4?X-Amz-Expires=3600&X-Amz-Date=20170313T232537Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=TOKEN_SECRET/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=secret'

Controlling a Light Group

groups=ring.groups()
group=groups['the-group-you-want']
print(group.lights)
# Prints True if lights are on, False if off# Turn on lights indefinitelyawaitgroup.async_set_lights(True)
# Turn off lightsawaitgroup.async_set_lights(False)
# Turn on lights for 30 secondsawaitgroup.async_set_lights(True, 30)

How to contribute

See our Contributing Page.

Credits && Thanks

• This project was inspired and based on https://github.com/jeroenmoors/php-ring-api. Many thanks @jeroenmoors.
• A guy named MadBagger at Prism19 for his initial research (http://www.prism19.com/doorbot/second-pass-and-comm-reversing/)
• The creators of mitmproxy (https://mitmproxy.org/) great http and https traffic inspector
• @mfussenegger for his post on mitmproxy and virtualbox https://zignar.net/2015/12/31/sniffing-vbox-traffic-mitmproxy/
• To the project http://www.android-x86.org/ which allowed me to install Android on KVM.
• Many thanks to Carles Pina I Estany <carles@pina.cat> for creating the python-ring-doorbell Debian Package (https://tracker.debian.org/pkg/python-ring-doorbell).