License, Copyright, and Trademark

The content contained in this repository is the intellectual property of Snap One, LLC, (formerly known as Wirepath Home Systems, LLC), and use without a valid license from Snap One is strictly prohibited. The user of this repository shall keep all content contained herein confidential and shall protect this content in whole or in part from disclosure to any and all third parties except as specifically authorized in writing by Snap One.

License and Intellectual Property Disclaimer

The content in this repository is provided in connection with Snap One products. No license, express or implied, by estoppal or otherwise, to any intellectual property rights is granted by this document or in this repository. Except as provided in Snap Oneʼs terms and conditions for the license of such products, Snap One and its affiliates assume no liability whatsoever and disclaim any express or implied warranty, relating to the sale and/or use of Snap One products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Snap One products are not intended for use in medical, lifesaving, or life sustaining applications.

Information regarding third-party products is provided solely for educational purposes. Snap One is not responsible for the performance or support of third-party products and does not make any representations or warranties whatsoever regarding the quality, reliability, functionality or compatibility of these products. The reader is advised that third parties can have intellectual property rights that can be relevant to this repository and the technologies discussed herein, and is advised to seek the advice of competent legal counsel regarding the intellectual property rights of third parties, without obligation of Snap One.

Snap One retains the right make changes to this repository or related product specifications and descriptions in this repository, at any time, without notice. Snap One makes no warranty for the use of this repository and assumes no responsibility for any errors that can appear in the repository nor does it make a commitment to update the content contained herein.

Copyright

Copyright 2024 Snap One, LLC. All rights reserved.

The above copyright notice applies to all content in this repository unless otherwise stated explicitly herein that a third-party’s copyright applies.

No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Trademarks

Snap One and Snap One Logo, Control4 and the Control4 logo, and DriverWorks are trademarks or registered trademarks of Snap One, LLC. Other product and company names mentioned in this repository may be the trademarks or registered trademarks of their respective owners.

 Derivative Works

To the extent that you create any “Derivative Work” (meaning any work that is based upon one or more preexisting versions of the work provided to you in this repository, such as an enhancement or modification, revision, translation, abridgement, condensation, expansion, collection, compilation or any other form in which such preexisting works may be recast, modified, transformed or adapted, explicitly including without limitation, any updates or changes to Snap One, LLC’s software code or intellectual property) such Derivative Work shall be owned by Snap One, LLC and all right, title and interest in and to each such Derivative Work shall automatically vest in Snap One, LLC. To the extent any Derivative Work does not automatically vest in Snap One, LLC by operation of law, you hereby assign such Derivative Work to Snap One, LLC with full title guarantee. Snap One, LLC shall have no obligation to grant you any right in any such Derivative Work.

Contact Us

Snap One, LLC 11734 S. Election Road Salt Lake City, UT 84020 USA

http://www.control4.com

Introduction

This documentation includes content that details the functions that make up the Intercom Control Proxy which is supported in the DriverWorks Software Development Kit.

Additional driver development documentation supporting intercom driver development can be found in the DriverWorks Fundamentals Guide. This includes:

Intercom Proxy Terminology

Intercom Driver Development Best Practices

Proxies (Commands)

A proxy driver is an interface to the Control4 system for a set of devices that share common functionality. For instance, most Intercom have common controls such as ACCEPT CALL, END CALL and MUTE CALL.  The intercom proxy allows for a common user interface to control all intercom systems.  The Control4 system (Director) sends information to and receives information from the proxy drivers.  The proxy drivers send information to and receives information from the protocol drivers. Remember, your DriverWorks driver interacts with the proxy driver which then interacts with the system.  As a driver developer you will be relying on this proxy to provide status (notification) to the Control4 system for the device you are controlling.  You will also receive commands from the system that you will act on to control the device.  These commands and notifications are at the heart of what you will be implementing in your driver.  Essentially your driver is becoming the go-between from the Control4 system and your device with the proxy driver giving structure to the commands and notifications which you will be implementing. Your driver can facilitate communications with multiple types of proxies for a single device. As an example, a Security System driver will utilize both the Security proxy and the Contacts proxy. These additional proxies are configured in the <connections> section of the .c4z.

Protocol (Notifications)

Two similar devices may have the same functionality but utilize a very different command set.  A protocol driver provides the device-specific information needed to communicate with the Control4 system.  In the case of DriverWorks, the DriverWorks driver is the protocol driver.  When combined with the device-specific.c4Z file it provides the custom code necessary to implement the 2-way device driver. In the case of DriverWorks, the DriverWorks driver is the protocol driver. When combined with the device-specific.c4Z file it provides the custom code necessary to implement the 2-way device driver.

