FreewayCAM Programmer’s Manualdoc.arhungary.com/freewaycam/freewaycam_programmers_manual.… ·...

/58 Page 2/58

FreewayCAM Programmer’s Manual


For versions from 1.12.0.8

Document version: 13.05.09

Table of Contents

Introduction ................................................................................................................................................................................................................5 The Camera Software...............................................................................................................................................................................................5 The Camera Modules ...............................................................................................................................................................................................6 General Communication Interface......................................................................................................................................................................8

Setting Parameter Values .................................................................................................................................................................................8 Retrieving Parameter Values...........................................................................................................................................................................8 Retrieving Parameter Ranges .........................................................................................................................................................................9

Image Capturing Interface .................................................................................................................................................................................. 10 1. Introduction................................................................................................................................................................................................... 10 2. Image Sensor................................................................................................................................................................................................. 11 3. Frame Limiter ................................................................................................................................................................................................ 12 4. Flash Driver .................................................................................................................................................................................................... 12 5. De-Bayer.......................................................................................................................................................................................................... 13 6. Color Correction........................................................................................................................................................................................... 13 7. Gamma Correction...................................................................................................................................................................................... 14 8. Mirroring and Rotation .............................................................................................................................................................................. 15 9. Image Compressor ...................................................................................................................................................................................... 15 10. Motion Detector ........................................................................................................................................................................................ 16 11. Analyzer ........................................................................................................................................................................................................ 18 12. Frame Buffers.............................................................................................................................................................................................. 18 12.1 Getting Images from the Frame Buffer ........................................................................................................................................... 19

12.1.1 Operation of the Frame Buffer ................................................................................................................................................. 19 12.1.2 Parameters of Captured Frames (Images)............................................................................................................................ 19 12.1.3 The Capture Parameter............................................................................................................................................................... 19

13. Properties..................................................................................................................................................................................................... 20 System Hardware Date and Time ..................................................................................................................................................................... 22

1. Introduction................................................................................................................................................................................................... 22 2. Retrieving Time Parameters..................................................................................................................................................................... 22

2.1 Querying Custom Time Information ............................................................................................................................................ 23 Automatic Zoom Control..................................................................................................................................................................................... 24

1. Manual Method ............................................................................................................................................................................................ 24 2. Automatic Method...................................................................................................................................................................................... 24

2.1 Mandatory Parameters for Automatic (ZFG) Zooming ......................................................................................................... 25 3. Parameter Sets.............................................................................................................................................................................................. 26 4. Errors ................................................................................................................................................................................................................ 26

Automatic Focus Control..................................................................................................................................................................................... 27 1. Manual Method ............................................................................................................................................................................................ 27 2. Autofocus ....................................................................................................................................................................................................... 27

2.1 The ROI (Region of Interest) Box.................................................................................................................................................... 27 3. Brightness and Autofocus ........................................................................................................................................................................ 27 4. Parameters ..................................................................................................................................................................................................... 28

5. Focus correction........................................................................................................................................................................................... 28 5. Errors ................................................................................................................................................................................................................ 28

Automatic Brightness Control ........................................................................................................................................................................... 29 1. Manual Mode ................................................................................................................................................................................................ 29 2. BrightNow! ..................................................................................................................................................................................................... 29 3. Automatic Mode .......................................................................................................................................................................................... 29 4. Module Parameters..................................................................................................................................................................................... 30 5. Operation of Strategies ............................................................................................................................................................................. 31

5.1 ANPR and Overview Strategies ...................................................................................................................................................... 31 5.2 The Quick Strategy ............................................................................................................................................................................. 31

6. Errors ................................................................................................................................................................................................................ 31 Illuminator Configuration Manager................................................................................................................................................................. 31 Scheduler Trigger ................................................................................................................................................................................................... 32

1. Introduction................................................................................................................................................................................................... 32 2. Basic Parameters .......................................................................................................................................................................................... 32

2.1 Information Commands ................................................................................................................................................................... 33 3. Level and Edge Control ............................................................................................................................................................................. 33 4. Errors ................................................................................................................................................................................................................ 33

Upload Manager ..................................................................................................................................................................................................... 34 1. Introduction................................................................................................................................................................................................... 34 2. Parameters ..................................................................................................................................................................................................... 34 3. Processing Logging Data .......................................................................................................................................................................... 36 4. Errors ................................................................................................................................................................................................................ 36

Event Manager ........................................................................................................................................................................................................ 37 1. Short Description......................................................................................................................................................................................... 37 2. Detailed Description................................................................................................................................................................................... 37

2.1 Trigger Inputs and Master Output ................................................................................................................................................ 37 2.2 Registering ............................................................................................................................................................................................ 37 2.3 Formula................................................................................................................................................................................................... 37 2.4 Trigger Action....................................................................................................................................................................................... 37

3. Commands and Parameters .................................................................................................................................................................... 38 3.1 Commands ............................................................................................................................................................................................ 38 3.2 Parameters............................................................................................................................................................................................. 39

Software Trigger ..................................................................................................................................................................................................... 40 1. Short Description......................................................................................................................................................................................... 40 2. Detailed Description................................................................................................................................................................................... 40 3. Parameters ..................................................................................................................................................................................................... 40

GPIO Trigger ............................................................................................................................................................................................................. 41 1. Short Description......................................................................................................................................................................................... 41 2. Detailed Description................................................................................................................................................................................... 41 3. Parameters ..................................................................................................................................................................................................... 41

UART Trigger ............................................................................................................................................................................................................ 42 1. Short Description......................................................................................................................................................................................... 42 2. Detailed Description................................................................................................................................................................................... 42 3. Parameters ..................................................................................................................................................................................................... 42

Interface to Camera Peripherals........................................................................................................................................................................ 43 1. Short Description......................................................................................................................................................................................... 43 2. Detailed Description................................................................................................................................................................................... 43

2.1 Built-in LED Light Source.................................................................................................................................................................. 43 2.2 Motorized Optics and Filter Switching Unit .............................................................................................................................. 44 2.3 Diagnostics ............................................................................................................................................................................................ 44

3. Parameters ..................................................................................................................................................................................................... 44 Logging...................................................................................................................................................................................................................... 46

/58 Page 3/58 FreewayCAM Programmer’s Manual

1. Short Description......................................................................................................................................................................................... 46 2. Filtering Log Records.................................................................................................................................................................................. 46

Interface to External Illuminators ..................................................................................................................................................................... 47 1. Short description ......................................................................................................................................................................................... 47 2. Detailed description ................................................................................................................................................................................... 47 3. Parameters ..................................................................................................................................................................................................... 47

ARHIP - PC API Description ................................................................................................................................................................................. 48 1. Module Initialization and Closure.......................................................................................................................................................... 48 2. Functions of Communication (query/answer) .................................................................................................................................. 48

2.1 Establishing Connection with the Device .................................................................................................................................. 48 2.2 Disconnecting from the Device ..................................................................................................................................................... 49

3. Handling of Data Streams......................................................................................................................................................................... 49 3.1 Opening a Stream............................................................................................................................................................................... 49 3.2 Closing the Data Stream................................................................................................................................................................... 50 3.3 Querying a Frame from the Stream.............................................................................................................................................. 50 3.4 Sending a Query and Waiting for the Answer .......................................................................................................................... 50 3.5 Deleting the Answer .......................................................................................................................................................................... 52

Creating Backup File with ARHIP PCAPI ................................................................................................................................................... 53 Uploading Backup File (Update) with ARHIP PCAPI ............................................................................................................................ 54 Getting Images from the Scapture Module............................................................................................................................................ 55

Contact Information .............................................................................................................................................................................................. 58


Introduction Welcome to the Programmer's Manual of the FreewayCAM series cameras. This document is intended to provide you a complete understanding on the wide range of possibilities of integrating your FreewayCAM into your system. The FreewayCAM series of cameras are specially developed and optimized for license plate reading (ANPR) applications while offering a great deal of flexibility to suit your special needs. The two main capabilities of the FreewayCAM camera are capturing images optimized for ANPR and forwarding them via a selected protocol to your application. The special hardware features, such as for example the built-in high power pulsed-infra LED illumination, or the extended I/O capabilities backed up with software developed with device integration in mind, such as the built-in hardware motion detector, ensure that the unit should fit into your system quickly and easy. The camera is equipped with a DSP-based intelligent processing core and with large internal memory for image buffering. This core is hosting a Linux operating system and an intuitive web based control interface. Image processing in the camera is divided among modules: each module is responsible for a specific task. The camera can be configured and used by communicating with these modules. FreewayCAM communicates through HTTP requests; therefore no ARH libraries are necessary to use them. HTTP requests are supported by all popular programming environment natively. Since the FreewayCAM communicates through standard HTTP requests, installation or usage of any ARH libraries is not needed. One can use his/her development environment to construct and send the http requests to the camera.

The Camera Software The core of the camera software consists of modules that are responsible for handling different features of the device. (e.g. zooming is executed by the hwlayer/zoomcontrol module while trigger events are handled by the trigger/eventman module). Every module has a name and a group e.g. setup/network where setup is the group and network is the name and is responsible for setting up network connections of the camera. All features and functions of the camera are accessible by users through the camera software to an extent determined by their privileges.


The Camera Modules Every module of the camera is responsible for certain task(s) and has unique commands and functions. MODULE CATEGORIES, module groups and module names: [modulegroup/modulename] description:

MONITORING __________________________________________________________________________________ STAT [stat/memory] – Memory Statistics [stat/listmodules] – Module List LOGGING [logging/logstream] – Device Log Streamer

SETTING ______________________________________________________________________________________ HWLAYER [hwlayer/cphw] – CP Hardware Interface [hwlayer/cperiph] – Camera Peripherals [hwlayer/illuminator] – Interface to External Illuminators SETUP [setup/profiles] – Profile Manager [setup/users] – Set Users and Groups [setup/network] – Network Setup [setup/exit] – Shutdown/Restart Manager [setup/hwmotdet] – Hardware Motion Detection Parameter Manager [setup/time] – System/Hardware Date and Time [setup/imagepar] – Image Parameter Manager FILE [file/reader] – HTML Template Parser CONFIG [config/ledcfg] – Illuminator Configuration Manager [config/cfgman] – Configuration Manager

IMAGE ________________________________________________________________________________________ SCAPTURE [scapture/default] – Image Capture Interface MCAPTURE [mcapture/default] – Image Stream Interface CONTROL [control/focuscontrol] – Automatic Focus Control [control/zoomcontrol] – Automatic Zoom Control [control/brightnesscontrol] – Automatic Brightness Control

TRIGGER-UPLOAD ______________________________________________________________________________ TRIGGER [trigger/eventman] – Event Manager [trigger/swtrigger] – Software Trigger [trigger/uarttrigger] – UART Trigger [trigger/gpiotrigger] – GPIO Trigger [trigger/scheduler] –Scheduler Trigger UPLOAD [upload/uploadman] – Upload Manager

UPDATE-MAINTENANCE_________________________________________________________________________ UPDATE [update/default] – System Update BACKUP [backup/default] – Backup System


Modules in bold text can be accessed and managed with camera commands as described in the following chapters. Other modules are intended for internal usage.

To communicate with these modules, three methods are available: Through the web interface of the FreewayCAM camera by submitting the forms on the pages. For more

information see FreewayCAM User’s Manual.

As HTTP requests e.g. in browsers’ address bar according to syntaxes detailed below.

Through the PC API (for the C programming language) of the FreewayCAM camera (see PC API Description). The WEB interface is recommended for users, as it is very easy to use while the other methods are intended for programmers (C, C++ and HTML.) NOTE: For application development purposes, Mozilla Firefox is strongly recommended.

In the following sections of this manual, the FreewayCAM camera modules and the FreewayCAM PC API are described.


