Using the Room Controls feature of Zoom Room, you can control third-party IP-capable equipment in your Zoom Room, allowing the user to control the equipment through the Zoom Room control panel. In order to add outgoing IP control messages from Zoom Rooms, admins need to create a configuration profile for this purpose.

The following are the topics covered in this article:

• Enabling Room Controls
• Writing a Room Controls Profile
  • Getting Started
  • Adapters
  • Styles
  • Rules
  • Response Filters
• Using Room Controls
• Troubleshooting
  • Room Control Errors
  • Sample Files

Prerequisites for Room Controls

• If you would like to purchase Zoom Rooms for Mac OS or Windows or Zoom Rooms Appliances versions 5.1 or higher please click here
• Devices controlled by third parties via LAN or WLAN that can be controlled by third parties
  • If there is no native LAN or WLAN connection on the device, use the iTach network adapter (IP2SL/IP2CC or wifi equivalent)

Enabling Room Controls

In order to upload a JSON configuration profile, the Zoom Rooms settings must first be enabled before you can upload it. Zoom Rooms allows you to configure this at any level in the hierarchy of the Zoom Rooms system.

1. Using Zoom’s web portal, you will be able to sign in.
2. You can select Zoom Rooms from Room Management by clicking the Zoom Rooms button.
3. The Zoom Room name can be edited by clicking on the Edit button to the right of it.
4. The Enable Room Controls toggle should be toggled on (blue) in the Devices section.
5. In the Create Profile window, click the Create Profile button.
6. For this room, you will need to enter the configuration JSON file.

Writing a Room Controls profile

Getting Started

Before writing a Room Controls Profile, it is necessary to have a basic understanding of JSON in order to complete the task. Among the most important things to take into account with JSON is that it is a key-value pair-based system, and that syntax is crucial for ensuring that files are arranged correctly. If you are interested in learning more about the basic concepts of JSON, you may wish to consult an online introduction course.

Whenever you code in any language, you should extend some courtesy to the person who will be handling your next file. The Zoom Rooms Native Room Controls do not have any specific requirements with regard to this, but it is still highly recommended that you do. You can use the ‘about’ object in order to record the author, the version, as well as any other history of the adapter, and place it above the ‘adapters’ object. In the portal, this information is stored, but is not parsed by Room Controls.  In the example below, you can see how this could be leveraged to benefit your organization.