What’s New

What’s New in 3.4.2

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.4.1.

What’s New in 3.4.0

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.4.0.

What’s New in 3.3.2

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.3.2.

What’s New in 3.3.1

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.3.1.

What’s New in 3.3.0

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.3.0.

What’s New in 3.2.3

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.2.3.

What’s New in 3.2.2

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.2.2.

What’s New in 3.2.1

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.2.1.

What’s New in 3.2.0

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.2.0.

What was New in 3.1.2

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.1.2.

What was New in 3.1.0

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.1.0.

There were no modifications to the Intercom Proxy in conjunction with O.S. Release 3.0.0.

Intercom Proxy Settings

Exclude from Navigator

This setting is used to control whether or not an intercom endpoint is displayed on the Navigator Landing Page. It can be used to hide endpoints from the user interface so that they can only be accessed from programming.

Do Not Disturb

This setting is used to control whether or not an intercom endpoint can receive incoming calls; it has no effect on the endpoint’s ability to make an outgoing call.

Auto Answer

This setting is used to control whether or not an intercom endpoint automatically answers incoming calls. Note that Auto Answer is ignored in the case of group calls.

Send Video

This setting is used to control whether or not an intercom endpoint automatically sends video when it starts or receives a call; if the has_camera capability is false, this setting has no effect.

Monitor Mode

This setting is used to control whether or not an intercom endpoint is in monitor mode; a monitor mode call works like a baby monitor; it will quietly auto answer the incoming call on the receiver's (monitored) endpoint, the initiator's (monitoring) endpoint is automatically muted so that there is no transmission of sound to the monitored endpoint. The initiator can un-mute the call anytime two way communications are needed. Endpoints with monitor enabled will not receive broadcast calls, even if they are specified in the call group used for the broadcast.

Monitor mode also has a feature that allows the call to be taken over by different endpoint without having to end the original call. This feature is allows the user to continue to monitor a particular endpoint as they move from one room to another.

Ringer Volume

This setting is used to control the ringer volume level of an intercom endpoint.

Speaker Volume

This setting is used to control the speaker volume level of an intercom endpoint.

Microphone Gain

This setting is used by some Control4 devices to control the microphone gain level of an intercom endpoint. Control4 intercom endpoints do not support microphone gain adjustments; this setting is provided for 3rd party use.

Camera Enabled

This setting is used to control whether or not an intercom endpoint’s camera will be used when the endpoint is in a call; if the has_camera capability is false, this setting has no effect.

AEC Enabled

This setting is used to control whether or not an intercom endpoint will use conservative auto echo cancelation (AEC) when the endpoint is in a call.

If the can_set_aec capability is false, this setting has no effect.

Play Door Chime

This setting is used to control whether or not an intercom endpoint will use the door chime sound effect when a call is received from a door station. If this setting is disabled the endpoint will ring normally when a door station call is received.

Intercom Call Commands

ACCEPT_CALL

The ACCEPT_CALL command is sent from the Intercom Proxy to the device driver. When the driver receives the ACCEPT_CALL command, it must handle the command in a manner that enables the device to accept the incoming call. When implemented successfully, receipt of the ACCEPT_CALL command is followed the CALL_ACCEPTED notification being sent from the device driver to the Proxy.

Signature

ACCEPT_CALL ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. This needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.
4. Upon call acceptance, this is followed by the device driver sending a CALL_ACCEPTED notification to the Proxy.

Returns

None

Usage Notes:

This call command can be initiated by pressing a button on a UI displayed on devices running Navigator, Control-Control in ComposerPro and Composer Programming.

END_CALL

This command only applies to an established call session. If a call has not been established – it cannot be ended. The END_CALL command is sent from the Intercom Proxy to the device driver when an established call is to be terminated. After the call is terminated, the device driver must send the CALL_ENDED notification to both the initiator and the receiver of the call.

Signature

END_CALL ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. This needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.
4. Upon call acceptance, this is followed by the device driver sending a CALL_ACCEPTED notification to the Proxy.
5. When the call is to be terminated, The END_CALL command is sent from the intercom proxy to the device driver.
6. When the device driver terminates the call (SIP BYE), the CALL_ENDED notification is sent from the driver to the Intercom proxy.

Returns

None

MUTE_CALL

This command only applies to an established call session. If a call has not been established – it cannot be muted. Likewise, a call cannot be muted when it is in a ringing state or a SIP BYE or ENDING states. The MUTE_CALL command is sent from the Intercom Proxy to the device driver. When the driver receives the MUTE_CALL command, it must handle the command in a manner that enables the device to place the existing call in a muted or un-muted state. Placing the device in a true muted state or setting the device volume to zero is supported for muting purposes. There is no associated notification for the MUTE_CALL command. The device driver must maintain the state of the call in order to un-mute or mute the call correctly