General Communication Interface You can set up and monitor the camera by using parameters. Parameters are composed of a name and a value. The value of a parameter has a type (int, string, etc.) and validity limits. Each of the modules listed in the previous chapter has a parameter list, which consists of the parameters that the given module accepts. In this chapter, we will deal with the issue of getting, setting and retrieving these parameter lists and ranges. Parameters can be read only (RO), in this case only a get operation is allowed on them, or read/write (RW), in which case both a get and a set operation is allowed. There are certain special parameters (for example commands), which are by nature write only (WO).

Setting Parameter Values Syntax: http://[camera ip]/[module group]/[module name]?[parameter name 1]=[parameter value 1]&[parameter name 2]=[parameter value 2]&... Example:

Query: http://192.0.2.3/control/zoomcontrol?zoom=32

Answer:

multipart=1 mimetype=text/html estr= eparams= zoom=32

NOTES:

1) You can set multiple properties in one query. 2) In the answer, the module may include more properties, other than those queried (see the documentation

of the modules below). 3) In general, the answer will contain the previous value of the parameter in the answer. To make sure that

the parameter value is accepted and set, query it with the get command.

Retrieving Parameter Values Syntax: http://[camera ip]/[module group]/[module name]?get[parameter name 1]&get[parameter name 2]&... Example:

Query: http://192.0.2.125/control/zoomcontrol?getzoom

Answer:

multipart=1 mimetype=text/html estr= eparams= zoom=32


Special parameters

multipart=1 – Both image and image data are transferred (multipart=0: image only) ajaxcall=1 – Query/set data are displayed on the web interface (ajaxcall=0: can be save as file) cameraapi=1 – Substitutes the multipart=1 parameter when communicating with the [setup/time]

module.

Retrieving Parameter Ranges All modules (except scapture/default, which because its large number of parameters uses a different syntax, see its documentation below) return the validity range using the following syntax: http://[camera ip]/[module group]/[module name]?query[parameter name 1]&query[parameter name 2]&... Example:

Query: http://192.0.2.125/trigger/gpiotrigger?querysamplerate_hz&queryinvert

Answer:

listsamplerate_hz=1,2,5,10,20,50,100,200,500,1000,2000,5000,10000 listinvert=0,1 mimetype=text/plain multipart=1

Answers come in two types list and bound.

Syntaxes: list[parameter name]=[valid value1],[valid value2],... bound[parameter name]=[minimum value], [maximum value], [default value, or -1 if not applicable]


Image Capturing Interface [scapture/default]

1. Introduction The scapture/default module is responsible for the basic image capturing tasks detailed below. With the help of the module, it is possible to get camera images (in JPEG format) and to set and get image capturing parameters. Images returned by the camera have a parameter list attached. In this list, each value is listed twice: with and without the 'img' prefix. The parameter value with the 'img' prefix represents the value of the parameter at the time the image was captured, while the one without it represents the actual value. Steps of Image Processing:

Image Processing Pipeline


2. Image Sensor Camera images are captured by the image sensor. This sensor can be color or B&W as described in the scolor (0=B&W, 1=color) property. Pixels are captured with 12-bit depth. The image sensor also has attributes describing the number of vertical and horizontal pixels (described in the xsize and ysize parameters). Image sensors include a boost circuit to increase the brightness of the camera image. The extent of this boost can be adjusted through the gain parameter. Note that the higher the gain value is, the noisier the images will be. To make the camera image brighter, the exposure time can also be used. This time defines the length of time during which the sensor is collecting light. It can be set in microseconds through the shutter parameter. The longer the image sensor collects light, the brighter the camera image will be. In case of high shutter values, motion blur effect may occur in case of rapid motions. The image capturing frequency of the sensor is defined in FPS (describing the number of captured Frames Per Seconds) and can be adjusted by the ifps parameter. The actual number of processed images can be adjusted with the Frame Limiter (see below). The following parameters depend on the type of the camera image sensor:

Parameters of the Camera Image Sensor

imgsize RO

The size of the image in bytes (read only). If the amount of data exceeds this value then there it is extra data included

(e.g. histogram information, etc.). In the sent data package, always the image comes first and then comes the extra data.

imgxsize RO X (width) size of the image in pixels

imgysize RO Y (height) size of the image in pixels

ifps RO

Querying the frame capturing speed of the sensor (read-only). This value depends on the camera sensor according to the followings:

752x480: 0, 60.0 = 60Hz (default), 50.0 = 50Hz 1280x960: 0, 22.5 = 22.5Hz (default), 11.25 = 11.25Hz 1600x1200: 0, 8.5 = 8.5Hz (default), 4.25 = 4.25Hz

(Flashing effect on the camera image caused by interference with camera environment light sources can be avoided by this option).

imgifps RO actual ifps value influenced by iskipframes (see below)

imgscolor RO Camera sensor color information.

0 = B&W sensor 1= Color sensor

gain RW

Gain value for image capturing. In case of sensors:

752x480: it is represented in percentage (1.0 = 100%) 1280x960 and 1600x1200: it is represented in decibels

NOTE: Adjusting gain is strongly recommended through the brightness control module.

imggain RO used gain value when the image was captured

shutter RW value of shutter in μs (fractions can also be provided)

NOTE: Adjusting shutter is strongly recommended through the brightness control module.

imgshutter RO used shutter value when the image was captured



3. Frame Limiter In many cases, the speed with which the sensor captures images is too quick for image processing or it is unnecessary to operate the system at full speed (e.g. in case of parking facilities, 10 FPS is satisfactory). In these cases, the number of captured frames should be limited with the frame filter module that is capable of dropping frames from the incoming stream of from the sensor. When adjusting the number of dropped frames, it must be specified that after processing an image, how many should the module drop (ignore). The number of dropped images may vary between 0 and 15. If 0 is set, all images are forwarded (0 is dropped) while if 15 is set, the system drops 15 images after every processed one. The number of skipped frames can be set by the iskipframes property. E.g. iskipframes=3: Before limiter 1 2 3 4 5 6 7 8 9 After limiter 1 X X X 2 X X X 3 In the first row, the incoming frame indexes are enlisted, while in the second row, indexes of forwarded images are marked with green, indexes of dropped (ignored) images are marked with red.

Parameters of Frame Management

iskipframes RO

Number of frames skipped at capturing.

0 = no skipping 1 = every second is processed 2 = every third is processed

max. 15 = every fifteenth is processed)

The ifps and iskipframes parameters refer to data received from the sensor. The two parameters together define the number of frames downloaded from the camera.

imgiskipframes RO Used iskipframes value when the image was captured.

imgframetimems RW Time of frame capturing in msecs (system time). Updating system time changes this parameter.

imgframemonotimems RW

Time of frame capturing according to a clock counting monotonically starting from the timestamp at camera startup, thus unaffected by time synchronization effects and manual time setting to ensure the order of images in time.*

imgframeindex RW Frame index of the image stored in 32 bit. It may overflow.

4. Flash Driver The flash module works with images filtered by the frame limiter. The flash control can be set to flash differently on images with odd/even frame index with the help of the flashmode property. (If the camera uses visible light for illumination, disturbing flashing (stroboscopic) effect may occur. To avoid this phenomenon, the flash1persec property can be used that defines the minimal number of flashes in one second. If there is no such phenomenon, then set this parameter to 0 to flash only at image capturing.)

* Timestamp in ms-s counted from the Unix epoch 1970.01.01 0:00:00.00 +0000 UTC

Parameters of Flashing

flashmode RW

NOTE: Setting the flash mode is strongly recommended through the camera web interface: Setup/Advanced Setup/Flash Control. The camera can be set up to flash the illuminator on even/odd frames. Adjust flashing mode according to the followings: (0=turned off, one of the bits is 1 then turned on – 0xF to make all of them available).

0. bit: emitting strobe signal to the external illuminators on odd frames 1. bit: set to 1: emitting strobe signal to the illuminator on odd frames 2. bit: emitting strobe signal to the external illuminators on even frames 3. bit: set to 1: emitting strobe signal to the illuminator on even frames 4. bit: set to 0= even/odd frame differentiation is disabled

set to 1= even/odd frame differentiation is enabled E.g. to flash all light sources continuously: enable the 0.,1.,2., and 3. bits: 11112=1510

flash1delay RW Delay of flashing on the built-in illuminator in milliseconds. This value can be

negative as well. NOTE: This value is factory preset. Do not alter.

flash1persec RW

Minimal number of flashes in one second on the built-in illuminator. It always flashes once on a strobe signal. By this parameter, the number of flashes on the

illuminator in one second can be defined (it is divided equally). If it is 0 then only one flash will occur on a strobe signal.

flash2delay RW Delay of flashing on the external illuminators in milliseconds. This value can be

negative as well. NOTE: This value is factory preset. Do not alter.

flash2persec RW

Minimal number of flashes in one second on the external illuminators. It always flashes once on a strobe signal. By this parameter, the number of flashes on the

illuminators in one second can be defined (it is divided equally). If it is 0 then only one flash will occur on a strobe signal.

5. De-Bayer This option is available only at color cameras. Most color sensors send images according to the so-called Bayer Pattern. The task of the De-Bayer module is to convert the pixels to the RGB color space. (During the conversion and further image processing tasks, calculating accuracy needed by the incoming 12bit accurate data exceeds the 24bit accuracy. To achieve better image quality, the algorithm uses weighted average calculation).

6. Color Correction Pixels, converted to RGB are exposed to further image processing which includes the following procedures:

white balance contrast saturation

With the help of the whitebalance parameter, the gain of the individual color channels can be adjusted: the red, green and blue components can be enhanced (moved to positive direction) and reduced (moved to negative direction). As a result of such adjustments, shade of the image color can be altered. With the help of the contrast and saturation parameters, the corresponding values can be adjusted. The adjustment can be negative (minimum -1.0) or positive (maximum +1.0). In case of 0, no modification is executed. A further task of the color correction module is to convert the pixels from RGB to the YUV color space. This color space is appropriate for JPEG and H264 compressions and is suitable for the motion detector.


Parameters of Color Correction

saturation RW Adjusting saturation (between -1.0 and +1.0)

This parameter is available only at color cameras.

imgsaturation RO used saturation value when the image was captured

contrast RW contrast value (between -1.0 and +1.0)

imgcontrast RO used contrast value when the image was captured

whitebalance RW values of white balance between -1.0 and +1.0 (R, G, B) e.g.

whitebalance=0.0,0.1,0.8

imgwhitebalance RO used white balance values when the image was captured

7. Gamma Correction The gamma correction enables to enhance dark pixels differently from bright ones. This kind of modification helps to render the details of dark image sections (more) visible. The characteristic of the gamma curve is described by a number between 0.2 and 6.0. Values below 1.0 result in reduction of dark sections, while values above 1.0 mean the extension of them. The value 1.0 does not have any affect on the image. The average used gamma is 1.6 while 2.2 is considered to be strong gamma correction. This value can be set by the gamma property. Camera image can be darkened or brightened with the help of the brightness parameter. This parameter equally alters dark and bright parts of the image. The value -1.0 results in the darkest image, while 1.0 results in the brightest value. The value 0.0 does not have any effect on the image. It may occur that not even the darkest pixel on the camera image is black. To solve this problem, the blacklevel property can be used. The value of this parameter may vary between 0.0 and 1.0 where 1.0 stands for 100%. Default value: 0.0. The whitest pixel on the camera image can be adjusted with the help of the whitelevel property. The value of this parameter may vary between 0.0 and 1.0 where 1.0 stands for 100%. Default value: 1.0.

Parameters of Gamma Correction

gamma RW 1.0=no correction (linear), x=correction is used (between 0.2 and 6.0) Values must be rounded to tenth (e.g. 0.2, 0.3 … 5.9, 6.0).

imggamma RO used gamma value when the image was captured

blacklevel RW Defines the lowest pixel value that stands for black. This will be the starting

point of the gamma curve. Values between 0 and 1.0 are valid. NOTE: The blacklevel value must be lower than whitelevel.

imgblacklevel RO used black level value when the image was captured

whitelevel RW Defines the highest pixel value that stands for white. This will be the end of

the gamma curve. Values between 0 and 1.0 are valid. NOTE: The blacklevel value must be lower than whitelevel.

