Managing Cameras

Cameras module can be part of a gateway and remote users can access the cameras in the gateway's private network.

Control Servlet

The Cameras Manager Bundle registers a ControlServlet for controlling the cameras over HTTP proxy. When you request an action from a specified camera, it is read through the API implementation and forwarded to you through the proxy servlet. The HTTP API is simple and uses the following URI syntax:

/<path>/<action>/<cameraID>?<param1>=<value1>&<param2>=<value2>, where <action> can take the following values:

Action	Description	Parameters
image	It serves a still image snapshot using the StillImageControl interface.	All passed parameters are also passed to the getImage(Map) method as parameters map.
video	It serves a video snapshot using the VideoControl interface.	All passed parameters are also passed to the getVideo(Map) method as parameters map.
record	It serves an image and video recording using the RecordControl interface.	All passed parameters are also passed to the getRecord(Map) method as parameters map.

To request an image from an AXIS camera with ID=1, the syntax is:
/camerasManager/image/1

It returns the default image format, which for AXIS cameras is JPEG.
To request a Bitmap image with resolution 176x144 from an AXIS camera with ID=1, the syntax is:
/camerasManager/image/1?image.format=bitmap&width=176&height=144
To request a default video streaming from an AXIS camera with ID=1, the syntax is:
/camerasManager/video/1
To request Motion JPEG, with specific size and frame rate: (see also transcoder)
/camerasManager/video/1?video.format=mjpeg&width=320&height=200&fpr=5
To request a recording from an AXIS camera with ID=1, the syntax is:
/camerasManager/record/1

Adding and Removing Camera Devices

The adding operation is introduced to meet cases when the underlying protocol does not imply automatic detection of newly-joined camera devices.

To add a new camera device to the system:
1. Obtain the OSGi Cameras Manager service (org.osgi.services.cameras.CamerasManager).
2. Invoke the addCamera method passing the following input data:
java.util.Map props - The custom settings identifying the new camera. These properties are re-directed to the specified camera driver. The properties are defined as com.prosyst.mbs.services.cameras.CamerasManager constants and are as follows:

PROPERTY_USER - The user name of the camera device.

PROPERTY_NAME - The camera's user friendly name.

PROPERTY_ADDRESS - The address at which the new camera can be found.

PROPERTY_PASSWORD - The new camera's password.

PROPERTY_RTSP_PORT - The RTSP port of the camera.

DriverInfo driverInfo - The representation of the registered camera driver.
1. As result, the newly added camera is assigned with unique identifier, which is published through the OSGi Event Admin service.
To remove a camera device, invoke the removeCamera method specifying the unique ID of the target camera device.

Camera Controls

The Cameras module contains a flexible Cameras 3.0 API, whose functionality is to sustain various types of controls. The supported camera drivers implement only the controls provided by the module's API in order to get camera's content or to control the camera. Every camera control implements a CameraControl sub-interface, which defines a control for:

Advanced settings - Used to set and get settings of a camera.
Move - Used to move camera view (this functionality must be supported by the camera) down, up, to the left and to the right.
Zoom - Used to zoom in and zoom out (this functionality must be supported by the camera).
Video - Used to receive camera video streaming.
Still image - Used to obtain still image snapshot (jpeg, bitmap or other image format according to the driver implementations). Some properties can be specified in order to receive custom images.
Record - Used to retrieve camera records. Each record is persistently stored, therefore - reusable.
Presets - Used to get or update different camera positions with given index numbers and names (this functionality must be supported by the camera).
Profiles - Used to get or update different camera settings (resolution, FPS (frames per seconds), format) with given index numbers and names (this functionality must be supported by the camera).

Camera Drivers

The main goal of the camera drivers is to have a common representation of all kind of cameras, no matter what kind of communication, control and content delivery mechanism is used. The camera driver:

Issues the correct types of commands that camera uses for communication and control.
Talks directly to the camera.
Provides a layer to translate native camera commands to the common representation above.

The Cameras Module implements the following camera drivers:

AXIS camera driver (compatible with VAPIX v2 and v3)
ComPro (compatible with IP Camera SDK v0.97c)
IPCAM (compatible with CGI SDK 2.1)
Mobotix camera driver (compatible with Mobotix SDK 1.0.1)
Panasonic camera driver (compatible with CGI Interface v4.3)
MotionGuide camera driver (compatible with Video4Linux 2.0)
UDP Technology camera driver (compatible with NVC HTTP API v1.06.07)
UDP Technology camera driver (compatible with IPX/IPN API v1.3.0)
ONVIF (compatible with Core Specification v1.02)
SerComm (compatible with CGI Interface v1.36)
ZyXEL(compatible with CGI Interface v1.4)
Generic (1.0)

Getting Notifications for Changes in the Camera Set

When a camera is added, updated, or removed an asynchronous event is fired and published by the OSGi Event Admin service. To receive such events through the OSGi Event Admin, you have to implement an org.osgi.service.event.EventHandler interface. The EventHandler service must be registered with the EVENT_TOPIC_ADDED and EVENT_TOPIC_REMOVED topics. In order to specify which camera has issued the event, from the passed Event object is processed the CamerasManager.EVENT_PROPERTY_CAMERA_ID property. The property's Long value provides the ID of the camera.

User Interface

For managing camera devices you can use text commands in the OSGi runtime console. The cameras commands are provided by the Cameras Console Commands bundle (bundles/com.prosyst.mbs.cameras.driver.commands.jar) and are separated in a group, called cameras. See the "Management via Text Console" document for more details on the commands' usage.

Demos

The Cameras Module contains demos illustrating the usage of the API. You can examine them in Eclipse to see java code samples for the following implementations:

The Web Based Camera Viewer Demo provides a Web interface to the camera API allowing you to add, remove, view, and control the available cameras.
The Cameras Driver Demo shows how to create a new camera driver supporting image, video, and record streaming, as well as move, presets, and profiles control.
The Cameras Simulator Demo provides a simulated camera to be used when a real one is not available.
The Cameras Simple Demo shows how to add, update, remove, and control cameras via the Cameras API.

Configuring Debug and Proxy

You can activate the generation of debug information about the operation of the cameras manager through the com.prosyst.mbs.cameras.driver.core.logLevel system property found in the common.prs file in the bin/vms directory. Set the property with value 4, which stands for DEBUG.

System properties can be also used for configuring the proxy settings. For more information refer to "Configuration Properties" section in the Setup Guide.