Signature

MUTE_CALL

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. This needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.
4. Upon call acceptance, this is followed by the device driver sending a CALL_ACCEPTED notification to the Proxy.
5. When the call is to be muted or un-muted, the MUTE_CALL command is sent from the intercom proxy to the device driver.

Returns

None

Example

<MUTE_CALL>
   <muteAudio>[0]</muteAudio>
</MUTE_CALL>

PAUSE_CALL

NOTE: The PAUSE_CALL command is currently deprecated and not available for use._  This command can be issued by either the initiator or receiver and causes the call associated with the indicated session to be placed on hold (or paused). This command will result in a CALL_PAUSED notification being sent to both the initiator and the receiver of the call.

Signature

PAUSE_CALL ()

Returns

None

PLAY_DOOR_ CHIME

NOTE: The PLAY_DOOR_CHIME command is currently deprecated and not available for use._ 

This command can be issued by any device to play the currently defined door chime sound effect on that device.

Signature

PLAY_DOOR_CAHIME ()

Parameters

None

Returns

None

REJECT_CALL

The REJECT_CALL command is sent from the Intercom Proxy to the device driver. When the driver receives the Reject Call command, it must handle the command in a manner that enables the device to reject the incoming call. When implemented successfully, receipt of the REJECT_CALL command should be followed by sending a CALL_REJECTED notification from the device driver to the Proxy.

Signature

REJECT_CALL ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. This needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.
4. Upon call acceptance, this is followed by the device driver sending a CALL_REJECTED notification to the Proxy.

Returns

None

Usage Notes:

This command can be initiated by pressing a button on a UI displayed on devices running Navigator, Control-Control in ComposerPro and Composer Programming.

The Reject Call command has no effect when sent during an active call session. End Call should be used in this instance.

If auto-answer is enabled, it overrides the option to reject the call and the Proxy will automatically accept it.

RESUME_CALL

NOTE: The RESUME_CALL command is currently deprecated and not available for use._  This command can be issued by an intercom device that has already paused the call associated with the indicated session id. This command will result in a CALL_RESUMED notification being sent to both the initiator and the receiver of the call.

Signature

RESUME_CALL ()

Returns

None

START_CALL

The START_CALL command is initiated through Programming or Control/Control in ComposerPro. It is sent to the Intercom Proxy, which then sends a START_CALL to the device driver. When the driver receives the START_CALL command, it must handle the command in a manner that enables the device to begin a call. When implemented successfully, receipt of the START_CALL command is followed by the CALL_ACCEPTED notification being sent from the device driver to the Proxy.

Signature

START_CALL ()

Call Flow:

1. Upon receiving a START_CALL command from the Proxy, a SIP invite is generated.
2. The SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
3. The device goes into a state of “outgoing call”.
4. This needs to trigger an Outgoing_Call notification which is sent from the device, via the device driver, to the Proxy.
5. Upon call acceptance, this is followed by the device driver that receives the call, sending a CALL_ACCEPTED notification to the Proxy.

Returns

None

START_MONITOR_CALL

The START_MONITOR_CALL command is sent from the Intercom Proxy to the device driver. When the driver receives the START_MONITOR_CALL command, it must be in monitor mode to successfully handle it. A device can be set to monitor mode via Composer Pro or Navigator. When implemented successfully, the command will result in an INCOMING_CALL notification being sent to the proxy. Note that in addition to a device being in monitor mode, it should also mute itself or turn volume level to zero when receiving the START_MONITOR_CALL. This ensures that no sounds come from the receiving device. This is useful in the case where a device is being used as a baby monitor.

Signature

START_MONITOR_CALL ()

Call Flow:

1. START_MONITOR_CALL command is sent from the intercom proxy to the device driver.
2. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
3. The device goes into a state of “incoming call”.
4. This needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.
5. Because the device receiving the call is in monitor mode, the call is automatically accepted.
6. Upon call acceptance, this is followed by the device driver sending a CALL_ACCEPTED notification to the Proxy.

Returns

None

Intercom Call Requests

GET_DEVICE

This request is issued to obtain the device properties of a specified intercom endpoint.

Signature

GET_DEVICE ()

Example

<GET_DEVICE>
  <idDevice>[integer value]</idDevice>
</GET_DEVICE>

Response Parameters

Response Prototype

