Camera Management Server

From MiOS
(Difference between revisions)
Jump to: navigation, search
(→‎list_alerts: The cs returns a list of archived alerts, both system alerts and images and video)
(→‎alert: Add an alert to the system)
 
(19 intermediate revisions by one user not shown)
Line 3: Line 3:
  
 
Mios operates a camera server ("cs") which is available at crX.mios.com (ie cr1.mios.com, cr2.mios.com, etc.). Cameras which are shipped with this custom firmware will automatically connect to the cs and report their Mac Address and IP address. Cs stores this in a database along with the external IP that the connection came in on.
 
Mios operates a camera server ("cs") which is available at crX.mios.com (ie cr1.mios.com, cr2.mios.com, etc.). Cameras which are shipped with this custom firmware will automatically connect to the cs and report their Mac Address and IP address. Cs stores this in a database along with the external IP that the connection came in on.
 +
 +
For most of the commands where you need to pass a username and password to the CMS server, you can also pass either a cam or a gateway and the corresponding hwkey if it's known.
  
 
==Locating the camera==
 
==Locating the camera==
Line 60: Line 62:
 
https://cr1.mios.com/archive_video?cam=a&preroll=b&duration=c&format=d&res=e&user=f&pass=g
 
https://cr1.mios.com/archive_video?cam=a&preroll=b&duration=c&format=d&res=e&user=f&pass=g
  
−
where a is the serial number of the camera, 554 in the above example, b is 0 or 1 where 1 means to also capture whatever pre-roll is available from the camera, c is how long in seconds to capture the video, d is "mp4" or "mjpeg", e is "low" or "med" or "high" to indicate the resolution, f and g are the username/password of the MiOS account the camera is paired with.
+
where a is the serial number of the camera, 554 in the above example, b is 0 or 1 where 1 means to also capture whatever pre-roll is available from the camera, c is how long in seconds to capture the video, d is one of the formats id's defined below, e is "low" or "med" or "high" to indicate the resolution, f and g are the username/password of the MiOS account the camera is paired with.
  
 
The pre-roll is a given number of seconds at a given resolution as specified in the "config" command.
 
The pre-roll is a given number of seconds at a given resolution as specified in the "config" command.
Line 72: Line 74:
 
==list_alerts: The cs returns a list of archived alerts, both system alerts and images and video  ==
 
==list_alerts: The cs returns a list of archived alerts, both system alerts and images and video  ==
  
−
https://cr1.mios.com/list_alerts?cam=a&gateway=b&unread=1&type=c&source=d&format=e&device=f&count=g&start=h&before=i&after=j&user=k&pass=l
+
https://cr1.mios.com/list_alerts?cam=a&gateway=b&unread=1&type=c&source=d&format=e&device=f&count=g&start=h&before=i&after=j&user=k&pass=l&userevt=m
  
 
This returns a list of archives in JSON format as follows:
 
This returns a list of archives in JSON format as follows:
Line 98: Line 100:
 
             "value": "",
 
             "value": "",
 
             "description": "Camera Image",
 
             "description": "Camera Image",
 +
            "key": "1278",
 
             "comments": ""
 
             "comments": ""
 
         }
 
         }
Line 105: Line 108:
 
The arguments are as follows:
 
The arguments are as follows:
  
−
cam=If specified this is the id of the camera.  Only alerts from this camera are included.
+
cam=If specified this is the id of the camera(s).  Only alerts from this camera(s) are included.  Multiple cameras should be comma separated.  Or specify * for all cameras the user has access to.
  
−
gateway=If specified this is of a gateway.  Only alerts from this gateway are included.
+
gateway=If specified this is of a gateway(s).  Only alerts from this gateway(s) are included.  Multiple cameras should be comma separated.  Or specify * for all gateways the user has access to.
  
−
NOTE: If neither cam nor gateway is specified, only alerts from the user which is passed for validation are included.
+
user=See note below.
 +
 
 +
