Articles in this section

Adding a camera or a RTSP stream using API

Avatar
Andrey Terentyev
  • Updated
Follow

-------------------------
Affected Roles: System Owner • System Administrator 
Related Nx VMS Apps: Nx Server 
Difficulty: High
-------------------------

Adding a camera

Adding a generic RTSP stream

Abstract

The article exposes the procedure of how to programmatically add a camera or a generic RTSP resource. Manual invocation of API calls is being discovered in step by step manner in order to make possible the procedure be automated by a script.

Adding a camera

In order to add a camera three Server API calls have to be invoked sequentially.

  • manualCamera/search
  • manualCamera/status
  • manualCamera/add

NOTE: Between manualCamera/search and manualCamera/status API calls, the timeout of at lest 5 seconds should be preserved.

Server API requires definite Server URL for calling API, i.e. /api/ instead of /ec2/ for System API. Invocation of these methods corresponds to the operations performed by the Nx Client in  “Add device...” dialog window.dialog_window.png

Invoking manualCamera/search

This API has to be called to get initial processUuid for further activities.

Log in with a web browser to your server which the camera is connected to.

http://<your server address>:<port>
For example: http://localhost:7001

Select the “For Developers” menu item. Then click the link “API Testing Tool (new)” for_dev_menu_item.png

In the search field type “manual”. Click the link “manualCamera/search” appeared in the method tree below. camera_search_method.png
On the page appeares

  • in the “start_ip” field type an IP address of your camera;

NOTE: When you enter an IP address of your camera the Server will try to autodiscover it’s parameters and will update those automatically in periodic manner. See the screenshot in step "Invoking manualCamera/status". That means any manual changes of parameters for a camera will not persist.

  • in the “user” field type a username for logging into your camera;
  • in the “password” type a password for logging into your camera;
  • click “Test method” button;
  • make sure the “error” value is zero in the “Response” field;
  • copy the “processUuid” value to clipboard or to a text file.

camera_search_method_output.png

Invoking manualCamera/status

With this API the attributes of camera found are received to be passed to manualCamera/add API call.

Click the “manualCamera/status” link in the method tree.

camera_status_output.pngIn the “uuid” field paste the “processUuid” has been got in the step “Invoking manualCamera/search”.

Click the “Test method” button.

In the “Response” field you will see json formatted object. Copy json array named “cameras” shown on the screenshot above to the test editor of your choice. Exactly, starting with “cameras” and ending by closing square bracket.

Invoking manualCamera/add

Click the “manualCamera/add” link in the method tree. On the top of the page you see the example of the data structure of the parameters passed to the method.

{
   "user": "some_user",
   "password": "some_password",
   "cameras": [
   {
     "uniqueId": "00-1A-07-00-FF-FF",
     "url": "192.168.0.100",
     "manufacturer": "3100"
   }
  ]
}

This structure is a json object. You could compose this object by any tool of your choice. As you can notice, this object has to have  the “cameras” array assigned with parameters received in the step Invoking manualCamera/status. Namely,

  • "uniqueId",
  • "url",
  • "manufacturer".

At the moment Server’s API Testing Tool does not allow direct passing json object to the  manualCamera/add method. We will show the invocation of this method with the help of python. Of course, you can use any tool of your choice: curl, bash, php etc.

The code is presented below. We assume the res variable contains output of the manualCamera/status method.

import requests
import json