imgwhitelevel RO used white level value when the image was captured

brightness RW Adjusting brightness (it moves the gamma curve to Y direction). Valid values are between -1.0 and +1.0 Default: 0.0

imgbrightness RO used brightness value when the image was captured


8. Mirroring and Rotation In some special cases, (e.g. when the camera is installed upside down or aimed at a mirror) mirroring the camera image vertically or horizontally or rotating it by 90 degrees to any direction may provide a solution. Note that rotation is not supported by every camera model. Most camera models support only horizontal (smirrhoriz property) and vertical (smirrvert property) mirroring and 180-degree rotation (srotate property). Note that in case of rotations by 90 and 270 degrees, the aspect ratio changes (e.g. 752x480 image turns to 480x752).

Parameters of Mirroring

smirrhoriz RO 1: horizontal mirroring is enabled 0: horizontal mirroring is disabled

smirrvert RO 1: vertical mirroring is enabled 0: vertical mirroring is disabled

srotate RO

0: image rotation is disabled 90: camera image is rotated by 90 degrees 180: camera image is rotated by 180 degrees 270: camera image is rotated by 270 degrees

9. Image Compressor The image compressor is capable of converting the pixels into JPEG images or H264 stream. Note that not every camera model supports the H264 format. In case of JPEG compression, the quality of the images can be adjusted by the jpegquality parameter between 0 and 100 where 0 results in the smallest but poorest quality image and 100 means the best quality but largest image file. The default value is 75. Since good quality images can be created with 80, providing greater ones is not recommended to avoid increased bandwidth usage and disk space consumption. NOTE: The jpegquality parameter can be adjusted through the camera web interface by the Compress Rate option according to the following formula: jpegquality=100-Compress Rate, that means 0 is the best quality/largest file combination and 100 is the smallest file/poorest quality. Most of the enlisted properties are read-only and contain information related to the captured image.

Parameters of Image Compression

Parameter name RO/RW Description

imgchannel RO

Selecting channel, see above.

0 = normal image from the sensor in high resolution (default) 1 = minified grayscale image from the motion detector module

(optionally colored), H264_I_PCM format 2 = JPEG stream 3 = H264 stream

NOTE: If not the default (0) format is used, it must be marked in every query.

imgformat RO Image format (cannot be altered at runtime- also depends on the profile). Possible values are:

0 = Automatic


1 = RAW format 2 = JPEG (in case of imgchannel 0 and 2) 3 = BMP (in case of imgchannel 1 for creating grayscale images) 4 = H264 I_PCM frame (only in special cases) in case of imgchannel 1 5 = H264 (in case of imgchannel 0 and 3)

NOTE: H264 compression is not available in every camera model.

jpegquality RW

The quality of JPEG images can be set by this parameter (a number between 0 and 100). The higher this value is, the better the quality

of the images will be. Default=75. NOTE: Images of better quality are greater in size therefore, they increase

network load. Suggested values are between 60 and 80.

imgjpegquality RO used jpeg quality value when the image was captured.

fileext RO recommended file extension (string, e.g. ‘.jpg’) – (read only) mimetype RO It returns the type of the data e.g. ‘image/jpeg’.

10. Motion Detector With the help of the built-in motion detector, the camera is capable of detecting motions in image streams based on the pixel differences between consequent frames. This motion detector can be customized for different purposes through its parameters detailed below and can be used to launch trigger events on motions. For more information on triggering, see Event Manager description. Operation A speed and a sensitivity value can be specified for the motion detector. Based on these values, a new value is calculated (imgmdbgresult) from the learnt background and the changes (imgmdxresult) between the current image. It is advisable to use the latter parameter for motion detection. A limit value can also be set, above which motion is detected in the imgmdresult parameter. Motions can be framed as well. Images containing motions are organized into sequences to which numbers (IDs) are assigned (imgmdsequence). Within sequences, the frames are also counted (imgmdseqframe). If frames with no motion are found after motion sequences, these frames are inserted into the end of the previous motion sequence. By the imgmdresult parameter, it can be decided whether was there any motion in the given sequence or was not.

Parameters of the Motion Detector

mdmode RW Turning motion detection on/off: 0 = turned off, 3 = turned on

mdspeed RW

The speed of the motion detector. Both the speed of the background image and the motion image are set by this option. Setting speed is independent from the FPS. It is compensated automatically. 0 = slow...100 = very quick. Default value: 75

mdsensitivity RW Setting the sensitivity of the motion detector. 0 = the least sensitive …100 = very sensitive Default value: 75

mdrectsens RW Setting sensitivity for defining motion detection frame. 0 = the least sensitive …100 = very sensitive Default value: 75

mdoutimg RW

The output of the motion detector (minified image).

0 = minified grayscale image 1 = output of the motion detector (0=no movements, 0xFF=largest

movement)


2 = bitmask (in which position has the motion detection been enabled)

mdreslevel RW Motion limit. The extent of pixel changes above which the detected motion is handled as motion (it is not ignored). Suggested value: 20

mddebug RW This parameter is for testing the motion detector.

0 = no debug information appears on the minified image (default) 1 = areas included in the frame are marked with blue

mdmask00

..

mdmaskFF

RW

A so-called ‘forbidding mask’ can be set for the motion detector to mark areas to be excluded from motion detection. The image is divided into 16x16 pixel blocks. For every block, a bit belongs. If an image cannot be divided by 256 then the bits in the last block do not count. Because of this e.g. in case of a 752x480 image 48x30 bit is stored instead of 47x30. If a bit is 1 that represents disabling, if 0 then it represents enabling (by default).

imgmdwin RO The motion detector defines a frame within which motion detection is executed. The coordinates of this frame are represented by this read-only parameter according to the followings: imgmdwin=x1,y1,x2,y2

imgmdbgresult RO Difference against the background. It is executed on every block and it sums the absolute values of differences. Read only parameter.

imgmdxresult RO Motion value for the entire image based on the pixel changes. It is advisable to use this parameter for motion detection. Note that this parameter is read only.

imgmdresult RO

With the help of this parameter, it can be checked if there has been any motion on the given image or has not. Note that this parameter is read only.

0 = no motion has occurred 1 = motion has occurred

imgmdsequence RO Motion detection sequences have unique IDs. This ID is a read-only 32 bit counter.

imgmdseqframe RO The number of frames within sequences is counted by this 32 bit counter and can be queried only.

If there are parts in the image in which motion should be ignored (for example traffic on another lane, on the sidewalk or just a tree on the side of the road blown by the wind), then this part should be masked out. Masks can be drawn most freely with the commands below.

Motion Detection Mask Commands

mdfillmask Filling the entire mask with the specified value. 0= disabling every mask position (no motion detection) 1= enabling all mask position (motion detection is enabled)

mddraw

Drawing a full circle on the specified position of the motion detection mask. Command format: mddraw=x,y,t,s x= X coordinate of the normal image y= Y coordinate of the normal image t= Operation to be executed: 0=erasing, 1=adding, 2=inverting s= Size of the brush: 0=1 pixel, 1=3 pixel, 2=5 pixel

mdsavemask Saving the created mask file under the current profile. mdloadmask Loading mask file from the current profile.


11. Analyzer The analyzer module provides data for sharpness adjustment and brightness control to other modules. These data consist of the followings:

Data for sharpness adjustment Data for brightness control (shutter, gain, iris)

12. Frame Buffers Captured images and image data are stored in the camera memory, in a dynamic buffer. Depending on the settings, even hundreds of images (max. 1024) can be stored in this way. User applications may get previous images based on their image index or image time. Every image has a monotonic counter called the frame index. This index is represented by the frameindex parameter. Furthermore, every image has two different timestamps. The first one is the system time (frametimems), the second one is a monotonic clock measuring in milliseconds that starts counting after turning on the camera (framemonotimems, see above). System time can be altered by setting the clock (manually or automatically e.g. through an NTP server). With the help of the getframe property, users can specify if they want to download image, image data or both. The scapture module is capable of retaining the last queried image for every connection. Because of this, it is easy to query the following (next) or the closest (by frameindex or timestamp) image (best). If the last queried image is needed, the last value must be used with the capture parameter.

Commands of Frame Management

getframe

The state of returning images. It advisable to use this option when setting/querying parameters and no image is necessary from the camera. With the help of this command, the unnecessary network load can be avoided.

0=no image is returned (only parameters and data are transferred) 1=image and data are returned (all data are transferred). Default option. 2=image is taken inside the camera but only the image parameters are

returned.

capture

Specifies a frame to be taken from the buffer. Buffering is executed by an other (hwlayer) module. The scapture gets images from this buffer.

next = returns the next available image related to the previously downloaded one

last = returns the last captured image from the buffer best = returns the most appropriate image from the buffer

(Setting one parameter among the frametimems, framemonotimems and frameindex is mandatory for this parameter. Otherwise, it takes the last from the buffer).

