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¶
- 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.