Python Ring Door Bell’s documentation

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

Note

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

Installation

# Installing from PyPi
$ pip install ring_doorbell

# Installing latest development
$ pip install \
    git+https://github.com/tchellomello/python-ring-doorbell@dev

Initializing your Ring object

from pprint import pprint
from ring_doorbell import Ring, Auth

auth = Auth("YourProject/0.1", None, token_updated)
auth.fetch_token(username, password)
ring = Ring(auth)
ring.update_data()
devices = ring.devices()

pprint(ring.session['profile'])

Listing devices linked to your account

# All devices
devices = ring.devices()
{'chimes': [<RingChime: Downstairs>],
'doorbots': [<RingDoorBell: Front Door>]}

# All doorbells
doorbells = devices['doorbots']
[<RingDoorBell: Front Door>]

# All chimes
chimes = devices['chimes']
[<RingChime: Downstairs>]

# All stickup cams
stickup_cams = devices['stickup_cams']
[<RingStickUpCam: Driveway>]

Playing with the attributes

devices = ring.devices()
for dev in list(devices['stickup_cams'] + devices['chimes'] + devices['doorbots']):
    dev.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 volume
    print('Volume:     %s' % dev.volume)
    dev.volume = 5
    print('Volume:     %s' % dev.volume)

    # play dev test shound
    if dev.family == 'chimes':
        dev.test_sound(kind = 'ding')
        dev.test_sound(kind = 'motion')

    # turn on lights on floodlight cam
    if dev.family == 'stickup_cams' and dev.lights:
        dev.lights = 'on'

Showing door bell events

devices = ring.devices()
for doorbell in devices['doorbots']:

    # listing the last 15 events of any kind
    for event in doorbell.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 motion
    events = doorbell.history(kind='motion')

Downloading the last video triggered by ding

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

Displaying the last video capture URL

