Python Carson Living is a library written in Python that exposes the carson.live devices as Python objects.
Please use this library at your own risk and make sure that you do not violate the Terms of Service of Carson.
Carson Living Python should work against Python 2.x >= 2.7 and Python 3.x >= 3.5.
# Installing from PyPi $ pip install carson_living # Installing latest development $ pip install \ git+https://github.com/rado0x54/python-carson-living@master
# Initializing an API object
carson = Carson("account@email.com", 'your password')
print(carson.user)
# >> Martin
print(carson.token)
# >> ey...
You are also able to pass a valid JWT token during initialization which would prevent a login action as long as the token is valid:
# Initializing an API object with a valid token
carson = Carson("account@email.com", 'your password', 'ey....')
print(carson.token)
# >> Martin
Since Carson Living uses JWT token with very long validity, it is recommended to save the active token via
carson.token
, whenever one needs to reinitialize the API later on. The API library is robust to handle expired
JWT tokens (and 401 handling), so no need to check before.
The library currently supports the following entities and actions.
- User (
carson.user
): read - Building (
carson.buildings
): read - Doors (
building.doors
): read, open - Cameras (
building.cameras
): read, images, video
Doors can be "buzzed" open via door.open()
# Open all Unit Doors of Main Building
for door in carson.first_building.doors:
if door.is_unit_door:
print('Opening Unit Door {}'.format(door.name))
door.open()
Eagle Eye cameras can produce live images and videos but also allow access to passed recordings (see API). The API can download the image and video directly into a provided file object
or just pass a generated url with an eagle_eye auth key A=c000....
. Please note, that the url can only be accessed as long as the auth_key
is valid. Therefore it may make sense to
force the eagle eye api to refresh the auth key before generating a image or video url.
- Directly save a live image:
for camera in building.cameras:
with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
camera.get_image(file)
- Directly save a live video of 10s:
for camera in building.cameras:
with open('video_{}.flv'.format(camera.entity_id), 'wb') as file:
camera.get_video(file, timedelta(seconds=10))
- Directly download a image from a timestamp:
three_hours_ago = datetime.utcnow() - timedelta(hours=3)
# download all images from 3 hours ago
for camera in building.cameras:
with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
camera.get_image(file, three_hours_ago)
- Directly download a recorded video from a timestamp:
three_days_ago = datetime.utcnow() - timedelta(days=3)
# download all videos from 3 days ago
for cam in building.cameras:
with open('video_{}.flv'.format(cam.entity_id), 'wb') as file:
cam.get_video(file, timedelta(seconds=5), three_days_ago)
- The Carson API is also able to produce authenticated URLs that can be handled externally.
Please not, that the
auth_key
has a limited lifetime. Therefore it makes sense to update theauth_key
manually before retrieving predefined URLs. Note, the Eagle Eye API in Carson is associated with a building, so it is sufficient to update it once for all cameras in the same building. The function signature of the the_url
function is identical to the previous ones (minus the file object).
# Update Session Auth Key of Eagle Eye once in a while if using
# generated authenticated URLs.
# Note, this is not needed for get_image() or get_video()
building.eagleeye_api.update_session_auth_key()
for cam in building.cameras:
img_url = cam.get_image_url(three_days_ago)
print(img_url)
# >> https://cXXX.eagleeyenetworks.com/asset/prev/image.jpeg?id=c0×tamp=20200122211442.575&asset_class=pre&A=c000~...
response = requests.get(img_url)
with open('image_{}_with_url.jpeg'.format(cam.entity_id), 'wb') as file:
file.write(response.content)
# do only 1 cam.
break
Use cam.get_video_url()
the same way.
Checkout ./scripts/carsoncli.py
for further API implementation examples.
The code follow the Google Python Styleguide for docstring.
This project uses gitflow as a git branching model.
The following is not supported by the API yet and remains TODO.
- Expose visitor functionality (
/visitors
) - Expose thread / messaging functionality (
/threads
) - Expose delivery functionality (
/deliveries
) - Expose dashboard functionality (
/dashboard
) - Expose service functionality (
/service
) - Integrate Twilio (
twilio/access-token/
) - Expand and extract EagleEye API (into separate project?).
- A lot of the project setup and the API object design was inspired / launched off https://github.com/tchellomello/python-ring-doorbell. Saved me a lot of headaches with tox, setuptools and Travis!.