NOTE: If neither cam nor gateway is specified, only alerts from the user which is passed for validation are included, such as login events.  If a cam(s) and or gateways(s) are specified, then user alerts as well as gateway/cam alerts are included.  If you only want gateway/cam alerts, add a user=0.  This will exclude user events.  So gateway=1,3&cam=* will include alerts from gateways #1 and 3, as well as all cameras, plus the users alerts.  Adding user=0 will exclude the users alerts.  If user=0 is specified without any gateway or cam no records are returned.  Note that alerts from a gateway/cam will not be included if the gateway/cam is not already paired to the user's account.
  
 
unread=If this is a '1' only alerts that haven't been read yet are included
 
unread=If this is a '1' only alerts that haven't been read yet are included
Line 125: Line 130:
 
start=Starting with this row number
 
start=Starting with this row number
  
−
before= / after= a date range in the format yyyy-mm-dd (optionally add hh:mm:ss)
+
before= / after= a date range as a unix timestamp (ie an integer in UTC time).  You cannot use local time because some devices, like cameras, don't have a clock/timezone setting, so the times are universal timestamps applied by the server and not local times on the device.
  
 
The return data in json is as follows:
 
The return data in json is as follows:
Line 164: Line 169:
  
 
description=A description for the alert.  For triggers this is the user-defined trigger name.
 
description=A description for the alert.  For triggers this is the user-defined trigger name.
 +
 +
key=A unique, random value for each alert.  When you need to modify an alert you will pass back the key to confirm you are authorized.
  
 
comments=Comments which the user has associated with the alert.
 
comments=Comments which the user has associated with the alert.
  
 
If a file is associated with the alert, see the fetch_archive call.
 
If a file is associated with the alert, see the fetch_archive call.
 +
 +
==fetch_alert: Return the details about an alert==
 +
 +
https://cr1.mios.com/fetch_alert?id=a&key=b
 +
 +
Pass in the key from the alert (see list_alerts) as b and the alert id as a.  This returns the details about the alert, including any notification attempts, as follows.  Note the status codes for contacts and attempts are in the defined constants section:
 +
 +
{
 +
    "id": 192890,
 +
    "username": "aaronb",
 +
    "contacts": [
 +
        {
 +
            "id": 10,
 +
            "type": 1,
 +
            "destination": "john@gmail.com",
 +
            "numattempts": 0,
 +
            "status": "",
 +
            "contents": "200820:\r\n=\r\nserial:-\r\n",
 +
            "username": "john",
 +
            "attempts": [
 +
                {
 +
                    "timestamp": 182821717,
 +
                    "status": "1",
 +
                    "notes": "busy"
 +
                },
 +
                {
 +
                    "timestamp": 1812717,
 +
                    "status": "2",
 +
                    "notes": "complete"
 +
                }
 +
            ]
 +
        },
 +
        {
 +
            "id": 20,
 +
            "type": 3,
 +
            "destination": "+1310-555-0800",
 +
            "numattempts": 0,
 +
            "status": "",
 +
            "contents": "200820:\r\n=\r\nserial:-\r\n",
 +
            "username": "john"
 +
        }
 +
    ]
 +
}
 +
 +
==alter_alert: Alert data in the alert==
 +
 +
https://cr1.mios.com/alter_alert?id=a&key=b&read=c&deleted=d&locked=e&comments=f
 +
 +
This will change the alert 'a'.  Pass in the key from the alert (see list_alerts) as b.  Optionally pass in a unix timestamp for c to indicate if it's read, or 0 to indicate it is unread.  Pass in 0 or 1 for deleted or locked (d or e) to indicate if the record should be deleted, or if it's locked, meaning it won't be deleted after the expiration.  Comments will update the user comments for an alert.  Don't forget to properly URL encode the comments.  read, deleted, locked and comments are all optional, although at least one must be specified.
 +
 +