local = By default, it returns the image last queried by the scapture module (if there has not been such image then it returns the last one from the central buffer.

query{groupname} Querying specific boundary groups (see below).


12.1 Getting Images from the Frame Buffer

12.1.1 Operation of the Frame Buffer The buffer stores the latest captured frames. The number of these frames is variable: it depends on more factors e.g. on the size of the images.

12.1.2 Parameters of Captured Frames (Images) The scapture module returns three parameters for every captured frame: imgframeindex, imgframetimems and imgframemonotimems.

imgframeindex: After camera startup, captured frames are counted. This parameter provides the number of the frame. imgframetimems: Time elapsed since 1st January 1970 until the capturing of the frame in milliseconds. imgframemonotimems: Time elapsed since camera startup until the capturing of the frame in milliseconds. The above parameters can be used to determine the time of capturing when getting frames from the scapture module. These parameters can be displayed in browsers as a part of a parameter list according to the followings: http://192.0.2.3/scapture?multipart=1&ajaxcall=1 In case of the above query, no image is displayed. To display the image, the parameters are valid on, the multipart=1 and the ajaxcall=1 parameters must be omitted: http://192.0.2.3/scapture

12.1.3 The Capture Parameter capture=last http://192.0.2.3/scapture?capture=last It returns the last captured image. No other parameter is necessary for this query. Example to return the parameters of the last captured image: http://192.0.2.3/scapture?capture=last&multipart=1&ajaxcall=1 capture=next It returns the frame that follows the last returned (queried) one. If this frame is not in the buffer anymore, (too much time has elapsed and it has been rewritten by newer images), it returns the oldest image from the buffer. The capture=next can be used by itself or together with the framemonotimems, imgframetimems and frameindex parameters: In these cases, frames, following the specified number/timestamp are returned (if they are still in the buffer): Examples: capture=next&framemonotimems=98741855 capture=next&imgframetimems=1337679820180 capture=next&frameindex=8390


capture=best It returns the frame that is closest (before or after) to the specified timestamp or frame index. If the buffer does not contain such a frame, the oldest one is returned. If the specified timestamp (framemonotimems, imgframetimems) or frameindex value is too high (refers to a yet non-existing frame) then the newest frame from the buffer is returned. Examples: capture=best&framemonotimems=106964188 capture=best&imgframetimems=1337695009069 capture=best&frameindex=193390 For more information on handling the above parameters through the ARHIP PCAPI, see PCAPI description.

13. Properties By default, the system does not return all the properties together with images. If we need to query the remaining properties, then the get prefix must be used before the name of the property. Validity limits of properties can be queried with the query prefix.

get{propertyname}=1 Getting the value of the property

query{groupname}=1 Querying specific boundary groups or possible value(s) seen below. In case of returning boundaries, the returned values are as follows: [min. value], [max. value], [default value]

Queryable parameters and groups

Groupname Returned value Sample value boundimgchannel 0,1,0

listimgformat 0

listfileext jpg modefmt

listcapture next,last,best,local

boundimgframetimems 0,18446744073709551615,0

boundimgframemonotimems 0,18446744073709551615,0 frame

boundimgframeindex 0,4294967295,0

boundimgsize 0,4294967295,0

listimgxsize 752 imgsize

listimgysize 480

listifps 60.0,50.0 capfps

boundiskipframes 0,15,0

listgetframe 0,1 data

listgetmcount 0,1

param boundgain 0.25,4.0,1.0


boundshutter 25,60000,10

boundgamma 0.2,6.0,1.0

boundbrightness -1.0,1.0,0.0

boundsaturation -1.0,1.0,0.0

boundcontrast -1.0,1.0,0.0

boundjpegquality 0,100,80

boundwhitebalance -1.0,1.0,0.0

boundcmatrix -127.0,127.0,0.0

boundcyuvadd -127.0,127.0,0.0

boundblacklevel 0.0,1.0,0.0

paramadv

boundwhitelevel 0.0,1.0,1.0

boundflashmode 0,31,31

boundflash1delay -1000.0,1000.0,0.0

boundflash1persec 0,200,0

boundflash2delay -1000.0,1000.0,0.0

flash

boundflash2persec 0,200,0

boundgpifreq 1,250000,25 gpi

boundgpidebounce 1,255,5

mdmode 1,3,3

boundmdspeed 0,100,75

boundmdsensitivity 0,100,75

boundmdrectsens 0,100,75

boundmdoutimg 0,3,1

boundmddebug 0,1,0

md

boundmdreslevel 0,255,50

listsmirrhoriz 0,1,0

listsmirrvert 0,1,0 smirrot

listsrotate 0,180,0

Example:

Query: http://192.0.2.180/scapture/default?querydata=1

Answer:

… listgetframe=0,1 listgetmcount=0,1 …

It is necessary to make a single connection capable of querying an image and its data in two separate queries. In this case, the web server has to assign the opened channels to the HTTP session.



System Hardware Date and Time [setup/time]

1. Introduction With the help of this module, formatted time and date values can be queried from the camera. NOTE: When communicating with the setup/time module, the cameraapi=1 parameter must be used instead of the multipart=1.

2. Retrieving Time Parameters Sample URL request: http://192.0.2.3/setup/time?multipart=1&ajaxcall=1&cameraapi=1&g_ftime=$a, $d $h $Y $T GMT $Q Sample answer to the URL request: Fri, 12 Jul 2002 15:22:10 GMT 529 a_localtimems=1026480130051 a_monotimems=49108 a_tzcode=400#CET-1CEST,M3.5.0,M10.5.0/3 a_year=2002 a_month=7 a_day=12 a_hour=15 a_min=22 a_sec=10 a_ntp=0 a_ntpip= multipart=1 mimetype=text/html where the first line is the formatted time (specified with $a, $d $h $Y $T GMT $Q) and the rest of the values are always returned by the module. These values contain the following information (separated by enter-s): a_localtimems: local timestamp in milliseconds counted from the Epoch: 1970-01-01 00:00:00 +0000 UTC. a_monotimems: Time elapsed since camera startup in milliseconds. a_tzcode: code of the local time zone a_year: year of local time a_month: month of local time a_day: day of local time a_hour: hour of local time a_min: minute of local time a_sec: second of local time a_ntp: returns whether NTP synchronization is turned on or not. a_ntpip: IP address of the NTP server In order to configure the content and structure of the returned time information (first line of the answer), the following arguments† can be used:

† Arguments are the same as the strftime function’s usable in C++ except the Q.

2.1 Querying Custom Time Information Argument Description

%a The abbreviated weekday name according to the current locale. %A The full weekday name according to the current locale. %b The abbreviated month name according to the current locale. %B The full month name according to the current locale. %c The preferred date and time representation for the current locale. %C The century number (year/100) as a 2-digit integer. %d The day of the month as a decimal number (range 01 to 31). %D Equivalent to %m/%d/%y. %e Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space. %E Modifier: use alternative format, see below. %F Equivalent to %Y-%m-%d (the ISO 8601 date format).

%G The ISO 8601 week-based year with century as a decimal number. The 4-digit year corresponding to the ISO

week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.

%g Like %G, but without century, that is, with a 2-digit year (00-99). %h Equivalent to %b. %H The hour as a decimal number using a 24-hour clock (range 00 to 23). %I The hour as a decimal number using a 12-hour clock (range 01 to 12). %j The day of the year as a decimal number (range 001 to 366).

%k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)

%l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)

%m The month as a decimal number (range 01 to 12). %M The minute as a decimal number (range 00 to 59). %n A newline character. %O Modifier: use alternative format, see below.

%p Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".

%P Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale. %Q millisecond part of the current time (3 digits) %r The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p. %R The time in 24-hour notation (%H:%M). For a version including the seconds, see %T below. %s The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). %S The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.) %t A tab character. %T The time in 24-hour notation (%H:%M:%S). %u The day of the week as a decimal, range 1 to 7, Monday is 1. See also %w.

%U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.

%V The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W.

%w The day of the week as a decimal, range 0 to 6, Sunday is 0. See also %u.

%W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.

%x The preferred date representation for the current locale without the time. %X The preferred time representation for the current locale without the date. %y The year as a decimal number without a century (range 00 to 99). %Y The year as a decimal number including the century. %z The +hhmm or -hhmm numeric time zone (that is, the hour and minute offset from UTC). %Z The time zone or name or abbreviation. %+ The date and time in date(1) format. %% A literal '%' character.


Automatic Zoom Control [control/zoomcontrol]

Zoom adjustment is possible in two ways:

manually by automatic zoom –Zoom From Geometry (ZFG) mode–

1. Manual Method Select the manual method by setting the mode parameter to ‘0’. After that, the following parameters can be used to adjust the zoom.

Parameter name Mandatory RO/RW Valid values Description

mode yes RW 0: manual zoom

1: automatic (ZFG) mode of zooming

zoom no RW [zoom_min..zoom_max]

integer to zoom to a

specified position

zoom_min no RO integer to query the minimal zoom position of the

camera

zoom_max no RO integer

to query the maximal zoom position of the

camera

zoom_pc no RW [0..100] value of zoom in percentage

NOTE: Minimum, maximum and default values of zoom and zoom_pc can be queried by queryzoom and queryzoom_pc. Values are returned as: {minimum value}, {maximum value}, {default value}. Sample query: http://192.168.2.235/control/zoomcontrol?queryzoom&ajaxcall=1 Sample answer: boundzoom=0,90,-1 (-1 refers to a non-existing value).

2. Automatic Method In automatic mode, the camera calculates the best zoom position (so that the pixel size of the license plate will correspond to the set char_pxl value) based on the ZFG parameters provided by the user (certain requirements and constraints can be specified as well). Moreover, the camera is capable of setting the appropriate LED power and flashing time as well, for the above set parameters. Requirements of automatic zoom

set the mode parameter to ‘1’ provide all of the following parameters:


2.1 Mandatory Parameters for Automatic (ZFG) Zooming

Parameter name Mandatory Parameter title RO/RW Description

cam_d_mm only for ZFG Camera offset (mm) RW horizontal offset between the centre of the number plate and the camera

cam_h_mm only for ZFG Camera height (mm) RW distance between the ground and

the camera

char_mm only for ZFG Character height (mm) RW physical character height in

millimeters

char_pxl only for ZFG Character height (pixel) RW desired character height in pixels

plate_d_mm only for ZFG Plate distance (mm) RW distance between the camera and

the number plate measured according to the figure below

plate_w_mm only for ZFG Plate width (mm) RW width of the number plate in

millimeters

plate_h_mm only for ZFG Plate height (mm) RW height of the number plate in millimeters

plate_h0_mm only for ZFG Plate elevation (mm) RW distance between the ground and the centre of the number plate

NOTE: Legal values of the above parameters depend on the ANPR environment. Combinations, which describe physically impossible parameters, are rejected.

Visual interpretation of ZFG parameters

After setting the ZFG parameters, the camera adopts the best zoom value and calculates additional information can be queried by the user. These read-only parameters provide useful information for camera installment and operation:


Read-only post ZFG information parameters


best_zoom RO best zoom position

f_mm RO best focal length

hfov_deg RO horizontal field-of-view (in degrees)

vfov_deg RO vertical field-of-view (in degrees)

pan_deg RO camera pan angle (see below)

tilt_deg RO camera tilt angle (see below)

roi_left

roi_right

roi_top

roi_bottom

RO These parameters represent the coordinates of the number plate

bounding box. For more information see chapter Automatic Focus Control.

led_time RO suggested LED flashing time, μs

led_level RO suggested LED voltage level, index

estr RO error description (if there is any)

eparam RO list of invalid parameters (if there is any)

Camera pan and tilt angles

3. Parameter Sets

The default parameter set is updated after a complete and valid request has sent to the module. If a parameter set is invalid, the module sends back detailed description of the error and the list of the invalid parameter names. If a parameter set is incomplete, the module sends back the default parameter set.

4. Errors In case of invalid parameters, the detailed description of the error is sent back in the ‘estr’ parameter and the names of the invalid parameters are listed in "eparam". These special parameters (estr and eparams) cannot be queried directly.



Automatic Focus Control [control/focuscontrol]

Focus adjustment of the camera image can be executed in two ways: manually and automatically (by autofocus).

1. Manual Method Select the manual method by setting the mode parameter to ‘0’ then set the focus manually by the focus parameter within the boundaries of focus_min and focus_max values.

2. Autofocus When using autofocus, focusing is controlled entirely by the module (no manual adjustments are possible). After auto focusing, the module switches back to manual mode (in case of both a successful and an unsuccessful focusing). Progress of autofocus can be queried anytime through the progress parameter.

2.1 The ROI (Region of Interest) Box The Automatic Focus Control (AFC) module is able to focus in a region of the image called ROI (Region of Interest) box. This region can be the rectangle returned by the ZFG process. However, the position of this box can specified manually with the help of the following parameters:


roi_left** RW distance of the left side of the ROI box from the top left corner of the camera image in pixels

roi_right** RW distance of the right side of the ROI box from the top left corner of the camera image in pixels*

roi_top** RW distance of the upper side of the ROI box from the top left corner of the camera image in pixels*

roi_bottom** RW distance of the lower side of the ROI box from the top left corner of the camera image in pixels*

** Camera model (optics and sensor) dependent properties.

NOTE: Using the same ROI coordinates at zoom and focus is recommended.

NOTE: The coordinates of the ROI must be set according to the resolution of the camera. E.g. 752x480.

3. Brightness and Autofocus Criteria of successful auto-focusing:

the brightness must be set to reach optimal contrast the camera must be targeted to capture stable images containing fine details in the ROI (edges, textures)

The auto-focusing algorithm waits for stable brightness while the autobrightness function is running on the camera. During this waiting process, the automatic focus control is in paused mode (mode=2). As soon as the brightness is stable, the module switches back to auto mode and starts the auto-focusing process.

Values are rounded to 16 multiples.

4. Parameters Parameter name RO/RW Valid values Description

mode RW [0,1,2]

mode of focusing 0: manual 1: auto 2: paused (can not be activated

by users but the system only) focus RW [focus_min..focus_max] focus position

focus_min** R minimal focus position

focus_max** R maximal focus position

progress R [1..100] progress of the autofocus

represented in percentage

focus_pc RW [0..100] focus position in percentage

** Camera model (optics) dependent properties.

NOTE: Minimum, maximum and default values of focus and fous_pc can be queried by queryfocus and queryfocus_pc. Values are returned as: {minimum value}, {maximum value}, {default value}.

Sample query: http://192.168.2.235/control/focuscontrol?queryfocus&ajaxcall=1 Sample answer: boundfocus=0,90,-1 (-1 refers to a non-existing value).

5. Focus correction

The focus correction can be done either manually or automatically by the followings: Turning on the automatic solution:

IP/hwlayer/extopt?ircorr=1&ajaxcall=1 IP/hwlayer/extopt?save&ajaxcall=1

Using the manual solution: 1.) set the focus during daylight (with IR cut filter) 2.) take a note about the correct focus value 3.) set the focus during nighttime with all pass filter and take a note about that value too 4.) calculate the difference between the above values (positive number) 5.) set the correction value with the following commands:

IP/hwlayer/extopt?ircorr=-1&mdf=focus_difference&ajaxcall=1 IP/hwlayer/extopt?save&ajaxcall=1

The correction can be turned off with the following commands: IP/hwlayer/extopt?ircorr=0&ajaxcall=1 IP/hwlayer/extopt?save&ajaxcall=1

You can query the current correction settings by the following command: IP/hwlayer/extopt?getircorr&getmdf&ajaxcall=1

5. Errors In case of invalid parameters, the detailed description of the error is sent back in the ‘estr’ parameter and the names of the invalid parameters are listed in ‘eparam’. These special parameters (estr and eparams) cannot be queried directly.


Automatic Brightness Control [control/brightnesscontrol]

Brightness adjustment of the camera image can be executed in two ways: manually and automatically (with the help of strategies).

1. Manual Mode In manual mode (mode=0), the gain, shutter and iris can be adjusted separately between the boundaries returned by the module. Values are represented according to the followings:

gain - in percentage or decibel, depending on the camera model shutter - in microseconds iris - position iris_pc - in percentage

NOTE: Although, gain and shutter adjustment can also be executed through the scapture/default module, setting

these values is strongly recommended through the Brightness module.

2. BrightNow! Use the BrightNow! function for single, quick and simple adjustments. Send mode=3 and a target value (see below) to the brightness module then the function executes a quick but less accurate adjustment which will end in couple of steps (this mode will not engage again until started manually). After this, the previously set mode is activated.

NOTE: Always send the target first, or together with the mode in order the avoid malfunction.

3. Automatic Mode For automatic brightness adjustment, the following strategies are available:

Overview strategy (for overview camera purposes), mode=1 ANPR strategy (for ANPR purposes), mode=2 Quick strategy (for quick adjustment), mode=4

Common features of strategies All the three strategies receive brightness target value from the user between -100 and 100. When a target value is set, the strategies set shutter, iris and gain automatically to reach and to maintain this value – executing continuous adjustment on brightness changes. This value can be adjusted according to the figure below and is used mutually by the strategies –so it is sufficient to provide it for one.

For all strategies, the boundaries and step values can be set for gain, shutter and iris respectively. Day and night configuration settings can also be provided for each strategy containing the previously mentioned boundaries and steps. The strategies switch between day and night modes automatically with the help of the camera light sensor. Both the actual value of the light sensor and the current strategy can be queried from the module (0 stands for day mode, 1 for night mode). Note that currentset cannot be queried if the brightness control mode is manual. Boundaries (minimal and maximal values) and current values can be queried anytime regardless the controlling mode.


/58 Page 30/58


4. Module Parameters

Name RO/RW Valid values Description

mode RW [0,1,2,3,4] controlling strategy

gain RW [gain_min..gain_max] value of gain in percentage

gain_min1 RO minimal value of gain in percentage

gain_max1 RO minimal value of gain in percentage

shutter RW [shutter_min..shutter_max] value of shutter in μsecs

shutter_min1 RO minimal value of shutter in μsecs

shutter_max1 RO maximal value of shutter in μsecs

iris RW [iris_min..iris_max] iris position

iris_pc RW [0..100] iris value in percentage

iris_min1 RO minimal iris value

iris_max1 RO maximal iris value

target RW [-100..+100] integer target brightness value for strategies to set and maintain

current_set RW [0,1] day (0) or night (1) configuration (only if autobrightness is on)

light_sensor RO value of the light sensor

state RO [0,1,2]

State of the brightness controller. 1: stable (target is reached) 2: working (to reach the target) 3: unreachable (the target can not be reached

with the current light conditions)

histogram RO

256 pcs. of comma separated integers between 0 and 255

where X stands for the highest pixel intensity appearing on

the screen

returns histogram values in numeric format: 0.-255. values represent the cardinality of the given grayscale pixel intensity normalized to 100. 256. value represents the average pixel intensity.

1 Camera model (optics) dependent properties, query these parameters to get their values.

NOTE: Minimum, maximum and default values of iris, shutter and gain can be queried by queryiris, queryiris_pc, queryshutter and querygain. Values are returned as: {minimum value}, {maximum value}, {default value}. Sample query: http://192.168.2.235/control/brightnesscontrol?queryiris&ajaxcall=1 Sample answer: boundiris=0,47,-1 (where -1 refers to a non-existing value).

5. Operation of Strategies

NOTE: It may take seconds to minutes for the current strategy to settle depending on its settings.

5.1 ANPR and Overview Strategies The overview strategy prioritizes gain over shutter and shutter over iris. That means it prefers adjusting gain (if possible) to shutter and prefers adjusting shutter to iris within their boundaries. The ANPR strategy uses a special function and a further controller method to provide appropriate image for license plate recognition – it never lets the image burn out. The overview strategy does not have this protection – the image of the observed area may burn out to maintain visibility in the entire image.

5.2 The Quick Strategy With the help of the quick brightness adjuster method, appropriate brightness can be reached quickly but less accurately. Adjustments are applied according to the above-mentioned priority. When the target level is approached as close as a defined limit value, the adjustment stops until lighting conditions change. If the target level cannot be reached with given number of steps, the quick adjusting method gives up. It chooses between day and night configurations at startup and does not query the light sensor after all (to increase speed). It uses the selected configuration until finished.

6. Errors In case of an inappropriate parameter sending, the description of the error will be in the ‘estr’ answer parameter. These special answer parameters (estr and eparams) cannot be queried directly.

Illuminator Configuration Manager [config/ledcfg]

With the help of the Illuminator Configuration Manager, default flash settings can be customized for the different brightness modes and strategies on the built-in illuminator unit according to the followings: SETTING: http://{IP address}/config/ledcfg?{strategy}_{mode}_led_pcdose={value} E.g. http://192.0.2.170/config/ledcfg?overview_night_ledpcdose=45 As a result of the above command, the built-in illuminator flashes with 45 pc_dose value when the mode is night and the strategy is overview. QUERY: http://{IP address}/config/ledcfg?get{strategy}_{mode}

Possible parameter values

Strategy Mode led_pcdose

[anpr, overview, quick, manual] [day, night] [0..100]

NOTE: Values will be applied after saving settings and quick restart of the camera.

/58

Page 31/58 Page 31/58

Page 31/58 FreewayCAM Programmer’s Manual

Scheduler Trigger [trigger/scheduler]

1. Introduction With the help of this module, it is possible to schedule trigger events. On these events, certain tasks can be executed (e.g. uploading files to an FTP server).

2. Basic Parameters Name Mandatory Values Description

wday yes

[mon,tue,...,sat,sun][day_1-day_2] [mon;tue;...]

[every]

on which day(s) of the week should the timer be active example: wday=tue where day_1 < day_2: wday=tue-sat example: wday=wed;sun example: wday=every

day yes

[1-31] [1;2;...] [every]

on which day(s) of the month should the timer be active example: day=23-31 example: day=1;3;31 example: day=every

hour yes

[0-23] [0;1;2;...]

[every]

in which hour(s) of the day should the timer be active example: hour=8 example: hour=0;5;10 example: hour=every

min yes

[0-59] [0;1;2;...]

[every]

in which minute(s) of the hour should the timer be active example: min=1 example: min=15;23;42 example: min=every

sec yes

[0-59]

[0;1;2;...] [every]

in which second(s) should the timer be active example: min=1 example: min=15;23;42 example: min=every

output yes [0-(noutputs-1)] example: output=1 noutput no [uint] returns the number of scheduler outputs

drive yes [level,edge] Edge controlled or level controlled timer. level: level controlled (see below) edge: edge controlled (see below)

enabled no [true,false] Enabling or disabling a scheduler trigger Query example: http://192.0.2.45/trigger/scheduler?output=0&gethour Example for setting: http://192.0.2.45/trigger/scheduler?cmd=init&output=0&enabled=true&drive=edge&wday=mon-fri&day=1-31&hour=8-20&min=every&sec=every NOTE: Accepted parameters are saved to the configuration file and will be applied at the next startup.

/58

Page 32/58 Page 32/58


2.1 Information Commands

Command Name

Format Example Description

returns already set

timer parameters

getparams {ip_address}/trigger/scheduler?

getparams&output=1

http://192.0.2.33/trigger/

scheduler?output=1&getparams

3. Level and Edge Control Drive of trigger signals can be edge controlled or level controlled.

3.1 Edge controlled trigger signals last for a very short time instant (startms = endms).

3.2 Level controlled trigger signals on the other hand are always last for a period according to the followings:

23:12:59.999

If sec!=0-59

23:12:12.000 23:12:12.999

If sec=0-59 and min=0-59

23:59:59.99923:00:00.000

If sec=0-59 and min!=0-59

23:12:00.000

So, if the timer uses level control then:

if not every second is active (If sec!=0-59) then startms = start of the second, endms = 999 msecs later

if every second and every minute is active (If sec=0-59 and min=0-59 ) then startms is the first msec of the hour while endms is the last msec of the hour

if every second is active (If sec=0-59 and min!=0-59) then startms is the first msec of the minute while endms is the last msec of the minute

4. Errors In case of invalid parameters, the module returns the following:

estr=Invalid parameter eparams= {invalid parameters separated by colons}

/58

Page 33/58 Page 33/58


Upload Manager [upload/uploadman]

1. Introduction With the help of the upload/uploadman module, a protocol can be selected (FTP, SMTP or HTTP POST) via which image, image data (sent by the Event Manager) and trigger information will be forwarded from the camera. For sending trigger information, see Event Manager Description. Names of uploaded files can be specified in the filenametemplate parameter, image data is uploaded in text files of the following form: filenametemplate.params.txt

2. Parameters General Parameters (for every protocol)

Name Mandatory Values Description cmd yes [init] initializing protocol

method yes [ftp,smtp,post] selecting protocol e.g. method=ftp

currentmethod no [0,1,2]

returns the actual protocol: 0: FTP 1: SMTP 2: HTTP POST

data no

[0,1,2] 0: image + event data

1: image 2: data

type of data to be sent; if not set then both image and image data are

uploaded (data=0)

Parameters for the HTTP POST Protocol

Name Mandatory Values Description url yes [text] web server address

filenametemplate yes [$y,$r,$o,$d,$h,$m,$s,$l,$t,text] $y: year (4 characters) $r: year (2 characters) $o: month $d: day $h: hour $m: minute $s: second $l: millisecond $t: frametimems $i: motion sequence ID (hexadecimal number) $x: frame index within a sequence (hexadecimal number) text: string

definition of arguments

Filename template example: filenametemplate=$y-$o_$d-text-$d$m-text-$s-$l.JPEG Results in e.g. 2011-01_01-text-0113-text-12-123.JPEG Example: specifying parameters for HTTP POST protocol cmd=init&method=post&url=testserver/index.php&filenametemplate==$y/$o_$d/text-$d$m-text-$s-$l.JPEG&data=1

/58

Page 34/58 Page 34/58


NOTES: it is not mandatory to use all of the arguments it is possible to use an argument at more places in the same command it is advisable to specify the extension of the file (as text)

Parameters for the FTP Protocol

Name Mandatory Values Description url yes [text] FTP server address

username no [text] FTP account username password no [text] FTP account password

filenametemplate yes [text] see above

Example:

cmd=init&method=ftp&url=testserver&username=testuser&password=testpassword&filenametemplate=$y/$o_$d/text-$d$m-text-$s-$l.JPEG&data=0 NOTE: Setting the username and password are not mandatory. User name and password is stored in the camera unencrypted.

Parameters for the SMTP Protocol

Name Mandatory Values Description url yes [text] SMTP server address

username no [text] SMTP account username password no [text] SMTP account password

filenametemplate yes [$y,$r,$o,$d,$h,$m,$s,$l,$t,text] see above from no [email address] sender of the e-mail to yes [email1,email2,...] recipient(s) of the e-mail

