Howto:Working with multiple Door Cameras: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
 
(22 intermediate revisions by 5 users not shown)
Line 12: Line 12:
==More Information==
==More Information==
=== Overview ===
=== Overview ===
When multiple door cameras are used, the standard mechanism described in [[Howto:Door Phone with Video in V10 and later]] is not sufficient, as the URL used in the phone is static and will always show the same door camera.  Instead, the image should switch from one camera to the next continuously.  Also, when the operator is called by the door phone, the picture from the calling door should be shown always and the phone UI should switch to the ''Video'' app.  This can be achieved using a this SOAP-based utility.
When multiple door cameras are used, the standard mechanism described in [[Howto:Door Phone with Video in V10 and later]] is not sufficient, as the URL used in the phone is static and will always show the same door camera.  Instead, the image should switch from one camera to the next continuously.  Also, when the operator is called by the door phone, the picture from the calling door should be shown always and the phone UI should switch to the ''Video'' app.  This can be achieved using this SOAP-based utility.


=== Prerequisites ===
=== Requirements ===
This SOAP script requires a web server running PHP5.  A [[Reference10:Concept_Linux_Application_Platform | Linux Application Platform ]] is fine, but any other PHP platform should do too.
* A web server running PHP5.  A [[Reference10:Concept_Linux_Application_Platform | Linux Application Platform]] is fine, but any other PHP platform should do too. (Remark: V13 Application Platform does not provide any PHP server.)
* For the ''switch to video app'' feature, you need at least script version 1005 and telephone firmware which includes fix ''17611 - Phones: Remote Control Facility "switch2App"'' (that is, v12r2 - beta 1 (125048) or later).
* If the PBXs have configured DNS names, the web server must be able to resolve these, as SOAP may need to connect to slave PBXs using the configured DNS-Names.