<device_props id=”[integer value]”>
    <proxyId>[integer value]</proxyId>
    <protocolId>[integer value]</protocolId>
    <hasCamera>[integer value]</hasCamera>
    <hasDisplay>[integer value]</hasDisplay>
    <hasButtons>[integer value]</hasButtons>
    <isDoorStation>[integer value]</isDoorStation>
    <displayName>[string value]</displayName>
    <sipUserName>[string value]</sipUserName>
    <sipAOR>[string value]</sipAOR>
</device_props>

GET_DEVICE_LIST

This request is issued to obtain the device properties of all of the intercom endpoints in the project.

Signature

GET_DEVICE_LIST ()

Parameters

None

Response Parameters

Response Prototype

<device_list>
   <device_props id=”Id1”>
    [see the GET_DEVICE response format]
   </device_props>
   <device_props id=”Id2”>
    [see the GET_DEVICE response format]
   </device_props>
   <device_props id=”IdN”>
    [see the GET_DEVICE response format]
   </device_props>
</device_list>

GET_SESSION

This request is issued to obtain the active session information for the requesting device.

Signature

GET_SESSION ()

Parameters

None

Response Parameters

Response Prototype

<device_session id=”[integer value]”>
   <sessionId>[integer value]</sessionId>
   <videoMode>[integer value]</videoMode>
   <audioMode>[integer value]</audioMode>
   <callerDevId>[integer value]</callerDevId>
   <callerName>[string value]</callerName>
   <calleeDevId>[integer value]</calleeDevId>
   <calleeName>[string value]</calleeName>
</device_session>

GET_SESSION_LIST

This request is issued to obtain the session information of all of sessions on this endpoint.

Signature

GET_SESSION_LIST ()

Parameters

None

Response Parameters

Response Prototype

<session_list>
  <device_session id=”Id1”>
   [see the GET_SESSION response format]
  </device_session>
  <device_session id=”Id2”>
   [see the GET_SESSION response format]
  </device_session>
  <device_session id=”IdN”>
   [see the GET_SESSION response format]
  </device_session>
</session_list>

GET_TIMEOUT

This request is issued to obtain the current timeout setting for manually answering a call. If the timeout duration expires before a call is answered, the call is automatically ended. This value is configured in the Video Intercom Agent in Composer.

Signature

GET_TIMEOUT ()

Parameter

None

Response Parameters

Response Prototype

<timeout>
  <value>[integer value]</value>
</timeout>

Intercom Call Notifications

CALL_ACCEPTED

The CALL_ACCEPTED notification is generated by the device driver and sent to the intercom proxy when a call is accepted.

Signature

CALL_ACCEPTED ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. Upon entering this state, the device driver needs to trigger an INCOMING_CALL notification which is sent from the device to the intercom proxy.
4. Upon answering the call, the CALL_ACCEPTED notification is sent to the intercom proxy.

Returns

None

CALL_ENDED

The CALL_ENDED notification is generated by the device driver and sent to the intercom proxy when a call session is ended. After a SIP call is ended, any device participating in the call should send CALL_ENDED notification.

Signature

CALL_ENDED ()

Usage Notes:

The CALL_ENDED notification is only applicable to devices that are active in an answered, call session. For example, in the case of a group call, the CALL_ENDED notify is sent only by the device that was participating in the call. Other devices in the call list should sent a CALL_REJECTED to the proxy.

CAMERA_ENABLED_CHANGE

Notification sent to the proxy when the camera enabled value of the intercom has changed

Signature

CALL_ENABLED_CHANGE ()

CALL_PAUSED

NOTE: The CALL_PAUSED notify is currently deprecated and not available for use.\

This notification is issued when a session is paused, it is sent to the initiator and all receiver(s) involved in the specified session.

Signature

CALL_PAUSED ()

CALL_REJECTED

The CALL_REJECTED notification is generated by the device driver and sent to the intercom proxy when a call is rejected.

Signature

CALL_REJECTED ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “incoming call”.
3. Upon entering this state, the device driver needs to trigger an INCOMING_CALL notification which is sent from the device to the intercom proxy.
4. Upon answering the call, the CALL_REJECTED notification is sent to the intercom proxy indicating that the device did not answer the call.

Returns

None

Usage Notes:

The CALL_REJECTED notification is only applicable to devices that are NOT active in a call session. For example, in the case of a group call, the CALL_REJECTED notify is sent only by the device or devices that did not participate in the call. Other devices in the call list that answered the call, should sent a CALL_ENDED to the proxy.

CALL_RESUMED

NOTE: The CALL_RESUMED notify is currently deprecated and not available for use._

This notification is issued when a session is resumed, it is sent to the initiator and all receiver(s) involved in the specified session.

Signature

CALL_ RESUMED ()