==alert: Add an alert to the system==
 +
 +
https://cr1.mios.com/alert?PK_AccessPoint=a&PK_Accessory=b&EK_User=c&HW_Key=d&user=e&pass=f&DeviceID=g&LocalDate=h&AlertType=i&SourceType=j&Argument=k&Format=l&Code=m&Value=n&Description=o&Users=p&Expiration=q
 +
 +
Expiration should be a unix timestamp
  
 
==fetch_archive: The cs returns an archived image or video  ==
 
==fetch_archive: The cs returns an archived image or video  ==
  
 
https://cr1.mios.com/fetch_archive?id=a&user=b&pass=c
 
https://cr1.mios.com/fetch_archive?id=a&user=b&pass=c
 +
 +
or
 +
 +
https://cr1.mios.com/fetch_archive?id=a&key=b
  
 
==move_camera: Tells the cs to move the camera ==
 
==move_camera: Tells the cs to move the camera ==
Line 194: Line 260:
 
Here are the defined constants for format, resolution, etc., and the extensions that correspond to formats:
 
Here are the defined constants for format, resolution, etc., and the extensions that correspond to formats:
  
−
  #define ALERT_IMAGE     1
+
#define ALERT_IMAGE                             1
−
  #define ALERT_VIDEO     2
+
#define ALERT_VIDEO                             2
−
 
+
#define ALERT_TRIGGER                  3
 +
#define ALERT_VARIABLE                  4
 +
#define ALERT_LOGON                            5
 +
#define ALERT_GATEWAY_CONNECTED 6  // If the external IP changes or if it's been>  24 hours since last report
 +
 
 
   #define FORMAT_JPEG    1
 
   #define FORMAT_JPEG    1
 
   #define FORMAT_MJPEG    2
 
   #define FORMAT_MJPEG    2
Line 208: Line 278:
 
   #define SOURCE_TIMER  2
 
   #define SOURCE_TIMER  2
 
   #define SOURCE_TRIGGER  3
 
   #define SOURCE_TRIGGER  3
 +
  #define SOURCE_VARIABLE 4
 +
 +
  #define CONTACT_STATUS_SUCCESS 0
 +
  #define CONTACT_STATUS_PROCESSING 1
 +
  #define CONTACT_STATUS_FAILED 2
 +
  #define CONTACT_STATUS_RETRY 3
 +
 +
  #define ATTEMPT_STATUS_SUCCESS 0
 +
  #define ATTEMPT_STATUS_PROCESSING 1
 +
  #define ATTEMPT_STATUS_FAILED 2

Latest revision as of 23:31, 19 March 2012

Certain cameras come with custom firmware so that they automatically connect to the MiOS camera management server (cms), creating a tunnel the cms can use to send commands to the camera and to act as a relay so users can view and control the camera when outside the home without having to change their firewall.

Mios operates a camera server ("cs") which is available at crX.mios.com (ie cr1.mios.com, cr2.mios.com, etc.). Cameras which are shipped with this custom firmware will automatically connect to the cs and report their Mac Address and IP address. Cs stores this in a database along with the external IP that the connection came in on.

For most of the commands where you need to pass a username and password to the CMS server, you can also pass either a cam or a gateway and the corresponding hwkey if it's known.

Contents

[edit] Locating the camera

To get the list of all cameras and MiOS systems on your current home network, read this URL: http://sta1.mios.com/locator_json2.php which returns the list in JSON format. To add to the list all cameras that are off the home network but which can be access remotely with a given username, add a ?username=x to the URL, such as http://sta1.mios.com/locator_json2.php?username=johndoe