Example: cmd=init&method=smtp&url=testserver&username=testuser&password=testpassword&filenametem late=$y/$o_$d/text-$d$m-text-$s-$l.JPEG &from=sender@testserver&to=recipient@testserver2&data=2 NOTE: Setting the username and password are not mandatory. User name and password is stored in the camera unencrypted.

/58

Page 35/58 Page 35/58


Information Commands (to query previously set parameters)

Name Mandatory Values Description

getftpparams no -

The set FTP parameters. Returned values: url= filenametemplate= username= password= curltimeoutms= data= currentmethod=

getsmtpparams no -

Returns SMTP parameters. Returned values: url= filenametemplate= from= to= curltimeoutms= data= currentmethod=

getpostparams no -

returns HTTP POST parameters: url= filenametemplate= data= currentmethod=

returns logging data in the dataset section of the answer

cmd no [getlog]

Query example: http://192.0.2.11/upload/uploadman?getftpparams

3. Processing Logging Data A record of the log file is built-up as follows: upload1_var_1,upload1_var_2,upload1_var_3,upload1_var_4,upload1_var_5; Fields are separated by commas while records are separated by semicolons. Sample record:

0,02/02-01-25-25-972.JPEG,0,0,No error;0,02/02-01-25-45-175.JPEG,0,0,No error;

Description of variables: var_1 : upload method [0,1,2,3] <=> [ftp,smtp,http post,invalid] var_2 : filename var_3 : type of uploaded data [0,1,2] <=> [image+data,image,data var_4 : success of uploading [0,1,2] <=> [OK,failed,image ok + data failed] var_5 : error string [No error, or error message]

4. Errors In case of invalid parameters, the module returns the followings:

estr=invalid parameter eparams= invalid parameters separated by colons

/58

Page 36/58 Page 36/58


Event Manager [trigger/eventman]

1. Short Description The Event Manager monitors the state of multiple trigger sources (such as Hardware Motion Detector or GPIO input), evaluates a user defined logical conjunction between these trigger source states and –depending on the result of this evaluation – initiates the uploading of a sequence of images. The Event Manager also implements image and trigger buffering, thus it offers greater flexibility with trigger timing.

2. Detailed Description

2.1 Trigger Inputs and Master Output The Event Manager can be imagined as a combinatorial logic network with multiple inputs and a single output. The inputs and the output may be either asserted or not asserted. The output becomes asserted if the inputs are asserted in such a combination, that the user defined logic expression (formula, see below) evaluates to 'true'. The inputs are labeled with capital letters from A to U (V-Z are reserved).

2.2 Registering The inputs can be assigned to various trigger sources. This process is called registering. If a trigger source has multiple outputs, it can be assigned to different inputs of the Event Manager.

2.3 Formula The trigger control formula of the Event Manager can be defined by using the capital letters and the logic symbols defined below. The shorthands 'each' for AND-ing all the inputs, or 'any' for OR-ing all the inputs can be used. The following logic symbols can be used: - & (web interface) or * (URL) for AND - | (web interface) or + (URL) for OR - ! for NOT - ( and ) for bracketing Valid formulas are for example: - A&B&C (Web interface) - (A+B)*C (URL) - A - A&!B (Web interface) NOTE: Spaces are not allowed in formulas.

2.4 Trigger Action There is a process within the Event Manager, which monitors the Master Output, and acts while it is asserted. This action is forwarding the images to the Upload Manager, which in turn will handle uploading of these images according to its current setup.

/58

Page 37/58 Page 37/58


3. Commands and Parameters The event manager can be configured wit the help of the commands below. Structure of a command:

cmd=[command]&[param1=value1]&...&[paramN=valueN]

3.1 Commands

Command Format Example Description

register cmd=register&module_name=

[Module name]&output=[Output index]&input=[Input index]

cmd=register&module_name= trigger/swtrigger

&output=0&input=D

registers the module's given output to the

given input unregisters the

module registered at the given input

freeinput cmd=freeinput&input=[Input index]

cmd=freeinput&input=D

sets the logic expression the Event Manager evaluates

setformula cmd=setformula&formula=[Logic expression]

cmd=setformula&formula= (D+A)*B

start cmd=start cmd=start starts the Trigger

Action process of the Event Manager

stop cmd=stop cmd=stop stops the Trigger

Action process of the Event Manager

reset cmd=reset cmd=reset resets the Event Manager

getconfig cmd=getconfig cmd=getconfig

returns the current configuration of the Event Manager. The

answer is a semicolon-separated list of entries

in the format of [Module

name]/[Output index]: [Input index]

getformula cmd=getformula cmd=getformula returns the current

formula of the Event Manager

getsources cmd=getsources cmd=getsources returns all available trigger sources

/58

Page 38/58 Page 38/58


3.2 Parameters Parameter name Mandatory Values Description

send_trginfo no [0,1] 0: trigger information is included 1: trigger information is not included

If send_trginfo is set to 1 then a .trg file is uploaded together with images, data or both. This file includes the following information:

Trigger Information

output output of the trigger source Note that different outputs of the same source are marked with different frame indexes.

startms trigger start time endms trigger end time index trigger index (images of a trigger have the same index)

upload_type type of the upload cmd task to be executed on the trigger

fileext extension of the trigger information file source source (sender) of the trigger event

Information provided by trigger information is intended to determine that which images belong to the same trigger (with the help of the index).

/58

Page 39/58 Page 39/58


Software Trigger [trigger/swtrigger]

1. Short Description The Software Trigger module serves as a user-triggerable trigger source.

2. Detailed Description A trigger signal can be sent to the Event Manager (see above) from user applications or from the web interface using this module.

3. Parameters The software trigger module has the following parameters:

Name RO/RW Mandatory Legal values Description

noutputs RO no [uint] returns the maximum number of software trigger

outputs

cmd W yes [sendtrigger] sends a trigger to the Event Manager, use with the parameters that follow

trigger_data RW no [string]

max 256 bytes

trigger data included in the image parameters (.par file); BASE64 encoded, URL pre-coded characters

remain e.g. ‘ ” ’ → '%22' Suitable for logging serial port information e.g.

radar data. startms* W no [timestamp] trigger start timestamp endms* W no [timestamp] trigger end timestamp

the value to be added to the trigger start timestamp

prems RW no [-1000-1000]

the value to be added to the trigger end timestamp

postms RW no [-1000-1000]

output RW yes [0-(noutputs-1)] specifies the selected output *If not specified, the actual system time is used. Example: http://192.0.2.20/trigger/swtrigger?cmd=sendtrigger&output=0&startms= 1336744931805&endms=1336744931905&trigger_data=[NTIuMTsxMzM2Ow0K] Trigger data –containing multiple traffic sensor information– explanation: Encoded: 'NTIuMTsxMzM2Ow0K' (0x35 0x32 0x2E 0x31 0x3B 0x31 0x33 0x33 0x36 0x3B 0xD 0xA) Decoded 12 bytes: '52.1;1336;' where: speed: 52.1 km/h vehicle length (time of crossing the radar beam): 1336 ms NOTE: To provide vehicle height and weight information, special external devices are (sensors) necessary.

/58

Page 40/58 Page 40/58


GPIO Trigger [trigger/gpiotrigger]

1. Short Description The GPIO Trigger module provides user access to the GPIO facility of the device, and serves as a trigger source.

2. Detailed Description Users can access the General Purpose In and Outputs (GPIO) of the device through the GPIO Trigger Module. Users can set the GP output and get the GP input of the device by issuing an HTTP command. This module also serves as a trigger source relaying trigger signals from the GP input to the Event Manager. The duration of the relayed trigger signal can be extended by the module by adding a predefined value to the timestamps of the trigger signal received on the input.

3. Parameters The trigger/gpiotrigger module has the following parameters: NOTE: When querying parameters, the output must be defined. Otherwise, data of the 0 output are returned.

Name RO/RW Mandatory Legal values Description output RW yes [0-(noutputs-1)] specifies the output; If not defined, 0 is used

noutputs RO no uint Get the number of outputs (of the trigger source).

setoutput RW no [0,1] Set the GP Output of the device to the value.

prems RW no [-1000-1000] the value to be added to the trigger start timestamp

postms RW no [-1000-1000] the value to be added to the trigger end timestamp

the sample rate with which the GP input is sampled*

samplerate_hz RW no [1-1000]

edge RW no [0,1,2]

Drive of the trigger signal. For more information see Scheduler.

0: level 1: rising 2: falling

invert RW no [0,1] the logic level of the input can be inverted (0 - active high, 1 - active low).

input RO no [0,1,-1]

the current status of the GP input can be queried by this parameter:

0: no signal 1: active level

-1: invalid value

NOTE: The default value is -1 (until the first signal arrives).

*Use the lowest possible sample rate to avoid bouncing of the input.

/58

Page 41/58 Page 41/58


UART Trigger [trigger/uarttrigger]

1. Short Description UART Trigger monitors the user UART of the device for trigger signals and relays these to the Event Manager.

2. Detailed Description UART Trigger monitors the user UART of the device for arriving data, and if these correspond to a user specified byte sequence, then sends a trigger signal to the Event Manager. The duration of the relayed trigger signal can be extended by the module by adding a predefined value to the timestamps of the trigger signal received on the UART.

3. Parameters The UART Trigger module has the following parameters:

Name RO/RW Mandatory Legal values Description output RW yes [0-(noutputs-1)] specifies the output

get the number of outputs (of the trigger source)

noutputs RO no uint

the value to be added to the trigger start timestamp

prems RW no [-1000-1000]

the value to be added to the trigger end timestamp

postms RW no [-1000-1000]

edge RW no [0,1,2]

Drive of the trigger signal. For more information see Scheduler.

0: level 1: rising 2: falling

baudrate RW no [1200,2400,...,115200] UART Baud rate (standard values) bytesize RW no [8,9,...] UART byte size parity RW no [0,1] UART parity (1 - use, 0 - do not use)

stopbits RW no [1,2] UART number of stop bits

starttoken RW no [0x00-0xFF,0x100] trigger start byte value (256 means the first byte is the start byte regardless the byte value)

endtoken RW no [0x00-0xFF] trigger end byte

/58

Page 42/58 Page 42/58


Interface to Camera Peripherals [hwlayer/cperiph]

1. Short Description This module provides access to some of the camera peripherals, such as the built-in LED light source, diagnostic values (temperature, light sensor, etc.), direct access and calibration of the motorized optics, etc.

2. Detailed Description The module provides access to the following groups of peripherals, which are detailed below:

Built-in LED light source Motorized optics and filter switching unit Diagnostics

2.1 Built-in LED Light Source The intensity of the built-in light source of the camera can be set and queried by two methods. The first is to enter a 0-100 % value using the parameter led_pcdose, which changes the light output accordingly. 2.1.1 Advanced LED Control For more control, the amplitude of the flash can be set with ledpwr to:

0 - low 1 - medium 2 - high

and set the flash time in microseconds using the parameter ledtimeus. NOTES:

It is not recommended to set higher pulse width than the length of the shutter, because this will not make the image any brighter.

In case of too high LED powers with too long pulse width and too high frame rate, the camera will protect the LEDs by disabling them for a couple of frames.

Safe Voltage/FPS Limits

Voltage FPS

Low Normal High

10 950 μs* 950 μs* 950 μs* 12 950 μs* 950 μs* 950 μs* 15 950 μs* 950 μs* 800 μs 20 950 μs* 950 μs* 600 μs 30 950 μs* 800 μs 400 μs 50 600 μs 400 μs 200 μs 60 600 μs 400 μs 200 μs

* 950 μsec= max. allowed LED impulse width LEDs can be turned on/off by using the leden parameter (1 - on, 0 - off).

/58

Page 43/58 Page 43/58


2.1.1 Frame Parity Flashing NOTE: This function is required only under such special circumstances when the recognition of both reflective and non-reflective number plates is necessary. The Frame Parity Flashing option can be used to setup the camera for reading both reflective and non-reflective license plates. This task is realized by switching to lower and higher light output between odd and even frames. With this illuminating technique, the camera captures images with more and less intensive illumination. The former images will be suitable for the recognition of non-reflective license plates, while the latter ones are for reflective plates. If led_diff_en is enabled, then the illuminating light output used on odd frames will be different from the illuminating light output used on even frames. The extent of difference can be adjusted with the help of the led_diff_pc parameter according to the followings: the illuminating light output on odd frames will be reduced to led_diff_pc percentage of the illuminating light output on even frames. E.g. if led_pcdose is set to 50 and led_diff_pc is set to 20 then the camera will flash with 50% power on even frames and 10% (20% of the 50%) on odd frames.

2.2 Motorized Optics and Filter Switching Unit Use this module to access and calibrate the motorized optics of the camera. The motorized optics can be turned in finite many steps. Calibration means rescanning the entire range of the optics to measure the exact position and length of control to compensate deviation (if there is any). The state of the filter switching unit can also be set here, that is to insert different kinds (e.g. infrared cut) filters in front of the optics, depending on the hardware configuration of the camera. 2.3 Diagnostics Through diagnostics, the following diagnostic values and controls can be accessed:

camera temperature (Celsius scale) light sensor value (0-255) green status LED to display status

3. Parameters Built-in light source

Name RO/RW Legal Values Description leden RW [0,1] 0 - disables built in light source,1 enables it

ledpwr* RW [0,1,2] LED power: 0 - low, 1 - medium, 2 - high ledtimeus* RW [5-950] LED flash pulse length in microseconds led_pcdose RW [0-100] LED illumination value in percentage led_diff_en RW [0,1] 1- enabling, 0-disabling Frame Parity Flashing

ledtimeus2 RW [5-950] flashing time in μseconds on odd frames

NOTE: It is valid only if led_diff_en=1!

led_diff_pc RW [0-100], -1

illuminating value for odd frames represented as a percentage of the led_pcdose value used on even

frames. -1: frame illumination difference is disabled

(it has the same effect as led_diff_en=0)

/58

Page 44/58 Page 44/58


Motorized optics and Filter Switching Unit

Name RO/RW Legal Values Description iris_pos RW [*] Iris position in steps (* between iris_min and iris_max)

iris_pc RW [0-100] Iris position in percentage

(if queried, it returns limits for iris (percentage)) iris_min RO [uint] Iris minimum position (steps) iris_max RO [uint] Iris maximum position (steps)

iris_moving RO [0,1] 1 if iris is moving

focus_pos RW [*] focus position in steps (* between focus_min and

focus_max) focus_pc* RW [0-100] focus position in percentage focus_min RO [uint] focus minimum position (steps) focus_max RO [uint] focus maximum position (steps)

focus_moving RO [0,1] 1 if focus is moving

zoom_pos RW [*] zoom position in steps (* between zoom_min and

zoom_max) zoom_pc* RW [0-100] zoom position in percentage zoom_min RO [uint] zoom minimum position (steps) zoom_max RO [uint] zoom maximum position (steps)

zoom_moving RO [0,1] 1 if zoom is moving calibrate RO [0-100] progress of calibration (if running) filter RW [0,1] status of filter switcher: 0 - IR cut, 1 – all pass iris RO [uint] returns limits for iris (steps) focus RO [uint] returns limits for focus (steps) zoom RO [uint] returns limits for zoom (steps)

Diagnostics

Name RO/RW Legal Values Description overdrive RO [0,1] 1 if LED protection is active

temperature RO [uint] camera temperature (Celsius) lightsensor RO [0-255] light sensor value status_g RW [0,1] 1 - green status LED is on

*usable with ‘query’ as well e.g. 192.0.2.60/hwlayer/cperiph?queryledpwr=1 uint [0..232-1]

/58

Page 45/58 Page 45/58


Logging [logging/logstream]

1. Short Description Camera events are logged into the central log file for administrative and error management purposes. The lines (records) of the log can be filtered for specific events according to the specified characters. Note, that the log file content is erased after restarting the camera. The log file can be saved and returned by the following command: http://{IP address}/logging/logstream?getlog&ajaxcall=1

2. Filtering Log Records Log events can be filtered for defined character strings. To use this option, the filter parameter must be used according the followings: http://{IPaddress}/logging/logstream?filter={stringtofind}&ajaxcall=1 Previously set filter can be queried as follows: http://{IP address}/logging/logstream?getfilter&ajaxcall=1

Logging Commands

Command name

Format Example Description

getlog http://{IP

address}/logging/logstream?getlog&ajaxcall=1