INCOMING_CALL

The INCOMING_CALL notification is generated by the device driver upon receiving the invitation to a call from SIP. This notification is sent to the Intercom Proxy.

Signature

INCOMING_CALL ()

Call Flow:

1. A SIP invite to a call is received by the device via the device driver and the device enters a ringing state.
2. The device goes into a state of “Incoming call”.
3. Upon entering this state, the device driver needs to trigger an Incoming_Call notification which is sent from the device, via the device driver, to the Proxy.

Returns

None

OUTGOING_CALL

The OUTGOING_CALL notification is generated by the device driver and sent to the intercom proxy when a call invite is SENT. This notification is sent to the Intercom Proxy.

Signature

OUTGOING_CALL ()

Call Flow:

1. A SIP invite to a call is sent by the device.
2. The device goes into a state of “outgoing call”.
3. Upon entering this state, the device driver needs to trigger an Outgoing_Call notification which is sent from the device driver to the Proxy.

Returns

None

Intercom State Commands

SET_CAMERA_ENABLE

This command is issued to enable or disable the camera on an intercom device.

Signature

SET_CAMERA_ENABLE ()

Returns

None

Example

<SET_CAMERA_ENABLE>
    <cameraEnable>[true]</cameraEnable>
</SET_CAMERA_ENABLE>

SET DND

This command is issued to toggle the “Do Not Disturb” setting of the intercom.

Signature

SET_DND ()

Returns

None

Example

<SET_DND>
   <dndSettingd>[true]</dndSetting>
</SET_DND>

SET_EXCLUDE_FROM_NAVIGATOR

This command is issued to toggle the visibility of the intercom endpoint in a proxy user interface. This command will result in an EXCLUDE_FROM_NAVIGATOR_CHANGED notification to the proxy.

Signature

SET_EXCLUDE_FROM_NAVIGATOR ()

Returns

None

Example

<SET_EXCLUDE_FROM_NAV>
   <excludeFromNav>[1]</excludeFromNav>
</SET_EXCLUDE_FROM_NAV>

SET_SEND_VIDEO

This command is issued by a proxy consumer to cause the state of the send video setting to change. This command will result in a SEND_VIDEO_CHANGED

Signature

SET_SEND_VIDEO ()

Returns

None

Example

<SET_SEND_VIDEO>
   <sendVideo>[1]</sendVideo>
</SET_SEND_VIDEO>

SET_MICROPHONE_GAIN

This command is issued by a proxy consumer to cause the microphone gain for the indicated intercom device to change. This command will result in a MICROPHONE_GAIN_CHANGED notification to the indicated device.

Signature

SET_MICROPHONE_GAIN ()

Returns

None

Example

<SET_MICROPHONE_GAIN>
    <microphoneGain>[0]</microphoneGain>
</SET_MICROPHONE_GAIN>

SET_MONITOR_MODE

This command will result in a MONITOR_MODE_CHANGED notification to the proxy consumer for the indicated intercom device.

Signature

SET_ MONITOR_MODE ()

Returns

None

Example

<SET_MONITOR_MODE>
    <monitorMode>[0]</monitorMode>
</SET_MONITOR_MODE>

SET_RINGER_VOLUME

This command is issued to cause the ringer volume setting to be changed for the indicated intercom device. This command will result in a RINGER_VOLUME_CHANGED notification to the proxy consumer for the indicated intercom device.

Signature

SET_RINGER_VOLUME ()

Returns

None

Example

<SET_RINGER_VOLUME>
   <ringerVol>[1]</ringerVol>
</SET_RINGER_VOLUME>

SET_SPEAKER_VOLUME

This command is issued by a proxy consumer to cause the current speaker volume setting to be changed. This command will result in a SPEAKER_VOLUME_CHANGED notification to the proxy consumer for the indicated intercom device.

Signature

SET_SPEAKER_VOLUME ()

Returns

None

Example

<SET_SPEAKER_VOLUME>
   <speakerVol>[50]</speakerVol>
</SET_SPEAKER_VOLUME>

Intercom State Requests

GET_CURRENT_STATE

This request is issued to obtain the current device state of the intercom endpoint making the request. Upon receiving the request, the driver should issue a CURRENT_STATE_CHANGED notify.

Signature

GET_CURRENT_STATE ()

Request Parameters

None

Response Parameters

Response Prototype

<device_state proxyid=”[10]”>
   <currentState>[2]</currentState>
</device_state>

GET_STATE

This request is issued to obtain the device state of a specified intercom endpoint.

Signature

GET_STATE ()

Request Prototype

See example to the right.

<GET_STATE>
   <idDevice>[17]</idDevice>