print(doorbell.recording_url(doorbell.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'

Developing

class ring_doorbell.Ring(auth)

Bases: object

A Python Abstraction object to Ring Door Bell.

active_alerts()

Get active alerts.

create_session()

Create a new Ring session.

devices()

Get all devices.

groups()

Get all groups.

query(url, method='GET', extra_params=None, data=None, json=None, timeout=None)

Query data from Ring API.

update_data()

Update all data.

update_devices()

Update device data.

update_dings()

Update dings data.

update_groups()

Update groups data.

class ring_doorbell.generic.RingGeneric(ring, id)

Bases: object

Generic Implementation for Ring Chime/Doorbell.

address

Return address.

device_id

Return device ID.

family

Return Ring device family type.

firmware

Return firmware.

has_capability(capability)

Return if device has specific capability.

kind

Return kind attr.

latitude

Return latitude attr.

longitude

Return longitude attr.

model

Return Ring device model name.

name

Return name.

timezone

Return timezone.

update()

Update this device info.

update_health_data()

Update the health data.

wifi_name

Return wifi ESSID name.

Requires health data to be updated.

wifi_signal_category

Return wifi signal category.

Requires health data to be updated.

wifi_signal_strength

Return wifi RSSI.

Requires health data to be updated.

class ring_doorbell.chime.RingChime(ring, id)

Bases: ring_doorbell.generic.RingGeneric

Implementation for Ring Chime.

family

Return Ring device family type.

has_capability(capability)

Return if device has specific capability.

linked_tree

Return doorbell data linked to chime.

model

Return Ring device model name.

test_sound(kind='ding')

Play chime to test sound.

update_health_data()

Update health attrs.

volume

Return if chime volume.

class ring_doorbell.doorbot.RingDoorBell(ring, device_id, shared=False)

Bases: ring_doorbell.generic.RingGeneric

Implementation for Ring Doorbell.

address

Return address.

battery_life

Return battery life.

connection_status

Return connection status.

device_id

Return device ID.

existing_doorbell_type

Return existing doorbell type.

0: Mechanical 1: Digital 2: Not Present

existing_doorbell_type_duration

Return duration for Digital chime.

existing_doorbell_type_enabled

Return if existing doorbell type is enabled.

family

Return Ring device family type.

firmware

Return firmware.

get_snapshot(retries=3, delay=1, filename=None)

Take a snapshot and download it

has_capability(capability)

Return if device has specific capability.

has_subscription

Return boolean if the account has subscription.

history(limit=30, timezone=None, kind=None, enforce_limit=False, older_than=None, retry=8)

Return history with datetime objects.

Parameters:
  • limit – specify number of objects to be returned
  • timezone – determine which timezone to convert data objects
  • kind – filter by kind (ding, motion, on_demand)
  • enforce_limit – when True, this will enforce the limit and kind
  • older_than – return older objects than the passed event_id
  • retry – determine the max number of attempts to archive the limit
kind

Return kind attr.

last_recording_id

Return the last recording ID.

latitude

Return latitude attr.

live_streaming_json

Return JSON for live streaming.

longitude

Return longitude attr.

model

Return Ring device model name.

name

Return name.

recording_download(recording_id, filename=None, override=False, timeout=120)

Save a recording in MP4 format to a file or return raw.

recording_url(recording_id)

Return HTTPS recording URL.

subscribed

Return if is online.

subscribed_motion

Return if is subscribed_motion.

timezone

Return timezone.

update()

Update this device info.

update_health_data()

Update health attrs.

volume

Return volume.

wifi_name

Return wifi ESSID name.

Requires health data to be updated.

wifi_signal_category

Return wifi signal category.

Requires health data to be updated.

wifi_signal_strength

Return wifi RSSI.

Requires health data to be updated.

class ring_doorbell.stickup_cam.RingStickUpCam(ring, device_id, shared=False)

Bases: ring_doorbell.doorbot.RingDoorBell

Implementation for RingStickUpCam.

address

Return address.

battery_life

Return battery life.

connection_status

Return connection status.

device_id

Return device ID.

existing_doorbell_type

Return existing doorbell type.

0: Mechanical 1: Digital 2: Not Present

existing_doorbell_type_duration

Return duration for Digital chime.

existing_doorbell_type_enabled

Return if existing doorbell type is enabled.

family

Return Ring device family type.

firmware

Return firmware.

get_snapshot(retries=3, delay=1, filename=None)

Take a snapshot and download it

has_capability(capability)

Return if device has specific capability.

has_subscription

Return boolean if the account has subscription.

history(limit=30, timezone=None, kind=None, enforce_limit=False, older_than=None, retry=8)

Return history with datetime objects.

Parameters:
  • limit – specify number of objects to be returned
  • timezone – determine which timezone to convert data objects
  • kind – filter by kind (ding, motion, on_demand)
  • enforce_limit – when True, this will enforce the limit and kind
  • older_than – return older objects than the passed event_id
  • retry – determine the max number of attempts to archive the limit
kind

Return kind attr.

last_recording_id

Return the last recording ID.

latitude

Return latitude attr.

lights

Return lights status.

live_streaming_json

Return JSON for live streaming.

longitude

Return longitude attr.

model

Return Ring device model name.

name

Return name.

recording_download(recording_id, filename=None, override=False, timeout=120)

Save a recording in MP4 format to a file or return raw.

recording_url(recording_id)

Return HTTPS recording URL.

siren

Return siren status.

subscribed

Return if is online.

subscribed_motion

Return if is subscribed_motion.

timezone

Return timezone.

update()

Update this device info.

update_health_data()

Update health attrs.

volume

Return volume.

wifi_name

Return wifi ESSID name.

Requires health data to be updated.

wifi_signal_category

Return wifi signal category.

Requires health data to be updated.

wifi_signal_strength

Return wifi RSSI.

Requires health data to be updated.

class ring_doorbell.Auth(user_agent, token=None, token_updater=None, hardware_id=None)

A Python Auth class for Ring

fetch_token(username, password, otp_code=None)

Initial token fetch with username/password & 2FA :type username: str :type password: str :type otp_code: str

get_hardware_id()

Get hardware ID.

query(url, method='GET', extra_params=None, data=None, json=None, timeout=None)

Query data from Ring API.

refresh_tokens()

Refreshes the auth tokens

Credits && Thanks

Indices and tables