A camera will look like this: 

     {
           "serialNumber": "554",
           "Alive": 0,
           "name": "Good camera",
           "mfr": "Mios",
           "ipAddress": "192.168.2.27",
           "category": "2",
           "subcategory": "1",
           "users": "16782,3",
           "ImageUrl_LR": "img/snapshot.cgi?size=320x240&quality=4",
           "MJpegUrl_LR": "img/video.mjpeg",
           "MP4Url_LR": "img/video.asf",
           "ImageUrl_HR": "img/snapshot.cgi?size=640x480&quality=2",
           "MJpegUrl_HR": "img/video.mjpeg",
           "MP4Url_HR": "img/video.asf",
           "CanRelay": "1",
           "Port": "80",
           "local_remote": "1",
           "relay_remote": "1",
           "active_server": "cr1.mios.com"
       }

[edit] Local vs remote access

In the Json data above, "active_server" tells you which Cs the camera connects to. So to view or control this camera connect to cr1.mios.com. If the camera is on the same network as the client, then ipAddress will have an ip. Otherwise there is no ipAddress. If the ipAddress is specified, then you can access the camera on the local network, without going through the relay server, by using ImageUrl, MJpegUrl and MP4Url tags to fetch a JPEG Image, MJPEG stream, or MP4 stream. _LR are low res verseions, _HR are high res. If CanRelay is 1, then this camera connects to the cs and you can also view the camera remotely using the Cs.

[edit] request_video: Request video from a camera

To view the video from the camera, open this URL:

https://cr1.mios.com/request_video?cam=a&format=b&res=c&user=d&pass=e

where a is the serial number of the camera, 554 in the above example, b is one of the defined constants below, c is the resolution and can be l or m or h, d and e are the username/password of the MiOS account the camera is paired with.

This will return another URL. If the viewer is on the same home network as the camera the URL will point directly to the camera. Otherwise it will be a Url, for example http://209.160.41.93:80/relay_viewer?cam=554&pass=2024848122, which points to the Cs with a use-once token. In this case the URL can only be used one time, and must be used within 1 minute of making the request.

[edit] request_image: Request image from a camera

To fetch a JPEG that is the current image from the camera, open this URL:

https://cr1.mios.com/request_image?cam=a&res=b&user=c&pass=d

where a is the serial number of the camera, 554 in the above example, b is "low" or "med" or "high" to indicate the resolution, c and d are the username/password of the MiOS account the camera is paired with. Calling this with "low" is the right way to get at thumbnail. This URL returns the JPEG image directly.

[edit] archive_video: Tells the cs to archive video from the camera

This command causes the cs to capture video from the camera and add it to the video archive for the user. The camera must be linked to a mios.com account.

https://cr1.mios.com/archive_video?cam=a&preroll=b&duration=c&format=d&res=e&user=f&pass=g

where a is the serial number of the camera, 554 in the above example, b is 0 or 1 where 1 means to also capture whatever pre-roll is available from the camera, c is how long in seconds to capture the video, d is one of the formats id's defined below, e is "low" or "med" or "high" to indicate the resolution, f and g are the username/password of the MiOS account the camera is paired with.

The pre-roll is a given number of seconds at a given resolution as specified in the "config" command.

[edit] archive_image: Tells the cs to archive an image from the camera

This is like archive_video except it stores a single image. If retimg=1 then the image being archived will also be returned by the Url, just like request_image.

https://cr1.mios.com/archive_image?cam=a&res=b&user=c&pass=d&retimg=e

[edit] list_alerts: The cs returns a list of archived alerts, both system alerts and images and video

https://cr1.mios.com/list_alerts?cam=a&gateway=b&unread=1&type=c&source=d&format=e&device=f&count=g&start=h&before=i&after=j&user=k&pass=l&userevt=m

This returns a list of archives in JSON format as follows: 

{
   "records": [
       {
           "id": 192817,
           "gateway": "0",
           "cam": "554",
           "user": "",
           "notification": "1827",
           "device": "0",
           "timestamp": "18217271",
           "date": "",
           "expiration": "18217271",
           "read": "",
           "type": "1",
           "source": "0",
           "format": "jpg",
           "ip": "192.168.2.27",
           "locked": "0",
           "size": "32728",
           "code": "",
           "value": "",
           "description": "Camera Image",
           "key": "1278",
           "comments": ""
       }
   ]
 }

The arguments are as follows:

cam=If specified this is the id of the camera(s). Only alerts from this camera(s) are included. Multiple cameras should be comma separated. Or specify * for all cameras the user has access to.

gateway=If specified this is of a gateway(s). Only alerts from this gateway(s) are included. Multiple cameras should be comma separated. Or specify * for all gateways the user has access to.

user=See note below.

NOTE: If neither cam nor gateway is specified, only alerts from the user which is passed for validation are included, such as login events. If a cam(s) and or gateways(s) are specified, then user alerts as well as gateway/cam alerts are included. If you only want gateway/cam alerts, add a user=0. This will exclude user events. So gateway=1,3&cam=* will include alerts from gateways #1 and 3, as well as all cameras, plus the users alerts. Adding user=0 will exclude the users alerts. If user=0 is specified without any gateway or cam no records are returned. Note that alerts from a gateway/cam will not be included if the gateway/cam is not already paired to the user's account.

unread=If this is a '1' only alerts that haven't been read yet are included

type=Only alerts of this type are included (see alert types below)

source=Only alerts from this source are included (see source types below)

format=Only alerts containing files of this format are included (eg mp4, jpg, mjpeg).

device=If a gateway is specified, only alerts from this device id on the gateway are included.

count=This many rows are included

start=Starting with this row number

before= / after= a date range as a unix timestamp (ie an integer in UTC time). You cannot use local time because some devices, like cameras, don't have a clock/timezone setting, so the times are universal timestamps applied by the server and not local times on the device.

The return data in json is as follows:

id=A numeric id of the alert

gateway=The id of the gateway that generated the alert, if any

cam=The id of the camera that generated the alert, if any

user=The id of the user that generated the alert, if any

notification=If user(s) were sent a notification of the alert (SMS, email) this is the id of the notification attempt(s)

device=If a device on a gateway generated the alert this is the device id

timestamp=The date when the alert was received as a unix timestamp

date=The date according to the gateway, specified in local time as yyyy-mm-dd hh:mm:ss

read=The date when the alert was read by the user as a unix timestamp

expiration=The date when the alert will be automatically deleted as a unix timestamp

type=The type of alert: 1=Image (a camera sent an image), 2=Video (a camera sent a video clip), 3=Trigger (a user-created trigger was fired), 4=Variable (a device changed state, such as a door was unlocked, a user code entered, a sensor tripped), 5=Login (a user logged into the portal), 6=Gateway Connected (a gateway came online)

source=What caused the alert to be generated: 1=User (e.g. user hit 'record' button or otherwise initiated the alert), 2=Timer (an automatic timer generated it), 3=Trigger (a user-created trigger), 4=Variable (some device changed state)

format=If there's a file associated with the alert, this is the extension, such as mpg, jpg, mjpeg

ip=The IP that sent the alert

locked=If 1 the alert will not automatically delete on the expiration

size=If there's a file associated with the alert, this is the size of the file

code and value=These depend on the type of alert. For Variables 'code' is the name of the variable (state) that changed and value is the new value.

description=A description for the alert. For triggers this is the user-defined trigger name.

key=A unique, random value for each alert. When you need to modify an alert you will pass back the key to confirm you are authorized.

comments=Comments which the user has associated with the alert.

If a file is associated with the alert, see the fetch_archive call.

[edit] fetch_alert: Return the details about an alert

https://cr1.mios.com/fetch_alert?id=a&key=b

Pass in the key from the alert (see list_alerts) as b and the alert id as a. This returns the details about the alert, including any notification attempts, as follows. Note the status codes for contacts and attempts are in the defined constants section: 