</GET_STATE>

Response Parameters

Response Prototype

<device_state proxyid=”[integer value]”>
   <excludeFromNav>[integer value]</excludeFromNav>
   <playDoorChime>[integer value]</playDoorChime>
   <dndSetting>[integer value]</dndSetting>
   <autoAnswer>[integer value]</autoAnswer>
   <currentState>[integer value]</currentState>
   <sendVideo>[integer value]</sendVideo>
   <monitorMode>[integer value]</monitorMode>
   <ringerVol>[integer value]</ringerVol>
   <speakerVol>[integer value]</speakerVol>
   <microphoneGain>[integer value]</microphoneGain>
   <showMainVideo>[integer value]</showMainVideo >
   <showMirrorVideo>[integer value]</showMirrorVideo >
   <cameraEnabled>[integer value]</cameraEnabled >
   <aecEnabled>[integer value]</aecEnabled >
</device_state> 

GET_STATE_LIST

This request is issued to obtain the device state of all of intercom endpoints in the project

Signature

GET_STATE_LIST ()

Request Prototype

See example to the right.

<state_list>
   <device_state id=”Id1”> 
     See GET_STATE response format
   </device_state>
   <device_state id=”Id2”> 
     See GET_STATE response format
   </device_state>
   <device_state id=”IdN”> 
     See GET_STATE response format
  </device_state>
</state_list>

Intercom State Notifications

AUTO_ANSWER_CHANGED

This notification is issued when a call is accepted, it is sent to the initiator and the receiver involved in accepting the specified session.

Signature

AUTO_ANSWER_CHANGED ()

Example

<device_state id=[10]>
   <autoAnswer>[1]</autoAnswer>
</device_state>

CAMERA_ENABLED_CHANGED

This notification is issued by the protocol when the endpoint’s Camera Enabled setting has changed.

Signature

CAMERA_ENABLED_CHANGED ()

Example

<device_state id=[10]>
   <cameraEnabled>[1]</cameraEnabled>
</device_state>

CURRENT_STATE_CHANGED

This notification is issued by the protocol when the endpoint’s current state has changed.

Signature

CURRENT_STATE__CHANGED ()

Example

<device_state proxyid =[10]>
   <currentState>[2]</currentState>
</device_state>

DEVICE_STATE_CHANGED

This notification is issued by the protocol when the endpoint’s current state has changed.

Signature

DEVICE_STATE__CHANGED ()

Example

<DEVICE_STATE_CHANGED>
   <excludeFromNav>[1]</excludeFromNav>
   <playDoorChime>[0]</playDoorChime>
   <dndSetting>[0]</dndSetting>
   <autoAnswer>[0]</autoAnswer>
   <sendVideo>[1]</sendVideo>
   <currentState>[3]</currentState>
   <monitorMode>[1]</monitorMode>
   <ringerVol>[50]</ringerVol>
   <speakerVol>[70]</speakerVol>
   <microphoneGain>[35]</microphoneGain>
   <showMainVideo>[1]</showMainVideo>
   <showMirrorVideo>[1]</showMirrorVideo>
   <cameraEnabled>[0]</cameraEnabled>
   <aecEnabled>[1]</aecEnabled>
</DEVICE_STATE_CHANGED

DEVICE_STATE_CHANGED

This notification is issued by the protocol when the endpoint’s Do Not Disturb setting has changed.

Signature

DND_CHANGED ()

Example

<device_state proxyid =[10]>
    <dndSetting>[1]</dndSetting>
</device_state>

EXCLUDE_FROM_NAVIGATOR_CHANGED

This notification is issued by the protocol when the endpoint’s Exclude from Navigator setting has changed.

Signature

EXCLUDE_FROM_NAVIGATOR_CHANGED ()

Example

<device_state proxyid =[10]>
    <excludeFromNav>[0]</excludeFromNav>
</device_state>

MICROPHONE_GAIN_CHANGED

This notification is issued by the protocol when the endpoint’s Microphone Gain setting has changed.

Signature

MICROPHONE_GAIN_CHANGED ()

Example

<device_state proxyid =[10]>
    <microphoneGain>[0]</microphoneGain>
</device_state>

MONITOR_MODE_CHANGED

This notification is issued by the protocol when the endpoint’s Monitor Mode setting has changed.

Signature

MONITOR_MODE_CHANGED ()

Example

<device_state proxyid =[10]>
    <monitorMode>[0]</monitorMode>
</device_state>

MUTE_AUDIO_CHANGED

Notification sent to the protocol when the audio muted value of the intercom has changed.

Signature

MUTE_AUDIO_CHANGED ()