For the ''switch to video app'' feature, you need at least script version 1005 and telephone firmware which includes fix ''17611 - Phones: Remote Control Facility "switch2App"'' (that is, v12r2 - beta 1 (125048) or later).
===Download ===
*[http://wiki.innovaphone.com/index.php?title=Howto:Wiki_Sources#doorcontrol Download] the complete file package of scripts and files described in this article.


===Download ===
*[http://download.innovaphone.com/ice/wiki-src#doorcontrol http://download.innovaphone.com/ice/wiki-src#doorcontrol ] - download the complete file package of scripts and files described in this article.
=== Installation ===
=== Installation ===
Unpack the downloaded file (see [[#Download]]).  Copy the content of the <code>Solution/sources</code> directory (including the sub directories) to your web server.
Unpack the downloaded file (see [[#Download]]).  Copy the content of the <code>Solution/sources</code> directory (including the sub directories) to your web server.


Open your web browser and go to <code>http://your-web-server-name-or-ip/path-you-installed-the-toolto/DoorControl.php?debug</code>. You should see something like
''number'' seconds since last switch ...
switching to next ''name-of-door''
...
==== On a Linux Application Platform ====
==== On a Linux Application Platform ====
To install the utility on a [[ Reference10:Concept_Linux_Application_Platform| Linux Application Platform  ]], you may proceed as follows
To install the utility on a [[ Reference10:Concept_Linux_Application_Platform| Linux Application Platform  ]], you may proceed as follows
Line 45: Line 40:
** change owner of <code>doorcontrol</code> and all its sub -directories to <code>www-data</code> (e.g. <code>chown -R www-data doorcontrol</code>)
** change owner of <code>doorcontrol</code> and all its sub -directories to <code>www-data</code> (e.g. <code>chown -R www-data doorcontrol</code>)


If you now type <code>http://</code>''lap-ip-addr''<code>/doorcontrol/DoorControl.php?debug</code>, you should see the message mentioned above.
After you have finished the configuration open your web browser and go to <code>http://your-web-server-name-or-ip/path-you-installed-the-toolto/DoorControl.php?debug</code>. You should see something like
''number'' seconds since last switch ...
switching to next ''name-of-door''
...


===Configuration===
===Configuration===
Line 70: Line 68:
The root tag <code>doors</code> has a few attributes which define the PBX access (used to determine if a phone is being called by a door phone):
The root tag <code>doors</code> has a few attributes which define the PBX access (used to determine if a phone is being called by a door phone):
; pbx : the IP address of the PBX
; pbx : the IP address of the PBX
; pbxhttp : the HTTP user to be used to access the SOAP service on the PBX (usually the ''Name''' of a PBX user object or the admin user)
; pbxhttp : the HTTP user to be used to access the SOAP service on the PBX (usually the ''Name''' of a PBX user object with minimum [[Reference9:PBX/Objects/Edit_Rights|''Groups/Call Forwards only'' access right]] or the admin user of the box)
; pbxpw : the password of the HTTP user
; pbxpw : the password of the HTTP user
; pbxuser : the ''Long Name'' of a user object that is used to access the SOAP service on the PBX
; pbxuser : the ''Long Name'' of a user object that is used to access the SOAP service on the PBX


Also, the interval between switching the available door cams must be defined
Also, the interval between switching the available door cams must be defined
; interval : the number of seconds the utility will wait before switchign to the next camera  
; interval : the number of seconds the utility will wait before switching to the next camera  


Finally, you can optionally have the phone switch to the ''video app'' automatically:
Finally, you can optionally have the phone switch to the ''video app'' automatically:
; switch : <code>true</code> or <code>false</code>.  If set to ''true'', the script will notify the phone when it detects a call from a door, so that the phone switches to the video app. This requires fix [[Support:DVL-Roadmap_Firmware_12r2#17611_-_Phones:_Remote_Control_Facility_.22switch2App.22 | Remote Control Facility "switch2App"]] and therefore firmware ''v12r2 beta 1'' or later.  Also it requires at least script version 1004.   
; switch : <code>true</code> or <code>false</code>.  If set to ''true'', the script will notify the phone when it detects a call from a door, so that the phone switches to the video app. This requires a fix within firmware ''v12r2 beta 1'' or later.  Also it requires at least script version 1004.   
====== door ======
====== door ======
Each sub-tag <code>door</code> defines an available door camera.
Each sub-tag <code>door</code> defines an available door camera.
Line 103: Line 101:
: if this is set to <code>true</code>, SSL-Certificate of the given <code>url</code> will not be verified
: if this is set to <code>true</code>, SSL-Certificate of the given <code>url</code> will not be verified
; proxy-resize [since build 1009]
; proxy-resize [since build 1009]
: if this is set to <code>true</code>, the big pictures will be resized for IP-Phone. The size is depending on the phone model and must not be configured. You can use this method if your camera is not able to provide small images. Please note that this increase the ressource usage on your webserver and should only used if your camera does not support the resize process itself.
: if this is set to <code>true</code>, the big pictures will be resized for IP-Phone. The size is depending on the phone model and does not need to be configured. You can use this method if your camera is not able to provide small images. Please note that this increases the resource usage on your webserver and should only be used if your camera does not support the resize process itself.


==== Phone ====
==== Phone ====
The ''door operator''s phone (that is, the phone that shall monitor the video image of the door(s)) needs some configuration as follows.
The ''door operator''s phone (that is, the phone that shall monitor the video image of the door(s)) needs some configuration as follows.


The ''Background Image'' property in [[Reference11r1:Phone/Preferences | Phone/Preferences ]] must be set to the DoorControl.php script on your web server.  It supports 2 arguments
The ''Background Image'' property in [[Reference11r1:Phone/Preferences | Phone/Preferences ]] must be set to the DoorControl.php script on your web server.  It supports the following arguments
; id : e.g. <code>id=operator</code>, the ''Long Name'' of the PBX user object the retrieving phone is registered with.  The script will use this name to query the PBX if the phone is currently being called by a door phone. (Special chars have to be [https://en.wikipedia.org/wiki/Percent-encoding#Character_data encoded])
; id : e.g. <code>id=operator</code>, the ''Long Name'' of the PBX user object the retrieving phone is registered with.  The script will use this name to query the PBX if the phone is currently being called by a door phone. (Special chars have to be [https://en.wikipedia.org/wiki/Percent-encoding#Character_data encoded])
; hw : e.g. <code>hw=0090333e0c57</code>, the ''Hardware Id'' used to register the operator's phone (optional, may be omitted if the operator does not have multiple registrations or mobility). Requires at least script version 1004 (Special chars have to be [https://en.wikipedia.org/wiki/Percent-encoding#Character_data encoded])
; hw : e.g. <code>hw=0090333e0c57</code>, the ''Hardware Id'' used to register the operator's phone (optional, may be omitted if the operator does not have multiple registrations or mobility). Requires at least script version 1004 (Special chars have to be [https://en.wikipedia.org/wiki/Percent-encoding#Character_data encoded])
Line 133: Line 131:
* open the <code>switchops.xml</code> script itself and fix the url found in the ''string'' argument of the <code>lib-strcat</code> tag near line 23 so that it points to your installed <code>DoorControl.php</code>, e.g.  
* open the <code>switchops.xml</code> script itself and fix the url found in the ''string'' argument of the <code>lib-strcat</code> tag near line 23 so that it points to your installed <code>DoorControl.php</code>, e.g.  
   <code xml><lib-strcat out-string="$url" string="http://1.2.3.4/doorcontrol/DoorControl.php?switchapp=1&amp;h323=" string2="$leg2-name-enc"/></code>
   <code xml><lib-strcat out-string="$url" string="http://1.2.3.4/doorcontrol/DoorControl.php?switchapp=1&amp;h323=" string2="$leg2-name-enc"/></code>
: into
  <code xml><lib-strcat out-string="$url" string="http://my.door.tld/path-on-web-server/DoorControl.php?switchapp=1&amp;h323=" string2="$leg2-name-enc"/></code>
: note that anything including and behind <code>/DoorControl.php?</code> must stay unchanged!
: note that anything including and behind <code>/DoorControl.php?</code> must stay unchanged!
* add a ''Fork''ing for the PBX user running the ''door operator'' phone towards the newly created ''Voicemail'' object
* add a ''Fork''ing for the PBX user running the ''door operator'' phone towards the newly created ''Voicemail'' object
Line 174: Line 170:
=== Error: Allocation limit exceded ===
=== Error: Allocation limit exceded ===
The filesize is too big for the Phone and will be rejected. Reduce the filesize via URI if your camera support this. (eg. image.jpg?size=640x480)<br />
The filesize is too big for the Phone and will be rejected. Reduce the filesize via URI if your camera support this. (eg. image.jpg?size=640x480)<br />
If you rcamera does not support the resize process, you can use the <code>proxy-resize</code> method described above.
If your camera does not support the resize process, you can use the <code>proxy-resize</code> method described above.
 
=== Error: bad state XML ===
Remove ''state.xml'' from doorcontrol folder, after that you get a correct error message if you reload the Doorcontrol.php in Webbrowser


==Known Problems==
==Known Problems==
* Forking to a VM Object without mobility object (license required) will display the name of the forking target in the caller display and his calllist. (To prevent this behaviour, use a mobility object for the forking to <code>doorcall-trigger</code>)
=== Wrong Caller Name ===
* Forking to a VM Object without mobility object (license required) will display the name of the forking target in the caller display and his callist. (To prevent this behavior, use a mobility object for the forking to <code>doorcall-trigger</code>)
 
=== 3rd party SOAP Application show multiple calls ===
Some SOAP applications show a permanent call to the ''doorcall-trigger'', even though the agent on the desk phone has already picked up.<br>
To turn this off, the solution must be adjusted as follows:
 
You have to edit the ''switchops.xml'' and add a ''<pbx-disc />'' at the end of the function ''Main''
<code xml>
  <voicemail xmlns="http://www.innovaphone.com/xsd/vm.xsd">
  <function define="Main">
    ...
    <exec url="$url"/>
    <pbx-disc />
  </function>
</voicemail>
</code>
 
Additional you have to update the [[Reference10:PBX/Objects/Edit_Forks|Forking configuration]] of the agent, use a Mobility or UC License for the Agent and create (or use an existing) Mobility Object in your PBX.<br>
Configure the ''Object'' and ''Min-Alert''=1 in the forking of the agent.


==Related Articles==
==Related Articles==

Latest revision as of 09:17, 17 July 2023

Applies To

This information applies to

  • V10 and innovaphone PBX platform
  • innovaphone phones supporting video
  • web server running PHP 5

some innovaphone phones support display of a door phone camera picture (see Howto:Door Phone with Video in V10 and later). However, only one camera is supported. This article describes a solution for use of multiple door cameras.


More Information

Overview

When multiple door cameras are used, the standard mechanism described in Howto:Door Phone with Video in V10 and later is not sufficient, as the URL used in the phone is static and will always show the same door camera. Instead, the image should switch from one camera to the next continuously. Also, when the operator is called by the door phone, the picture from the calling door should be shown always and the phone UI should switch to the Video app. This can be achieved using this SOAP-based utility.

Requirements

  • A web server running PHP5. A Linux Application Platform is fine, but any other PHP platform should do too. (Remark: V13 Application Platform does not provide any PHP server.)
  • For the switch to video app feature, you need at least script version 1005 and telephone firmware which includes fix 17611 - Phones: Remote Control Facility "switch2App" (that is, v12r2 - beta 1 (125048) or later).
  • If the PBXs have configured DNS names, the web server must be able to resolve these, as SOAP may need to connect to slave PBXs using the configured DNS-Names.

Download

  • Download the complete file package of scripts and files described in this article.

Installation

Unpack the downloaded file (see #Download). Copy the content of the Solution/sources directory (including the sub directories) to your web server.

On a Linux Application Platform

To install the utility on a Linux Application Platform , you may proceed as follows

  • open the LAP's file system using a SFTP client such as e.g. WinSCP (if you have not yet changed it, the default credentials will be root/iplinux, see Concept Linux Application Platform). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
    • create the new directory called doorcontrol underneath the /var/www/innovaphone directory.
    • copy the files doors.xml, switchops.xml and DoorControl.php to the new directory
    • create a subdirectoy /doorcontrol/classes
    • change to this directory
    • copy the file innopbx.class.php to the new directory
  • log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be admin/linux, see Concept Linux Application Platform)
    • go to Administration/Web Server/Change web server properties and public access to the web/webdav
    • add doorcontrol to Public Web Paths
  • log in the LAP's root shell (using e.g. putty, if you have not yet changed it, the default credentials will be root/iplinux, see Concept Linux Application Platform)
    • cd to /var/www/innovaphone
    • change owner of doorcontrol and all its sub -directories to www-data (e.g. chown -R www-data doorcontrol)

After you have finished the configuration open your web browser and go to http://your-web-server-name-or-ip/path-you-installed-the-toolto/DoorControl.php?debug. You should see something like

number seconds since last switch ...
switching to next name-of-door
...

Configuration

Configuration needs to be done in the doors.xml file that comes with the DoorControl.php script and on the phone that is used to monitor the door video(s).

When the switch to video app function is used (see below), additional configuration on the PBX is required.

doors.xml

The utility comes with a working sample configuration (in doors.xml). This file must reside in the same directory you installed the PHP script (DoorControl.php) too. The sample file looks like this: <?xml version="1.0" encoding="UTF-8"?> <doors

   pbx="1.2.3.4"
   pbxhttp="demo"
   pbxpw="demo"
   pbxuser="_TAPI_"
   interval="5"
   switch="false"

>

   <door name="door" url="http://wiki.innovaphone.com/images/innoWiki.png"/>
   <door name="behnke" url="https://www.innovaphone.com/content/images/innovaphone-slider-uc.png" proxy="true" content-type="image/png"/>

</doors>

doors

The root tag doors has a few attributes which define the PBX access (used to determine if a phone is being called by a door phone):

pbx
the IP address of the PBX
pbxhttp
the HTTP user to be used to access the SOAP service on the PBX (usually the Name' of a PBX user object with minimum Groups/Call Forwards only access right or the admin user of the box)
pbxpw
the password of the HTTP user
pbxuser
the Long Name of a user object that is used to access the SOAP service on the PBX

Also, the interval between switching the available door cams must be defined

interval
the number of seconds the utility will wait before switching to the next camera

Finally, you can optionally have the phone switch to the video app automatically:

switch
true or false. If set to true, the script will notify the phone when it detects a call from a door, so that the phone switches to the video app. This requires a fix within firmware v12r2 beta 1 or later. Also it requires at least script version 1004.
door

Each sub-tag door defines an available door camera.

url
the URL to retrieve a single picture from this camera. You must use the single-picture URL here (usually ending in .jpg), not the picture stream (.mjpg). Otherwise, the phone will never switch to the next camera.
name
the Name of the PBX user object the door phone is registered with

Proxy Access to Door Camera

In normal operation, this script will not deliver the door cam image itself to the caller. Instead, it will tell the calling client the URL where the current door cam image can be retrieved (using a HTTP/1.1 307 Temporary Redirect response with a Location: ... header). The phone will then refer to this URL and retrieve the image itself.

However, in rare situations this may not work (e.g. AXIS cameras are known to be incompatible with the HTTP client built-in to the innovaphone phone when the image requires authentication). In this case, the script behaviour can be modified so that the image actually is retrieved by the script and then returned to the caller.

proxy
if this is set to true, the image will be retrieved by the script and returned to the caller directly
user
if authentication is required by the camera and proxy mode is used, you can provide the authentication user-name here
pw
if authentication is required by the camera and proxy mode is used, you can provide the authentication password here
content-type
you can optionally specify the value used for the Content-Type: HTTP header (normally not necessary)
proxy-skip-ssl-verify [since build 1009]
if this is set to true, SSL-Certificate of the given url will not be verified
proxy-resize [since build 1009]
if this is set to true, the big pictures will be resized for IP-Phone. The size is depending on the phone model and does not need to be configured. You can use this method if your camera is not able to provide small images. Please note that this increases the resource usage on your webserver and should only be used if your camera does not support the resize process itself.

Phone

The door operators phone (that is, the phone that shall monitor the video image of the door(s)) needs some configuration as follows.

The Background Image property in Phone/Preferences must be set to the DoorControl.php script on your web server. It supports the following arguments

id
e.g. id=operator, the Long Name of the PBX user object the retrieving phone is registered with. The script will use this name to query the PBX if the phone is currently being called by a door phone. (Special chars have to be encoded)
hw
e.g. hw=0090333e0c57, the Hardware Id used to register the operator's phone (optional, may be omitted if the operator does not have multiple registrations or mobility). Requires at least script version 1004 (Special chars have to be encoded)
debug
if this is set, the script will not deliver the requested picture but will spit out some debug information

Please note that you must also add the query arguments not processed by the DoorPhone.php script but by the phone itself, namely

refresh
e.g. refresh=1, see Background Image in Reference11r1:Phone/Preferences and Howto:Door Phone with Video in V10 and later

So you may end up with something like http://my.door.tld/path-on-web-server/DoorControl.php?refresh=1&id=operator&hw=009033000000.


Picture Sources with Password Protection

If your camera is password protected, you must configure its URL and password in Services/HTTP/Client/Authenticated URLs.

Multiple Agents

If you want to serve this function to multiple Agents (e.g. over a Waiting queue), you have to use a separate Mobility Object per agent and configure the doorcall-trigger on each agent separately

PBX

From build 1005 on, the script can also switch the active app page on the door operator phone when a call from a door comes in. This feature requires additional configuration on the PBX.

  • create a PBX Voicemail object (you could set Long name and Name to doorcall-trigger for example)
  • in the 'Voicemail tab, tick the Trace check-mark
  • furthermore, set the Script URL to something like http://my.door.tld/path-on-web-server/switchops.xml
  • open the switchops.xml script itself and fix the url found in the string argument of the lib-strcat tag near line 23 so that it points to your installed DoorControl.php, e.g.
 <lib-strcat out-string="$url" string="http://1.2.3.4/doorcontrol/DoorControl.php?switchapp=1&h323=" string2="$leg2-name-enc"/>
note that anything including and behind /DoorControl.php? must stay unchanged!
  • add a Forking for the PBX user running the door operator phone towards the newly created Voicemail object
it is ok for the new Voicemail object to have no Number property, so you can target the Forking to its Name

Debugging

You can debug the retrieval of the image files using a normal brwoser. If you enter the URL to the script in to the address bar of your browser E. g. http://my.door.tld/path-on-web-server/DoorControl.php, the browser will retrieve the current image. If you add a ?debug=1 argument, as in http://my.door.tld/path-on-web-server/DoorControl.php?debug=1, you will see various debug messages instead of the picture.

Debugging the switch to video app function is a bit more tricky. You proceed as follows:

  • clear all trace flags on the PBX where the voicemail PBX object is installed
  • tick the Trace flag in the Voicemail tab of this Voicemail PBX object
  • check if the forking is configured correctly
  • look at the PBX Calls screen (or at the PBX calls logging)
  • from a door, call the door operator
  • the call should trigger a call to the Voicemail object while the door operators phone is ringing
  • obtain the PBX trace
it should look something like
The Voicemail PBX object gets call
1:1224:494:0 - vm(T):new vm=doorcall-trigger
1:1224:494:1 - script='http://172.16.100.202:8080/wiki-src/sample/DoorControl/sample/sources/switchops.xml'
it determines the name of the door operator and constructs proper arguments for the switchapp call
1:1231:137:2 - iprt.30.0(DBG):call diverting name:
1:1231:137:3 - iprt.30.0(DBG):doorOp
1:1231:137:4 - iprt.30.0(DBG):http://172.16.100.202:8080/wiki-src/sample/DoorControl/sample/sources/DoorControl.php?switchapp=1&h323=doorOp
...
1:1231:664:0 - iprt.30.1(T):running file='http://172.16.100.202:8080/wiki-src/sample/DoorControl/sample/sources/switchops.xml' ver=
finally it receives confirmation from the script that some calls have been switched
1:1231:664:1 - iprt.30.1(DBG):switchops.xml: switched 1 call(s) for door 'DoorOp'

Error: Allocation limit exceded

The filesize is too big for the Phone and will be rejected. Reduce the filesize via URI if your camera support this. (eg. image.jpg?size=640x480)
If your camera does not support the resize process, you can use the proxy-resize method described above.

Error: bad state XML

Remove state.xml from doorcontrol folder, after that you get a correct error message if you reload the Doorcontrol.php in Webbrowser

Known Problems

Wrong Caller Name

  • Forking to a VM Object without mobility object (license required) will display the name of the forking target in the caller display and his callist. (To prevent this behavior, use a mobility object for the forking to doorcall-trigger)

3rd party SOAP Application show multiple calls

Some SOAP applications show a permanent call to the doorcall-trigger, even though the agent on the desk phone has already picked up.
To turn this off, the solution must be adjusted as follows:

You have to edit the switchops.xml and add a <pbx-disc /> at the end of the function Main

 <voicemail xmlns="http://www.innovaphone.com/xsd/vm.xsd">
 <function define="Main">
   ...
   <exec url="$url"/>
   <pbx-disc />
 </function>

</voicemail>

Additional you have to update the Forking configuration of the agent, use a Mobility or UC License for the Agent and create (or use an existing) Mobility Object in your PBX.
Configure the Object and Min-Alert=1 in the forking of the agent.

Related Articles

Howto:Door Phone with Video in V10 and later