Minor changes related to camera usage

Author: philippelt

README.md

@@ -13,7 +13,11 @@ To install lnetatmo simply run:
 
     python setup.py install
 
+  or
+
+    pip install lnetatmo
+
 Depending on your permissions you might be required to use sudo.
-Once installed you can simple add latmo to your python scripts by including:
+Once installed you can simple add lnetatmo to your python scripts by including:
 
     import lnetatmo

lnetatmo.py

@@ -105,7 +105,7 @@ def __init__(self, clientId=_CLIENT_ID,
                        clientSecret=_CLIENT_SECRET,
                        username=_USERNAME,
                        password=_PASSWORD,
-                       scope="read_station"):
+                       scope="read_station read_camera access_camera read_presence access_presence"):
 
         postParams = {
                 "grant_type" : "password",
@@ -308,9 +308,9 @@ class DeviceList(WeatherStationData):
             DeprecationWarning )
     pass
 
-class WelcomeData:
+class HomeData:
     """
-    List the Netatmo Welcome cameras informations (Homes, cameras, events, persons)
+    List the Netatmo home informations (Homes, cameras, events, persons)
 
     Args:
         authData (ClientAuth): Authentication information with a working access Token
@@ -323,7 +323,7 @@ def __init__(self, authData):
         resp = postRequest(_GETHOMEDATA_REQ, postParams)
         self.rawData = resp['body']
         self.homes = { d['id'] : d for d in self.rawData['homes'] }
-        if not self.homes : raise NoDevice("No camera available")
+        if not self.homes : raise NoDevice("No home available")
         self.persons = dict()
         self.events = dict()
         self.cameras = dict()
@@ -343,7 +343,7 @@ def __init__(self, authData):
         for camera in self.events:
             self.lastEvent[camera]=self.events[camera][sorted(self.events[camera])[-1]]
         self.default_home = list(self.homes.values())[0]['name']
-        if not self.cameras[self.default_home] : raise NoDevice("No camera available")
+        if not self.cameras[self.default_home] : raise NoDevice("No camera available in default home")
         self.default_camera = list(self.cameras[self.default_home].values())[0]
 
     def homeById(self, hid):
@@ -392,12 +392,11 @@ def cameraUrls(self, camera=None, home=None, cid=None):
             camera_data=self.cameraByName(camera=camera, home=home)
         if camera_data:
             vpn_url = camera_data['vpn_url']
-            if camera_data['is_local']:
-                resp = postRequest('{0}/command/ping'.format(camera_data['vpn_url']),dict())
-                temp_local_url=resp['local_url']
-                resp = postRequest('{0}/command/ping'.format(temp_local_url),dict())
-                if temp_local_url == resp['local_url']:
-                    local_url = temp_local_url
+            resp = postRequest('{0}/command/ping'.format(camera_data['vpn_url']),dict())
+            temp_local_url=resp['local_url']
+            resp = postRequest('{0}/command/ping'.format(temp_local_url),dict())
+            if temp_local_url == resp['local_url']:
+                local_url = temp_local_url
         return vpn_url, local_url
 
     def personsAtHome(self, home=None):
@@ -531,6 +530,15 @@ def motionDetected(self, home=None, camera=None):
             return True
         return False
 
+class WelcomeData(HomeData):
+    """
+    This class is now deprecated. Use HomeData instead
+    Home can handle many devices, not only Welcome cameras
+    """
+    warnings.warn("The 'WelcomeData' class was renamed 'HomeData' to handle new Netatmo Home capabilities",
+            DeprecationWarning )
+    pass
+
 # Utilities routines
 
 def postRequest(url, params, json_resp=True, body_size=65535):
@@ -595,22 +603,22 @@ def getStationMinMaxTH(station=None, module=None):
            stderr.write("Library source missing identification arguments to check lnetatmo.py (user/password/etc...)")
            exit(1)
 
-    authorization = ClientAuth(scope="read_station read_camera access_camera")  # Test authentication method
+    authorization = ClientAuth()  # Test authentication method
 
     try:
-        devList = DeviceList(authorization)         # Test DEVICELIST
+        weatherStation = WeatherStationData(authorization)         # Test DEVICELIST
     except NoDevice:
         if stdout.isatty():
             print("lnetatmo.py : warning, no weather station available for testing")
     else:
-        devList.MinMaxTH()                          # Test GETMEASUR
+        weatherStation.MinMaxTH()                          # Test GETMEASUR
 
 
     try:
-        Camera = WelcomeData(authorization)
+        Homes = HomeData(authorization)
     except NoDevice :
         if stdout.isatty():
-            print("lnetatmo.py : warning, no Welcome camera available for testing")
+            print("lnetatmo.py : warning, no home available for testing")
 
     # If we reach this line, all is OK
 

samples/get_direct_camera_snapshot.py

@@ -0,0 +1,46 @@
+# Locate the camera name "MyCam" IP on the local LAN
+# to collect a snapshot of what the camera sees without
+# bandwith constraints of the Internet connexion
+
+
+# You will need the "requests" library :  pip install requests
+
+from sys import exit
+import lnetatmo
+import requests
+
+
+# The name I gave the camera in the Netatmo Security App
+MY_CAMERA = "MyCam"
+# From the netatmo camera API documentation
+SNAPSHOT_REQUEST = "/live/snapshot_720.jpg"
+
+
+# Authenticate (see authentication in documentation)
+# Note you will need the appropriate scope (read_welcome access_welcome or read_presence access_presence)
+# depending of the camera you are trying to reach
+# The default library scope ask for all aceess to all cameras
+authorization = lnetatmo.ClientAuth()
+
+# Gather Home information (available cameras and other infos)
+homeData = lnetatmo.HomeData(authorization)
+
+# Ask for Url giving local access to the camera I am looking for
+# Or remote VPN access through Netatmo server if the camera can't be reach locally
+vpnUrl, localUrl = homeData.cameraUrls(MY_CAMERA)
+camUrl = localUrl if localUrl else vpnUrl
+
+# Request a snapshot from the camera
+r = requests.get(camUrl + SNAPSHOT_REQUEST)
+
+# If all was Ok, I should have a returned HTTP status of 200, else something goes wrong
+if r.status_code != 200 :
+    # Decide what to do with an error situation (alert, log, ...)
+    exit(1)
+
+# Save the snapshot in a file
+with open("MyCamSnap.jpg", "wb") as f: f.write(r.content)
+
+# You can then archive the file, send it by mail, message App, ...
+
+exit(0)

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='lnetatmo',
-    version='1.2.2',
+    version='1.3.2',
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Developers',

usage.md

@@ -332,24 +332,26 @@ for m in weatherData.checkNotUpdated("<optional station name>"):
 at all if you slip over two days as required in a shifting 24 hours window.
 
 
-#### 4-5 WelcomeData class ####
+#### 4-5 HomeData class ####
 
 
 
 Constructor
 
 ```python
-    welcomeData = lnetatmo.WelcomeData( authorization )
+    homeData = lnetatmo.HomeData( authorization )
 ```
 
 
 Requires : an authorization object (ClientAuth instance)
 
 
-Return : a WelcomeData object. This object contains most administration properties of Welcome cameras accessible to the user and the last data pushed by the cameras to the Netatmo servers.
+Return : a homeData object. This object contains most administration properties of home security products and notably Welcome & Presence cameras.
 
 Raise a lnetatmo.NoDevice exception if no camera is available for the given account.
 
+Note : the is_local property of camera is most of the time unusable if your IP changes, use cameraUrls to try to get a local IP as a replacement.
+
 Properties, all properties are read-only unless specified: