Camera Management Server
Micasaverde (Talk | contribs) (→alert: Return the details about an alert) |
Micasaverde (Talk | contribs) (→fetch_archive: The cs returns an archived image or video) |
||
| Line 191: | Line 191: | ||
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 == | ||
Revision as of 18:37, 15 September 2011
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.
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"
}
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.
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.
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.
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.
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
list_alerts: The cs returns a list of archived alerts, both system alerts and images and video
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.
fetch_alert: Return the details about an alert
https://cr1.mios.com/fetch_alert?alert=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.
alter_alert: Alert data in the alert
https://cr1.mios.com/alter_alert?alert=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.
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
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).
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.
Refer to the camera's manual for specific settings
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 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