{
"about": {
"type": "Medium Conference A",
"version": "v1.2.4",
"design_ref": "\\files\MediumConfA",
"created": "Mon, 21 Oct 2020 16:35:52 GMT"
},

Adapters

As soon as the adapters are set up, Room Controls can be connected to devices. The primary purpose of this section is to configure the software. There should be a similar format for each device contained within the nested JSON format (shown below is an example nested inside the code example below), which is:

• Adapters: The adapters are responsible for defining the connection between each device
  • Model: There are three types of models available, the generic network adapter, the IP2CC, and the IP2SL.  Below you will find more details regarding this.
  • IP: There are two parts to this address: the IP address and the port number of the network device
  • • NOTE:
    • As part of the current version of the software, the Room Controls now support hostnames in addition to IP addresses
  • UUID: As far as Global Cache devices are concerned, this feature is only mandatory and follows the “GlobalCache_[MAC]” format.
  • Ports: In the case of a connection, a port defines the device that is connected to the connection
  • • ID: As a code name, this is what the device is called.  A JSON variable should be formatted in accordance with the JSON specification
    • Name: There will be a friendly name displayed on the interface for your users to use
    • Methods: There are a number of methods that define the different sections of the user interface
    • • ID: It is the ID of the control type which is called in code (specific to the type of control) to identify the control.
      • Name: The user-accessible name for Zoom Rooms is the one that appears on the interface of Zoom Rooms
      • Command: Depending on the type of action, this could either be the entire command or the parts of the command string that are shared by the full command
      • • NOTE: The action type for the command string should be % when the action type is ‘actions’ in order to be able to insert elements inside the parameters of the command string
      • Params: Only the ‘actions’ type is used in this section. It contains the elements that can be rolled up to the parent command when used with the ‘actions’ type.
      • • ID: A programming ID is a number that is called in code when a particular program is being run
        • Name: On the Room Controls Button, there will be a text that can be accessed by the user
        • Value: As the name suggests, this is the section of the parent command that contains the commands.  Using ‘POWR000%//x0D’ as a parent command, an example of this could be to include ‘0’ for Off or ‘1’ for On with some Sharp Displays in the parent command.

{
"adapters": [
            {
            "model": "iTachIP2SL",
            "ip": "[IP_ADDRESS]",
            "uuid": "GlobalCache_[UNIT_MAC_ADDRESS]",
            "ports": [
                     {
                     "id": "sl_sharp_tv",
                     "name": "Sharp Display",
                     "settings": {
                     "baud_rate": "38400",
                     "flow_control": "FLOW_NONE",
                     "parity": "PARITY_NO"
                     },
                     "methods": [
                                {
                                "id": "power",
                                "name": "Power",
                                "command": "POWR000%\\x0D",
                                "params": [
                                          {
                                          "id": "displayOn",
                                          "name": "On",
                                          "value": "0001"
                                          },
                                          {
                                          "id": "displayOff",
                                          "name": "Off",
                                          "value": "0000"
                                          }
                                          ],
                                "type": "actions" 
                                },
...

There is an additional section that can be used underneath the ‘methods’ section: “response_filter”. There is a Response Filter that serves as a beacon, allowing the Response Filters in the list below to be able to understand which connection they need to monitor. In this area, there are no functions that have been defined. We will cover in more detail the role that a Response Filter plays within other sections of this document.

Styles

Your interface elements are styled according to the styles that you apply to them. There are not a lot of adjustments to be made, so learning how to do them isn’t very challenging.

In the interface, there are a number of icons available for you to choose from. There are a wide variety of air conditioners and speakerphones available in these stores. Icons in the list below represent the current status of this list, but it is being updated on a regular basis.

Device	Name	Image
air conditioner	icon_air_conditioner
cable TV	icon_cable_tv
ceiling mic	icon_ceiling_mic
curtain	icon_curtain
DVD Player	icon_dvd_player
Xbox/PS4 System	icon_game_console
HDMI	icon_hdmi
laptop	icon_laptop
light	icon_light
projector	icon_projector
rack equipment	icon_rack_equipment
satellite dish	icon_satellite_dish
speaker	icon_speaker
speakerphone	icon_speakerphone
TV	icon_tv
power	icon_power
up	icon_up
down	icon_down
cold	icon_cold
hot	icon_hot
dry	icon_dry
wind	icon_wind

Icons (as discussed above), Main Methods, and Visibility are the three primary modifiers within styles that we will discuss in more detail below.

An icon is a visual representation of how the system works. The texts can either be used to mark a device or to replace text associated with a button so that the device can be marked. As you can see in the example below, we have defined a device called ‘example’ in order to demonstrate this.

{
"adapters": [
            {
            "model": "ExternalControlSystem",
            "ip": "tcp://[USER_IP_ADDRESS]:[USER_PORT]",
            "ports": [
                     {
                     "id": "example",
                     "name": "Example Device",
                     "methods": [
...

In order to make use of the ID of the device, we must define ‘example’ as a device on the page.  In our example device, for instance, we can easily set the main icon to be a light, by simply changing the settings for the device.

"styles": [
          "example.icon=icon_light",
          "example.main_method=power"
          ]

The fact that we have defined the Main Method within a single line is also something you should be aware of.  A main method extracts the referenced command that you have defined from the device’s title bar so that it can be displayed prominently in the device’s title bar as shown in the following example:

The power command has been defined as the main method, which is why it is displayed separately from all the other commands in the upper bar.

Lastly, there is the Visibility style type. It allows the programmer to define a function and hide it completely from the User’s Interface by using the visibility feature of the language. It is just as easy to define it as follows:

"example.power.invisible=true"

The format of “device.command.invisible=true” can be used in order to hide the Rooms User from seeing the contents of this command.

Rules

The rules of Room Controls are the engine that automates the whole system. It is in this area where it is defined what happens on its own when things happen on their own. I could for example use “meeting_started” and “meeting_ended” (stock Zoom events) as functions to let my display only be active during meetings, for example, if I wanted it to only be displayed when meetings are in progress.

"rules": {
          "meeting_started": [
                             "display.power.on",
                             "camera.power.wake"
                             ]
          ),
          "meeting_ended": [
                           "display.power.off"
                           ]
          }

It is possible to reduce your system’s power consumption by using this example.

It is also possible to stack multiple commands per rule if one command is not enough. We will consider these events simultaneous even though technically the events fire sequentially. Nonetheless, they process fast enough that we will consider them sequential. To activate my camera when my display is powered on, “camera.power.wake” is added below “display.power.on”to make sure that my camera is activated when my display lights up.

In today’s rules, there are a couple of Zoom commands that are available that are straightforward:

• Meeting Events
  • “meeting_started”
  • “meeting_stopped”
• Audio Events
  • “microphone_muted”
  • “microphone_unmuted”
• Video Events
  • “video_started” (camera unmuted)
  • “video_stopped” (camera muted)
• Admin Events
  • “operation_time_started”
  • “operation_time_ended”

Note: The Zoom Rooms settings page allows you to set the operating hours for the room.

Adding your own Response Filters is also a simple process that you can do. The Trigger Events, which are discussed below, can also be used in the rules section to enable you to drive your own automation with inputs from outside the rules section.

"rules":{
        "operation_time_started":[
                                "light.power.on"
                                ],
        "user_customized_event1":[
                                "light.power.off"
                                 ]
         }

The “user_customized_event1” in this example is a custom event that triggers the control light to be turned off. The room could be sent an update by a third-party system, like a booking system, telling the room that no users checked in for the meeting, or it might be driven by an input from a button or even a motion sensor going inactive. This feature can be used in a number of ways, but the number of ways is mainly dependent on your imagination.

Response Filters

As part of Zoom Rooms Native Room Controls, Response Filters enable a powerful enhancement to the functionality of the room controls. In such a filter, messages sent by defined devices are read back and instantaneously matched with phrases originating from the devices. The Rules Trigger Event (described above) is triggered whenever this phrase (or expression) is identified as matching one of those on that connection.

There are three elements that make up each Response Filter, and they are as follows:

• “name”: “Ports” is the section of “methods” where the name of the method is used. When the response filter matches the name of the port in the “ports” area, then the defined connection will be spanned by the response filter.
• “filter_regex”: As soon as the Response Filter is applied to a request, the regex (or regular expression) will be the set of characters that it anticipates to match. There will be an activation of the trigger_event if a match occurs between the two
• “trigger_event”: In the rules section of the document, the Trigger Event is used to trigger a sequence of events. This Trigger Event will trigger a series of automations to happen as soon as the “filter_regex” activation in Rules is achieved

Using Room Controls

In order to access these added features, simply tap the Room Controls icon on the Zoom Rooms controller.

If you are not in a meeting, you will be able to find the Room Controls icon in the main menu when you are not in a meeting.

It is also possible to display the same Room Controls while a meeting is ongoing by tapping the icon at the top right corner of the controller window.

Troubleshooting

When it comes to custom configurations, troubleshooting plays a crucial role. The Room Control software can be simple to use, but it also has the flexibility to be complex when needed. There are some sections below that may be helpful in resolving potential roadblocks that you may encounter.

Room Control Errors

Error Code	Description
No_Config_Error	JSON Profile is not loaded in web portal
Json_Syntax_Error	JSON Profile contains a syntax error
Json_Config_Error	JSON Profile contains a configuration error
IP_Error	There is an issue connecting to a specified IP
IP_Is_Public	Public IPs are not allowed at this time
DeviceID_Error	One or more Device IDs are incorrectly set
MethodID_Error	One or more methods are incorrectly defined
ParamID_Error	One or more parameters are incorrectly defined
IP2SL_Settings_Error	Serial Port incorrectly configured on GC IP2SL
Empty_Device_Error	One or more devices are called without being defined in the JSON Profile
Unknown	An unknown error has occurred

Sample Files

I have collected these files from a variety of sources, but they should only be used as a starting point for further research. In order to make the application fit your needs, you may need to make some modifications.

• Generic Files
  • Zoom Room Control JSON Profile
  • Zoom Room control JSON profile with additional comments
  • Generic Lighting JSON Profile (Relay)
  • Generic Lighting JSON Profile (Serial)
• Avocor
  • JSON Profile (IP)
• Middle Atlantic
  • Racklink JSON Profile (IP)
• Shure
  • MXA910 JSON Profile (IP)