The Zoom Community is here!
We welcome all Zoom customers to come together on the Zoom Community to ask questions, find solutions,
and collaborate with peers. Login with your Zoom account credentials and start collaborating!

Room Controls Follow

Overview

The Room Controls feature allows you to control third-party, IP-capable equipment so that the equipment can be controlled by the user through the Zoom Room controller. Admins can create a configuration profile to add outgoing IP control messages from Zoom Room.

This article covers: 

Prerequisites

  • Zoom Rooms for macOS or Windows or Zoom Rooms Appliances, version 5.1 or higher
  • Third-party devices controllable by LAN or WLAN
    • iTach network adapter (IP2SL/IP2CC or wifi equivalent), if the device does not have native LAN or WLAN access

Configuration

Enabling Room Controls

Before you can upload a JSON Configuration Profile, the setting will need to be enabled for Zoom Rooms.  This can be configured at any level of the Zoom Rooms hierarchy.

  1. Sign in to the Zoom web portal.
  2. Click Room Management, then select Zoom Rooms.
  3. Click Edit to the right of the Zoom Room name.
  4. Under Devices, toggle Enable Room Controls to on (blue). 
  5. Click Create Profile.
  6. Enter the JSON configuration for this room. 

Writing a Room Controls Profile

Getting Started

Before writing a Room Controls Profile, some working knowledge of JSON is needed.  The key items to note are that JSON is a key:value pair-based system and that syntax is important to correctly lay out the file.  For additional information on the basics of JSON, consult an online intro course.

In any coding language, some courtesy should be extended to the next person that handles your file.  While there is no specific requirement around this for Zoom Rooms Native Room Controls, it is recommended.  To leave a record of the author, version, or other history, the 'about' object can be used and placed above 'adapters'.  This is not parsed by Room Controls, but will persist in the portal.  An example of how this could be leveraged is below.

 

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

 

Adapters

Setting up the adapters connects Room Controls to devices. This section is the primary section for configuration.  Individual devices inside the nested JSON format should follow a similar format (this example is nested to parallel the code example below):

  • Adapters: Adapters defined the individual device connections
    • Model: Models can be "GenericNetworkAdapter", "IP2CC", and "IP2SL".  More details below.
    • IP: this is the IP Address + Port of the network device
    • UUID: this is only required with Global Caché devices and would follow "GlobalCache_[MAC]"
    • Ports: Ports define the device attached to the connection
      • ID: this is the name of the device in code.  Should follow JSON variable formatting
      • Name: this is the friendly name that your users will see on the Interface
      • Methods: methods define the individual UI section
        • ID: this is the control type ID that is called in code (specific to the control type)
        • Name: this is the user-accessible name shown on the Zoom Rooms Interface
        • Command: this is either the full command or the shared parts of the command string depending on the action type
          • NOTE: When the action type is 'actions' a % should be placed in the command string as a placeholder for the inserted elements inside of 'params'
        • Params: this section is only used with 'actions' type and contains the elements that can roll up to the parent command.
          • ID: this is the programming ID that is called in code
          • Name: This will be the user-accessible text on the Room Controls Button
          • Value: this is the command section that is inserted in the parent command.  An example of this would be using 'POWR000%\\x0D' as the parent command, '0' for Off or '1' for On could be inserted for some Sharp Displays
{
"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"
},
...

Below 'methods', an additional section can be used: "response_filter".  The Response Filter is a beacon that allows the Response Filters defined below to understand which connection to listen for.  There are no functions defined in this area.  How a Response Filter fits into other sections will be covered inside of those sections.

Styles

Styles control the visual styling of your interface elements.  Today, the adjustments aren't extremely extensive, so it isn't very hard to learn. 

There are many icons available in the interface.  They span everything from Air Conditioners to Speakerphones.  The icons below are the current list, but this list is regularly expanding.

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  

 

There are three primary modifiers within styles: icons (as we discussed above), Main Methods, and Visibility. 

Icons are the visualizations of the system.  You can use them either to mark a device or to replace the text tied to a button. In the below example, we've defined a device called 'example'.

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

Once 'example' is defined as a device, we can use this ID inside of styles.  For example, setting the main icon for our example device to be a light is easily done. 

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

You may also notice that within a single line, we've also defined the Main Method for the device.  The Main Method pulls the referenced command that you've defined into the title bar of the device giving it a prominent billing like so:

mceclip0.png

We've defined the power command as the main method, and so it is shown in the upper bar separate from the other commands.

The third style type is Visibility. Visibility allows the programmer to define a function, but hide that function from the User's Interface completely.  It can be defined just as easily:

"example.power.invisible=true"

Following the format of "device.command.invisible=true" allows this command to be completely hidden from the Rooms User.  

Rules

Rules are the automation engine of Room Controls.  This is the area where things that happen on their own are defined.  For example, if I wanted my display to only be active when a meeting is active, I could leverage "meeting_started" and "meeting_ended" (stock Zoom events) to make this occur.  

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

This example can be used to reduce power consumption for your system.

If one command per rule isn't enough, these commands can easily be stacked.  While they technically fire sequentially, they process quickly enough that we'll consider these events simultaneous.  In my above example "camera.power.wake" is added beneath "display.power.on" to activate my camera when my display wakes.

The available stock Zoom commands inside of rules today 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: Operating Hours are set in the Zoom Rooms settings page. 

It is also simple to add your own for Response Filters.  Within the rules section, you can also use the Trigger Events discussed below to drive your own automation with outside inputs.

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

In this example, our "user_customized_event1" is turning our controlled light off.  This could be driven by an input from a button or maybe a motion sensor going inactive or maybe even a third-party system like a booking system sending the room an update that no users checked in for the meeting.  How you can use this feature is primarily limited by your imagination.

Response Filters

Response Filters are a powerful advancement in Zoom Rooms Native Room Controls functionality.  These filters read messages coming back from defined devices and instantaneously scan for a phrase to match.  When this phrase (or expression) is identified on that connection, the Rules Trigger Event (described above) fires.

Each Response Filter is comprised of three elements:

  • "name": the name is used in the "ports" section of "methods".  When the response filter matches this name in the "ports" area, this begins to span the defined connection
  • "filter_regex": the regex (or Regular Expression) is the set of characters that the Response Filter is attempting to match.  When the match occurs, the "trigger_event" will activate
  • "trigger_event": the Trigger Event is used within the rules section.  When the "filter_regex" activates, the automation defined within this Trigger Event in Rules will occur

Using Room Controls

On the room controller device, simply tap the Room Controls icon to access these added functions. 

When not in a meeting, the Room Controls icon can be found in the main menus.

During a meeting, tapping the icon at the top right of the controller will display the same Room Controls.

Troubleshooting

Troubleshooting is an important part in any custom configuration.  While Room Controls can be simple, it is also flexible enough to be complex when needed.  The below sections should help to resolve possible roadblocks.

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

These files have been compiled from various sources and should be used as a starting point only.  Some modification is likely required to fit your application.