RINGER_VOLUME_CHANGED

This notification is issued by the protocol when the endpoint’s ringer volume setting has changed.

Signature

RINGER_VOLUME_CHANGED ()

Example

<device_state proxyid =[10]>
    <ringerVoL>[0]</ringerVoL>
</device_state>

SIP_USERNAME_CHANGED

Notification sent to the protocol when the SIP username value of the intercom has changed.

Signature

SIP_USERNAME_CHANGED ()

SEND_VIDEO_CHANGED

This notification is issued by the protocol when the endpoint’s Monitor Mode setting has changed.

Signature

SEND_VIDEO_CHANGED ()

Example

<device_state proxyid =[10]>
    <sendVideo>[0]</sendVideo>
</device_state>

SPEAKER_VOLUME_CHANGED

This notification is issued by the protocol when the endpoint’s Speaker Volume setting has changed.

Signature

SPEAKER_VOLUME_CHANGED ()

Example

<device_state proxyid =[10]>
    <speakerVol>[0]</speakerVol>
</device_state>

USE_CAMERA_CHANGED

Notification sent to the protocol when the use camera value of the intercom has changed.

Signature

USE_CAMERA_CHANGED ()

Intercom Call Group Requests

GET_GROUP_LIST

This request is issued to obtain the group list of all of intercom call groups in the project except for the “All” group.

Signature

GET_GROUP_LIST ()

Example

<groups>
  <group>
   <id>[3]</id>
   <name>[group one]</name>
  </group>
  <group>
    <id>[4]</id>
    <name>[group two]</name>
  </group>
</groups>

Intercom Capabilities

has_play_door_chime

Device supports the ability to play a secondary door chime inanition to the default door chime. This is primarily intended for playing a secondary door chime on Control4 touch panels.

Signature

<has_play_door_chime></has_play_door_chime> 

Example

<capabilities>
   <has_play_door_chime>false</has_play_door_chime>
</capabilities>

has_camera

The device includes a camera and supporting camera functionality. This controls enabling/disabling the use of the Send Video UI in ComposerPro.

Signature

<has_camera></has_camera>

Example

<capabilities>
   <has_camera>True</has_camera>
</capabilities>

has_display

Device includes a physical display. Typically a door station has a display where a touch panel may not. Setting this to True enables the device to receive incoming video.

Signature

<has_display></has_display>

Example

<capabilities>
   <has_display>True</has_display>
</capabilities>

has_buttons

This capability specifies whether this device type has custom buttons. Its value is a Boolean string. For example: “True” or “False”

Signature

<has_buttons></has_buttons>

Example

<capabilities>
   <has_buttons>True</has_buttons>
</capabilities>

is_doorstation

This capability specifies whether this device type is a door station. Its value is a Boolean string. For example: “True” or “False”

Signature

<is_doorstation></is_doorstation>

Example

<capabilities>
   <is_doorstation>True</is_doorstation>
</capabilities>

driver_arch_type

This capability is included in the SDK for Control4 internal use. It is used to determine if the driver file is a Control4 driver or a third party driver. Third party driver developers must pass a value of 5 in this capability.

Signature

<driver_arch_type></driver_arch_type>

Example

<capabilities>
   <driver_arch_type>5</driver_arch_type>
</capabilities>

has_auto_answer

A setting of True indicates that the device supports the ability to automatically answer an incoming call. Setting this capability to True will also enable the use of the has auto answer checkbox in ComposerPro.

Signature

<has_auto_answer></has_auto_answer> 

Example

<capabilities>
   <has_auto_answer>false</has_auto_answer>
</capabilities>

has_do_ not_disturb

Device supports do not disturb functionality. Setting this to true will enable the use of the Do Not Disturb checkbox in ComposerPro.

Signature

<has_do_not_disturb></has_do_not_disturb> 

Example

<capabilities>
   <has_do_not_disturb>true</has_do_not_disturb>
</capabilities>

has_early_media

Device supports delivery of SIP Early Media. Early media is the preview video and or audio distributed prior to a call being answered. Currently, this is only supported in door stations.

Signature

<has_early_media></has_early_media> 

Example

<capabilities>
   <has_early_media>true</has_early_media>
</capabilities>

has_monitor_mode

Device supports the use of display monitor functionality. Setting this to true will also enable the use of the Monitor Mode checkbox in ComposerPro.

Signature

<has_monitor_mode></has_monitor_mode> 

Example

<capabilities>
   <has_monitor_mode>true</has_monitor_mode>
</capabilities>

use_microphone

The driver has the ability to physically control the microphone level on the device.

Signature

<use_microphone></use_microphone> 

Example

