What Are Camera Identifiers, and how use them?

This article describes the different types of camera identifiers utilized by Nx Witness Server and how to obtain them. These include the Physical ID (~ MAC address), Camera ID (system designated UUID), and Logical ID (a simplified version of the Camera ID). Camera identifiers are important for performing tasks involving the cameras in a System e.g. API requests and for creating any integration that utilizes the cameras in the System.

What are Physical ID, Camera ID, and Logical ID?

The Physical ID of a camera is usually the same as its MAC address. It can be used for utilizing live or recorded video from the camera(s) in your Nx Witness system; however, this is not the preferred method. The video archive (located in storage) is also organized by a camera’s Physical ID.

The Camera ID is a UUID that the system assigns to each camera, usually in a format that looks similar to f93369eb-e530-27b7-78ba-16978cbd3061. The Camera ID is preferred when performing API calls. It is also used for “devices” such as virtual camera instances, encoders, I/O units, etc.

The Logical ID simplifies device identification when integrating with third-party systems, and is necessary for environments with input fields that are not capable of entering the full Camera ID due to a limitation in the maximum number of characters. A Logical ID also simplifies the process of replacing one camera with another, without changing the identifiers in the integration. The Logical ID can be used in API calls (including getting RTSP streams, etc.) to address cameras.

How to Obtain the Physical and Camera ID?

Using the Nx Witness Desktop Client (version 3.0 and newer)

1. Right-click on a camera and select the Camera Settings menu.
2. In the General tab, select the More Info arrow located beneath Vendor and Model. You will find the camera and Physical ID there. 

Note: The MAC address is also the Physical ID.

Using an API Request 

Since Nx Witness 4.3, our API received an update that changed the method for performing certain requests. For finding the Camera ID, /rest/v1/devices will be used.

An example format of a basic request for viewing the response in the browser is the following request below. In this example, we set the response format type to XML and sorted the list by the devices’ names:

https://<serverip>:<port>/rest/v1/devices?_format=XML&_orderBy=name

The Camera ID is found above the device name in the tag <id>. The Physical ID is found below the Camera ID in the <mac> tag.

Use these extra parameters to meet your requirements; for example, incorporating device checking in an integration and receiving the response in a specific format. Refer to /rest/v1/devices in our API Documentation for more information.

• _format — Enter the response format type.
  • By default, JSON is used.
• _with — Enter a comma-separated list of field names, where only objects which have at least one field from this list will be included in the response.
• filter — This is a family of parameters rather than a fixed-name parameter: any number of response object fields can be specified as parameters, with the desired field values as parameter values.
• _keepDefault — If false or unspecified, then in the response objects the Server will not omit fields that have values equal to their default values. Otherwise, such fields will be omitted.
• _orderBy — Choose your preferred sort order. Can be by name, id, server, etc.

Example using the _with parameter to limit the objects in the response to what you specify, in this case, only the <id>, <mac>, and <model> tags are shown:

https://localhost:7001/rest/v1/devices?_format=XML&_with=id%2Cmac%2Cmodel&_orderBy=id

Using API Request (Old Method)

This method uses our old API (now deprecated).

1. In the browser, type the following HTTP request:

http://<server_ip>:<server_port>/ec2/getCamerasEx?extraFormatting

server_ip = the IP address or URL of the Nx Witness Server you are requesting this information from
server_port = the port your System is using (typically 7001)

For example, an API call to Nx Witness could look like:

http://127.0.0.1:7001/ec2/getCamerasEx?extraFormatting

Note: When making an API call, you can use any Server in the System.

2. You should now see something similar to the screenshot below:

3. Search the page (CTRL + F) and enter the name of the camera you are searching for, using the camera name in your System (e.g. "Kitchen"). Also, the camera IP address can be used for the search.

Locating the Physical ID

Located above the camera name, you will notice a parameter called physicalId. This attribute value is the Physical ID and will be the folder name for "recording" and the "smart motion index". In this case, the Physical ID is 00-1C-A6-01-6E-6E.

Locating the Camera ID

Located above the camera name is a parameter called id. This attribute value is the Camera ID and should be put to different API calls (PTZ, HLS, RTSP, etc.). The value should be used without quotation marks and with or without parenthesis. For example, in this case you add 0b73e6d1-a5d3-2868-41c7-b52994f4107d to your api call as a parameter. 

Note: Camera name in the screenshot below is “Cube”.

How to set up the Logical ID?

Assigning a Logical ID

1. Right-click on a camera and select the Camera Settings menu.
2. Navigate to the Expert tab.
3. Look for the Logical ID field at the right of the center of the menu and enter a number in the Logical ID field.
4. Click Apply.

If you are already using 1 to 3 digit identifiers, use the Generate button to discover and display the smallest number that is not already in use.

Removing a Logical ID

Press the Reset button. This sets the Logical ID to zero, which the API equates to having no Logical ID.