res = {
 "error": "0",
 "errorString": "",
 "reply": {
 "cameras": [
 {
   "existsInPool": true,
   "manufacturer": "Hilvision",
   "name": "DS-2CD2132F-IWS",
   "uniqueId": "BC-AD-28-02-62-EE",
   "url": "http://192.168.0.64:80/onvif/device_service",
   "vendor": "HIKVISION"
 }
 ],
 "processUuid": "{29a39aa8-cfa2-4899-bf04-7223ff11adf1}",
 "status": {
 "current": "100",
 "state": 3,
 "total": "100"
 }
}

server_ip="your.server.address"
server_api="api"
system_api="ec2"
username='admin'
password='your_password'

payload = dict(
 user='camera_login',
 password='camera_password',
# constructing the json array with one json object 
cameras=[ dict(
   uniqueId=res["reply"]["cameras"][0]["uniqueId"],
   url=res["reply"]["cameras"][0]["url"],
   manufacturer=res["reply"]["cameras"][0]["manufacturer"]
 )]
)

nx_method = 'manualCamera/add'
server_url="http://"+server_ip+":7001/"+server_api+"/"+nx_method
res = requests.post(
 server_url,
 auth=(username,password),
 json=payload
)

res = res.json()
print(res)

Adding a generic RTSP stream

In order to add a generic RTCP stream three Server API calls have to be invoked sequentially.

  • manualCamera/search
  • manualCamera/status
  • manualCamera/add

Server API requires definite URL for calling API, i.e. /api/ instead of /ec2/ for System API.

Invocation of these methods corresponds to the operations performed by the Nx Client in “Add device...” dialog window.

Though the procedure looks similar to that of adding a camera it has slight differences.

Invoking manualCamera/search

This API has to be called to get initial processUuid for further activities.

Log in with a web browser to your server which the camera is connected to.

http://<your server address>:<port>

For example: http://localhost:7001  

Select the “For Developers” menu item. Then click the link “API Testing Tool (new)”

In the search field type “manual”.

Click the link “manualCamera/search” appeared in the method tree below.

rtsp_stream_search.png

On the page appeares

  • in the “start_ip” field type an URL of your stream;

NOTE: When you enter an URL of the specific stream (as shown below for instance) the Server will assign vendor type of “GENERIC_RTSP” and will NOT autodiscover parameters as well as will NOT update those periodically. That means any manual changes of parameters will persist.

  • in the “user” field type a username for logging into your camera;
  • in the “password” type a password for logging into your camera;
  • click “Test method” button;make sure the “error” value is zero in the “Response” field;
  • copy the “processUuid” value to clipboard or to a text file.

Invoking manualCamera/status

With this API the attributes of a resource corresponding to RTSP stream are received to be passed afterwards to the manualCamera/add API call. Click the “manualCamera/status” link in the method tree. rtsp_stream_status.pngIn the “uuid” field paste the “processUuid” has been got in the step “Invoking manualCamera/search” for a generic RTSP stream. Click the “Test method” button.

If you typed an URL in the “start_ip” field for the “manualCamera/search” method you will get slightly different values of “cameras” array parameters compared to those of a camera. See a screenshot above.

In the “Response” field you will see json formatted object. Copy json array named “cameras” shown on the screenshot above to the test editor of your choice. Exactly, starting with “cameras” and ending by closing square bracket.

Invoking manualCamera/add

The API method for adding a generic RTSP stream differs from that for a camera. Exactly,

  • it utilises HTTP GET method;
  • because of that, the parameters are passed in the URL, not in the json object;
  • the parameters has to be named like this
    • user
    • assword
    • uniqueId0
    • url0
    • manufacturer0

We will show the invocation of this method with the help of python. Of course, you can use any tool of your choice: curl, bash, php etc.

Here is the code. We assume the res variable contains output of the manualCamera/status method.

import requests
import json

res = {
 "error": "0",
 "errorString": "",
 "reply": {
 "cameras": [
 {
   "existsInPool": false,
   "manufacturer": "THIRD_PARTY_COMMON",
   "name": "GENERIC_RTSP-101",
   "uniqueId": "30-1B-F7-A0-BB-95",
   "url": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/101",
   "vendor": "GENERIC_RTSP"
 }
 ],
   "processUuid": "{d34d1e29-aa83-4089-9445-7934fe0fcfd8}",
   "status": {
     "current": "100",
     "state": 3,
     "total": "100"
    }
 }
}

# actually composing a json object,
payload = dict(
 user='admin',
 password='your_password',
 uniqueId0=res["reply"]["cameras"][0]["uniqueId"],
 url0=res["reply"]["cameras"][0]["url"],
 manufacturer0=res["reply"]["cameras"][0]["manufacturer"]
 
)
nx_method = 'manualCamera/add'
server_url="http://"+server_ip+":7001/"+server_api+"/"
request_url=server_url+nx_method
# the requests.get method transforms payload object to the URL-passed parameters
res = requests.get(
 request_url,
 auth=(username,password),
 params=payload
)
res = res.json()
print(res)

 Related articles:

Changing resource attributes using API

 

Related articles

Comments

0 comments

Please sign in to leave a comment.