http://192.0.2.31{/logging/logstream?getlog&ajax

call=1

opening the log file

retrieving previously set

characters used to filter for

getfilter http://{IP

address}/logging/logstream?getfilter&ajaxcall=1

http://192.0.2.31/logging/logstream?getfilter&aj

axcall=1

setfilter http://{IPaddress}/logging/logstream?setfilter={stringtofind}&ajaxcall=1

http://192.0.2.31/logging/logstream?filter=20110

820&ajaxcall=1

setting characters to

filter for

/58

Page 46/58 Page 46/58


Interface to External Illuminators [hwlayer/illuminator]

1. Short description This module provides access to the external LED light sources.

2. Detailed description The intensity of the built-in light source of the camera can be set and queried by two methods. The first is to enter a 0-100 % value using the parameter led_pcdose, which will change the light output accordingly. For more control, the amplitude of the flash can be set with ledpwr to:

0 - low 1 - medium 2 - high

and set the flash time in microseconds using the parameter ledtimeus. NOTES:

It is not recommended to set higher pulse width than the length of the shutter, because this will not make the image any brighter.

On too high LED powers with too long pulse width and too high frame rate, the camera will protect the LEDs by disabling them for a couple of frames.

LEDs can be turned off by using the leden parameter. The illuminators can be addressed separately using the ill_addr parameter.

3. Parameters

Name RO/RW Legal Values Description leden RW [0,1] 0 for built in light source disable, 1 for enable ledpwr RW [0,1,2] LED power: 0 - low, 1 - medium, 2 - high

ledtimeus RW [0-900] LED flash pulse length in microseconds pc_dose RW [0-100] LED illumination value in percentage

queryledpwr RO [uint] query LED power possible values queryledtimeus RO [uint] query LED flash pulse possible values

status_g RW [0,1] 1 - green status LED is on ill_addr W [1,2,...] address of the illuminator

/58

Page 47/58 Page 47/58


ARHIP - PC API Description The PC API consists of the following files:

arhip.h: C/C++ file containing function descriptions arhip.dll, arhip.lib: for Windows projects libarhip.so: for Linux projects

With the help of the ARHIP, it is possible to connect to a camera’s built-in web server from a user-written piece of software, delivering the user from the burden of implementing e.g. the TCP/IP communication protocol and providing tools for FreewayCAM-specific functions. The ARHIP is capable of retrieving images from received MJPEG streams. Besides, the API is also capable of sending queries to the camera and receiving the answers. E.g. capturing an image, downloading its data and adjusting parameters. Before calling the functions below, the corresponding structures must be filled with zeros with the memset function. Filling with zeros between function calls is not necessary because the arhip_freeanswer function does that for you. The web interface can be accessed through browsers and from the ARHIP as well. Queries related to certain functions and operations are the same as the variables of the corresponding HTML requests. The ARHIP supports both the GET and POST methods. Data are returned in the content type section of the HTTP response as parameter types. File and module names are the same as in case of accessing from browsers.

1. Module Initialization and Closure

int arhip_init(void); This function is for initializing the module. In case of error, it returns a negative number. If it returns a positive number or 0 then no error has occurred. Negative values are standard POSIX error codes.

void arhip_cleanup(void); This function is for closing the module.

2. Functions of Communication (query/answer)

2.1 Establishing Connection with the Device

int arhip_connect(const char *host); Parameters:

host: Link to the device that can be a hostname, IPv4 or IPv6 address and port. Port can be specified after a colon. IPv6 addresses have to be enclosed in square brackets (as in browsers). Examples: IPv4: http://10.0.0.1:80 IPv6: http://[2001:4860:0:2001::80]/

The default port is 80.

/58

Page 48/58 Page 48/58


Returned values: If negative then error occurred. The error code is included. If 0 or any positive number then the handle is returned, this handle has to be passed to the other

functions.

2.2 Disconnecting from the Device

int arhip_disconnect(int handle); Parameters:

handle: Closing the channel opened by the arhip_connect function. Returned values:

If negative then error occurred. The error code is included. If 0 or any positive number then the function was successful.

3. Handling of Data Streams In case of data streams, the device executes data sending continuously. The data stream can be e.g. an MJPEG stream (in this case the data stream consists of JPEG images).

3.1 Opening a Stream int arhip_openstream(const char *host);

Parameters:

host: Link to the device that can be a hostname, IPv4 or IPv6 address and port. Port can be specified after a colon. IPv6 addresses have to be enclosed in square brackets (as in browsers). Examples: IPv4: http://10.0.0.1:80 IPv6: http://[2001:4860:0:2001::68]/

The default port is 9901.

Returned values:

If negative then error occurred. The error code is included. If 0 or positive then the handle is returned which has to be passed to the other functions.

/58

Page 49/58 Page 49/58


3.2 Closing the Data Stream int arhip_closestream(int handle);

Parameter:

handle: Closing the channel opened by the arhip_openstream. Returned values:


3.3 Querying a Frame from the Stream Frames can be queried from opened streams. The answer can be freed with the arhip_freeanswer function as described above. Getting a frame from the stream:

int arhip_getdata(int handle, struct ARHIP_ANSWER *answer, int timeoutms); Parameters:

handle: Channel opened by the arhip_openstream function. answer: The answer will be in this parameter. timeoutms: Maximal length of waiting time for the answer.

Returned values:

If negative then error occurred. The error code is included. If 0 or any positive number then the function was successful. If the amount of returned data would exceed eight Mbytes then an error is returned (EINVAL). Eight

Mbytes is the maximal amount of data that can be returned. Before calling the functions, the ARHIP_ANSWER structure has to be filled with zeros with the memset function. Filling with zeros between function calls is not necessary because the arhip_freeanswer function does that for you.

3.4 Sending a Query and Waiting for the Answer The API sends a query to the device then waits for the answer. Both the query and the answer are placed into structures. Structure of the query: struct ARHIP_QUERY { const char *modtypeandname; int sessionid; const char *param; const void *data; int datalen; const char *filename; };

/58

Page 50/58 Page 50/58


Before sending a query, the following fields must be set:

modtypeandname: The type and name of the module. It is not URL coded, the accepted characters are '/' plus the alphanumeric characters. It must be a standard '\0' terminated string and must be set according to the following template: 'moduletype/modulename' or 'path/filename' (do not begin with '/'). Setting this field is mandatory; its maximal length is 128 bytes.

sessionid: The identifier of the session. If it is not 0 then a new session will open (default session ID is 0).

param: Parameter string. Parameters have to be defined as follows: name=value. Note that every

parameter must be set in separate lines (1 parameter/1 line, separated by '\r\n'). These lines will be parameter/1 line). These lines will be URL encoded except the following characters: - _ . ~ = and ,. Note that this field cannot be NULL but empty string only. Its maximal length is 3072 bytes.

data: Data to be sent. If not used, it must be set to NULL.

datalen: Length of data in bytes. Values between 0 and 32768 (32 Mbytes) are valid.

filename: This filename will be used at upload when sending data. Its maximal length is 64 characters. If