<capabilities>
   <use_microphone>true</use_microphone>
</capabilities>

use_speaker

The driver has the ability to physically control the speaker level on the device.

Signature

<use_speaker></use_speaker> 

Example

<capabilities>
   <use_speaker>true</use_speaker>
</capabilities>

use_ringer

The driver has the ability to physically control the ringer level on the device.

Signature

<use_ringer></use_ringer> 

Example

<capabilities>
   <use_ringer>true</use_ringer>
</capabilities>

has_high_definition

Capability applicable to touch panels. The driver has the ability to turn camera video quality to 720p, as opposed to 640x480.

Signature

<has_high_definiton></as_high_definiton> 

Example

<capabilities>
   <has_high_definiton>true</has_high_definiton>
</capabilities>

has_echo_calibration

This capability is included in the SDK for Control4 internal use.

Signature

<has_echo_calibration></has_echo_calibration> 

Example

<capabilities>
   <has_echo_calibration>false</has_echo_calibration>
</capabilities>

audio_codecs_supported

This Capability has been deprecated and is no longer applicable to driver development efforts. 

has_intercom

This Capability has been deprecated and is no longer applicable to driver development efforts. 

has_video_intercom

This Capability has been deprecated and is no longer applicable to driver development efforts. 

has_mcast_emedia

This Capability has been replaced and is no longer applicable to driver development efforts. 

For more information see the has_early_media capability.

can_change_multicast_ip

This Capability has been deprecated and is no longer applicable to driver development efforts. 

can_change_transport

This Capability has been deprecated and is no longer applicable to driver development efforts. 

video_codecs_supported

This Capability has been deprecated and is no longer applicable to driver development efforts. 

can_set_aec

This Capability has been deprecated and is no longer applicable to driver development efforts. 

number_ring_buttons

This capability is included in the SDK for Control4 internal use.

can_detect_button_press

This capability is included in the SDK for Control4 internal use.

can_detect_button_release

This capability is included in the SDK for Control4 internal use.

Intercom Events

Intercom Events are tied to programming in ComposerPro. Events are also recored in history and can be used to trigger notifications using the History Agent.

For example, it’ possible to trigger a notification on a mobile phone based on an incoming call (Incoming Call Event) that occurs on a door station or any other device in the project that uses the Intercom Proxy.

Intercom Events

The following Events are supported by the Intercom Proxy. They include:

Incoming Call Fired when there is a new incoming call.

Outgoing Call Fired when there is a new outgoing intercom call.

Call SetupFired when a new call is setup.

Call Accepted Fired when an incoming call is accepted by the receiver.

Call Rejected Fired when an incoming call is rejected by the receiver.

Call Started Fired when there is new call session is started.

Call Ended Fired when an existing call session is ended

Call Paused Fired when an existing call session is paused.

Call Resumed Fired when an existing call session is resumed.

Do Not Disturb Changed Fired when the “Do Not Disturb” setting is changed.

Auto Answer Changed Fired when the “Auto Answer” setting is changed.

Monitor Mode Changed Fired when the “Monitoring” setting is changed.

Send Video Changed Fired when the “Send Video” setting is changed.

Ringer Volume Changed Fired when the “Ringer Volume” setting is changed.

Speaker Volume Changed Fired when the “Speaker Volume” setting is changed.

Microphone Gain Changed Fired when the “Microphone Gain” setting is changed

Custom Button N Pressed Fired when the “Custom Button N” is pressed. (where N = 0 or 1)

Custom Button N Released Fired when the “Custom Button N” is released. (where N = 0 or 1)

Intercom Variables

Intercom Variables

The following Variables are supported by the Intercom Proxy itself. They include:

CALL_DURATION - This variable supports ComposerPro programming based on a set call duration time.

MICROPHONE_GAIN - This variable supports ComposerPro programming based on a change to the microphone’s gain level.

RINGER_VOLUME - This variable supports ComposerPro programming based on a change to the device’s ringer volume level.

SPEAKER_VOLUME - This variable supports ComposerPro programming based on a change to the device’s speaker volume level.

Intercom Conditionals

Intercom Conditionals

The following Conditionals are supported by the Intercom Proxy itself. They include:

Remote Name Matched Returns true if there is an incoming/outgoing call to a specified endpoint.

Do Not Disturb Returns true if “Do Not Disturb” is enabled on the current endpoint.

Auto Answer Returns true if “Auto Answer” is enabled on the current endpoint.

Send Video Returns true if “Send Video” is enabled on the current endpoint.

Monitor Mode Returns true if “Monitoring” is enabled on the current endpoint.

In A Call Returns true if there is an active session on the current endpoint.