{
   "id": 192890,
   "username": "aaronb",
   "contacts": [
       {
           "id": 10,
           "type": 1,
           "destination": "john@gmail.com",
           "numattempts": 0,
           "status": "",
           "contents": "200820:\r\n=\r\nserial:-\r\n",
           "username": "john",
           "attempts": [
               {
                   "timestamp": 182821717,
                   "status": "1",
                   "notes": "busy"
               },
               {
                   "timestamp": 1812717,
                   "status": "2",
                   "notes": "complete"
               }
           ]
       },
       {
           "id": 20,
           "type": 3,
           "destination": "+1310-555-0800",
           "numattempts": 0,
           "status": "",
           "contents": "200820:\r\n=\r\nserial:-\r\n",
           "username": "john"
       }
   ]
}

[edit] alter_alert: Alert data in the alert

https://cr1.mios.com/alter_alert?id=a&key=b&read=c&deleted=d&locked=e&comments=f

This will change the alert 'a'. Pass in the key from the alert (see list_alerts) as b. Optionally pass in a unix timestamp for c to indicate if it's read, or 0 to indicate it is unread. Pass in 0 or 1 for deleted or locked (d or e) to indicate if the record should be deleted, or if it's locked, meaning it won't be deleted after the expiration. Comments will update the user comments for an alert. Don't forget to properly URL encode the comments. read, deleted, locked and comments are all optional, although at least one must be specified.

[edit] alert: Add an alert to the system

https://cr1.mios.com/alert?PK_AccessPoint=a&PK_Accessory=b&EK_User=c&HW_Key=d&user=e&pass=f&DeviceID=g&LocalDate=h&AlertType=i&SourceType=j&Argument=k&Format=l&Code=m&Value=n&Description=o&Users=p&Expiration=q

Expiration should be a unix timestamp

[edit] fetch_archive: The cs returns an archived image or video

https://cr1.mios.com/fetch_archive?id=a&user=b&pass=c

or

https://cr1.mios.com/fetch_archive?id=a&key=b

[edit] move_camera: Tells the cs to move the camera

https://cr1.mios.com/move_camera?cam=a&dir=b&user=c&pass=d

Where dir can be "up", "down", "left", "right", "in" or "out" (for zoom).

[edit] send: Sends a URL to the camera

https://cr1.mios.com/send?cam=a&user=b&pass=c&url=d

Everything after the url= is sent to the camera.

For example: https://cr1.mios.com/send?cam=37117&user=johndoe&pass=mypassword123&url=/adm/set_group.cgi?group=VIDEO&exposure=1&sharpness=7

Refer to the camera's manual for specific settings

[edit] defined constants

Here are the defined constants for format, resolution, etc., and the extensions that correspond to formats: 

#define ALERT_IMAGE                             1
#define ALERT_VIDEO                             2
#define ALERT_TRIGGER                   3
#define ALERT_VARIABLE                  4
#define ALERT_LOGON                             5
#define ALERT_GATEWAY_CONNECTED 6  // If the external IP changes or if it's been>  24 hours since last report

 #define FORMAT_JPEG    1
 #define FORMAT_MJPEG    2
 #define FORMAT_MP4    3
 
 #define EXT_JPEG    "jpg"
 #define EXT_MJPEG    "mjpg"
 #define EXT_MP4      "mp4"
 
 #define SOURCE_USER    1
 #define SOURCE_TIMER  2
 #define SOURCE_TRIGGER  3
 #define SOURCE_VARIABLE 4

 #define CONTACT_STATUS_SUCCESS	0
 #define CONTACT_STATUS_PROCESSING	1
 #define CONTACT_STATUS_FAILED		2
 #define CONTACT_STATUS_RETRY		3

 #define ATTEMPT_STATUS_SUCCESS	0
 #define ATTEMPT_STATUS_PROCESSING	1
 #define ATTEMPT_STATUS_FAILED		2
Retrieved from "http://wiki.mios.com/index.php?title=Camera_Management_Server&oldid=4129"
Personal tools