no filename is set then the default file name 'apidata.dat' is used. If the field is not used it must be set to NULL. (E.g. when sending a file to the update/default module this field will contain the name of the file while the data will contain the bytes of the file.

Structure of the answer: struct ARHIP_ANSWER { char *param; void data* ; int datalen; void *exdata; int exdatalen; }; Before calling the function, this structure has to be filled with zeros with the memset function. After the answer has been processed, call the arhip_freeanswer function to free memory allocated by the arhip_iterate function in the answer.

param: Returned ASCII string parameters. These parameters are stored separately (one line/one parameter, separated by ‘\r\n’) as follows: name=value. It can be NULL if there are no parameters.

data: Returned data. It can be NULL if there is no data. It is e.g. a JPEG image.

datalen: Length of data in bytes.

exdata: Returned extra data. It can be NULL if there is no data. It may contain extra image data. Such data

are e.g. a histogram, motion detection or DCT information, etc.

exdatalen: Length of extra data in bytes.

/58

Page 51/58 Page 51/58


Sending a query for the device and requesting the answer:

int arhip_iterate(int handle, struct ARHIP_QUERY *query, struct ARHIP_ANSWER *answer, int timeoutms);

Parameters:

handle: Channel opened by the arhip_connect function. query: The query has to be passed in this parameter. answer: This parameter will contain the answer. timeoutms: Maximal waiting time for answer and sending.

Returned values:


If the data, received from the server, contains any error (HTTP protocol error) then the arhip_iterate() function returns with the EINVAL (22) error code. If a query – that the server cannot answer any content – arrives, (non-existing file or module, or the module cannot create answer data) then 404 is returned in the parameter field of the ARHIP_ANSWER structure.

3.5 Deleting the Answer void arhip_freeanswer(struct ARHIP_ANSWER *answer); Parameter: answer: Pointer to the received answer. After the arhip_iterate and arhip_getdata function calls, the answer must be deleted with this function to free the allocated areas. If the answer pointer itself points to an allocated area then this area must be freed by the programmer.

/58

Page 52/58 Page 52/58


Creating Backup File with ARHIP PCAPI //Creating Backup File with ARHIP PCAPI //Includes for Linux: #include <stdio.h> #include <string.h> #include "arhip.h" //Includes for Windows: #include "arhip.h" #include <stdio.h> #include <tchar.h> #include <windows.h> int main(int argc, char *argv[]) { arhip_init(); arhip_handle connected=arhip_connect("192.0.2.27",1); //IP address of the device if(connected){ struct ARHIP_QUERY qpr; struct ARHIP_ANSWER apr; memset(&qpr,0,sizeof(qpr)); qpr.modtypeandname="backup"; qpr.param="pipe=1=2"; //the mode specifies what to save memset(&apr,0,sizeof(apr)); int ec=arhip_iterate(connected, &qpr, &apr, 5000); //the more data you want to save the more timeout you need if(ec>0 && apr.data){ FILE* flet=fopen("backup.tar.gz","wb"); //the backup file fwrite(apr.data,1,apr.datalen,flet); fclose(flet); arhip_freeanswer(&apr); } else{ perror("arhip_iterate() "); } arhip_disconnect(connected); } else{ perror("arhip_connect()"); } arhip_cleanup(); return 0; }

/58

Page 53/58 Page 53/58


Uploading Backup File (Update) with ARHIP PCAPI //Includes for Linux: #include <malloc.h> #include <string.h> #include "arhip.h" //Includes for Windows: #include "arhip.h" #include <stdio.h> #include <tchar.h> #include <windows.h> #include <malloc.h> int main(int argc, char *argv[]) { arhip_init(); arhip_handle connected=arhip_connect("192.0.2.27",1); //IP address of the device if(connected){ struct ARHIP_QUERY qpr; struct ARHIP_ANSWER apr; memset(&qpr,0,sizeof(qpr)); qpr.modtypeandname="update"; qpr.param="pipe=1"; qpr.sessionid=0; FILE* df=fopen("backup.tar.gz","rb"); //backup file to be uploaded fseek(df, 0, SEEK_END); size_t len = ftell(df); fseek(df, 0, SEEK_SET); void* load=malloc(len); fread(load, len, 1, df); fclose(df); qpr.data=load; qpr.datalen=len; memset(&apr,0,sizeof(apr)); int ec=arhip_iterate(connected, &qpr, &apr, 5000); //the more data you want to save the more timeout you need free(load); if(ec>0 && apr.data){ FILE* flet=fopen("answ.txt","wb"); //to show the result fwrite(apr.data,1,apr.datalen,flet); fclose(flet); arhip_freeanswer(&apr); } else{ perror("arhip_iterate() "); } arhip_disconnect(connected); } else{ perror("arhip_connect()"); } arhip_cleanup(); return 0; }

/58

Page 54/58 Page 54/58


Getting Images from the Scapture Module /* This sample program saves three images into jpeg files according to the followings: First, it saves the latest captured image and its parameters. Then, it saves the image captured right after the previously saved image (with the help of the image’s exact time of capturing). Finally, it saves the image captured closest to the time (timestamp) 2 seconds before the image saved first. */ #ifdef WIN32 #include <windows.h> #include <stdio.h> #define snprintf _snprintf #define sleep Sleep #define TSLEEP 1000 #else #include <malloc.h> #include <string.h> #include <unistd.h> #include "arhip.h" #define TSLEEP 1 #endif #include <time.h> #include <stdlib.h> #include "arhip.h" //This function processes the camera answer: extracts the parameters from the scapture answer, prints them to the console, saves an image and returns the absolute value of the time of capturing in the second parameter. // @param answ the camera (as server) answer structure. // @param frmt absolute value of time of capturing in milliseconds void parse_vals(struct ARHIP_ANSWER answ, unsigned long long* frtm ); int main(int argc, char* argv[]) { unsigned long long frtm=0; //variable of the time of frame capturing (timestamp) arhip_init(); //ARHIP PCAPI initialization

arhip_handle connected=arhip_connect("192.0.2.3",1); //opening connection to the camera with the ecified IP address sp

if(connected){ //if connecting was successful struct ARHIP_QUERY qpr; //query for the camera struct ARHIP_ANSWER apr; //answer from the camera memset(&qpr,0,sizeof(qpr)); //filling the memory area of the variable with zeroes qpr.modtypeandname="scapture"; //querying the image from the scapture module qpr.param="capture=last=1"; //scapture module is called with the specified parameters:

querying the latest captured image and its parameters et(&apr,0,sizeof(apr)); // filling the memory area of the variable with zeroes mems int ec=arhip_iterate(connected, &qpr, &apr, 1000); //sending the query and requesting for the

answer if(ec>=0){ //if the iterate function was successful if(apr.data && apr.param ){ //if there is any returned data (image) parse_vals(apr, &frtm); //processing } arhip_freeanswer(&apr); //freeing the memory area of the answer } else{ perror("arhip_iterate() "); //returning error code in case of error } sleep(TSLEEP);//waiting 1 sec //querying another image follows char s_last[128];

snprintf(s_last,sizeof(s_last),"capture=next=%llu=1", frtm); //querying the image captured right after the previous one with the help of the exact time of capturing of the image queried first

qpr.param=s_last; memset(&apr,0,sizeof(apr)); ec=arhip_iterate(connected, &qpr, &apr, 1000); // sending the query and requesting for the

answer if(ec>=0){ if(apr.data && apr.param ){ // if there is any returned data (image) parse_vals(apr, &frtm); // processing } arhip_freeanswer(&apr); } else{ perror("arhip_iterate() "); } sleep(TSLEEP); // waiting 1 sec

/58

Page 55/58 Page 55/58


// querying another image follows snprintf(s_last,sizeof(s_last),"capture=best=%llu=1", frtm-2000); //querying the image captured closest to the time (timestamp) 2 seconds before the image saved first in this program

qpr.param=s_last; memset(&apr,0,sizeof(apr)); ec=arhip_iterate(connected, &qpr, &apr, 1000); // sending the query and requesting for the

swer an if(ec>=0){ if(apr.data && apr.param ){ // if there is any returned data (image) parse_vals(apr, &frtm); // processing } arhip_freeanswer(&apr); } else{ perror("arhip_iterate() "); } arhip_disconnect(connected); //disconnecting } else{ perror("arhip_connect()"); } arhip_cleanup(); //closing ARHIP PCAPI (); getchar return 0; } void parse_vals(struct ARHIP_ANSWER answ, unsigned long long* frtm ) { const char* m_frtm="imgframetimems="; const char* m_frix="imgframeindex="; const char* m_frmo="imgframemonotimems="; char* s_frtm=NULL; char* s_frix=NULL; char* s_frmo=NULL; unsigned int msec=0; char* p_frtm=strstr(answ.param, m_frtm); if(p_frtm){ char* p_ent=strstr(p_frtm, ""); if(p_ent){ unsigned int l_val=p_ent-(p_frtm+strlen(m_frtm)); s_frtm=(char*)malloc(l_val+1); s_frtm[l_val]=0; memcpy(s_frtm,p_frtm+strlen(m_frtm),l_val); sscanf(s_frtm,"%llu",frtm); msec=(*frtm)%1000; } } char* p_frix=strstr(answ.param, m_frix); if(p_frix){ char* p_ent=strstr(p_frix, ""); if(p_ent){ unsigned int l_val=p_ent-(p_frix+strlen(m_frix)); s_frix=(char*)malloc(l_val+1); s_frix[l_val]=0; memcpy(s_frix,p_frix+strlen(m_frix),l_val); } } char* p_frmo=strstr(answ.param, m_frmo); if(p_frmo){ char* p_ent=strstr(p_frmo, ""); if(p_ent){ unsigned int l_val=p_ent-(p_frmo+strlen(m_frmo)); s_frmo=(char*)malloc(l_val+1); s_frmo[l_val]=0; memcpy(s_frmo,p_frmo+strlen(m_frmo),l_val); } } if(s_frt frix && s_frmo){ m && s_ time_t frmtsec=(*frtm)/1000; tm* tm_loc=localtime(&frmtsec); printf("frametime:%s (%d.%d.%d %d:%d:%d.%d):%s:%s",s_frtm, tm_loc->tm_year+1900, tm_loc->tm_mon+1, tm_lo _mday, tm_loc->tm_hour, tm_loc->tm_min, tm_loc->tm_sec, msec, s_frix, s_frmo ); c->tm char fname[128]; snprintf(fname, sizeof(fname),"%s.jpg", s_frtm); FILE* fs_jpgres=fopen(fname,"wb"); fwrite(answ.data,1,answ.datalen,fs_jpgres); fclose(fs_jpgres);

/58

Page 56/58 Page 56/58


} if(s_frtm) free(s_frtm); if(s_frix) free(s_frix); if rmo) free(s_frmo); (s_f return; }

IMPORTANT: Note that samples are instructional and may not include all security mechanisms required for a production environment.

/58

Page 57/58 Page 57/58


/58

Page 58/58 Page 58/58

Page 58/58


Contact Information

Should you have any problem during operating the FreewayCAM, our support team is at your disposal. Please try to explain the problem as detailed as possible and do not forget to send the following information to make it easier to help you:

The name of your company (for administration purposes). The exact type of the product you have (serial number is appreciated). If you have problems during recognition, send images in the original file format. If there is any error code or message appearing, please send us the code snippet where it occurs (a

screenshot may also be helpful). If you noticed the problem while running a Demo or a sample application, please let us know the name of

the application you tested. If you have some problem while developing your own application, please specify the followings:

o your programming language o your operating system o the name and version number of the compiler you use o the programming technology (e.g. native C/C++ / ActiveX / .NET) o If possible please send a short part of the source code. Please try to determine the place where the

error occurs (e.g. “the scapture?getshutter command returns a negative number…“).

IMPORTANT NOTES:

Before sending back a faulty device, always contact ARH Support Team. Repairs may be executed by the manufacturer only!

Office address: Service address: ARH Inc. ARH Inc. 41 Alkotás Road Ipari Park HRSZ 1113/1 HU-1123 Budapest HU-2074 Perbál Hungary Hungary Phone: +36 1 2019650 Phone: +36 1 2019650 Web: www.arh.hu Web: www.arh.hu Email: [email protected] Email: [email protected]

http://www.arh.hu/

http://www.arh.hu/

mailto:[email protected]

mailto:[email protected]

FreewayCAM Programmer’s Manualdoc.arhungary.com/freewaycam/freewaycam_programmers_manual.… ·...

Documents

Transcript of FreewayCAM Programmer’s Manualdoc.arhungary.com/freewaycam/freewaycam_programmers_manual.… ·...