Room Controls in zoom App
Room Controls is a Zoom Room feature that allows users to remotely control third-party equipment that is IP-capable by using their Zoom Room controller to control that equipment. There is a way for Zoom Room administrators to create a configuration profile where they can include outgoing IP control messages.
This article covers:
- 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
- For MacOS or Windows users, or Zoom Room Appliances version 5.1 or higher, Zoom Rooms for macOS or Windows can be downloaded.
- Devices controlled by third parties via LAN or WLAN can also be accessed through Zoom Rooms.
- In the event that the device does not have native LAN or WLAN access, it will be necessary to connect the network adapter (IP2SL/IP2CC or wifi equivalent)
Enabling Room Controls
You must enable Zoom Rooms before uploading a JSON configuration profile. JSON configuration profiles can be uploaded at any level of the Zoom Rooms hierarchy.
- Log into the Zoom website.
- Click on Zoom Rooms under Room Management.
- Scroll down to Edit and click it.
- Turn on the Enable Room Controls button (blue) under Devices.
- Select Create Profile.
- Specify the room’s configuration in JSON.
Writing a Room Controls profile
Getting Started
A working knowledge of JSON is required before writing a Room Controls Profile. A key feature of JSON is that it uses key-value pairs and that it must be formatted correctly. You can learn more about JSON by taking an online course.
The next person handling your file should be treated with some courtesy, regardless of the language used. Zoom Rooms Native Room Controls do not have a requirement around this, but it is recommended. ‘About’ can be used above ‘adapters’ to record the author, version, and other history. Room Controls does not parse this information, but it will persist. Below is an example of how this might be utilized.
{
"about": {
"type": "Medium Conference A",
"version": "v1.2.4",
"design_ref": "\\files\MediumConfA",
"created": "Mon, 21 Oct 2020 16:35:52 GMT"
},
Adapters
Room Controls are connected to devices by setting up the adapters. Configuration takes place in this section. There should be similar formats for devices that form part of the nested JSON format (this example is nested in order to parallel the code example below):
- Adapters:
- Device connections are defined by adapters
- Model:
- These can be generic network adapters, IP2CCs, and IP2SLs. See below for further information.
- IP:
- It is the network device’s IP address plus its port number.
- NOTE:
- In current software versions, RoomControls also supports hostnames rather than IP addresses
- UUID:
- “GlobalCache_[MAC]” is required only for Global Cache devices.
- Ports:
- These refer to the devices that are connected to a connection.
- ID:
- A code identifying a device. Formatted according to JSON
- Name:
- You will use this as the friendly name on your website
- Methods:
- This section defines each UI section
- ID:
- In code, this identifies the specific control type.
- Name:
- Zoom Rooms user interface displays this name.
- Command:
- Depending on the type of action, this could either be the full command string or the shared parts of it
- NOTE:
- The % should be placed in the command string when the action type is ‘actions’. This placeholder will accommodate the elements inserted inside the ‘params’
- Params:
- In this section, just the elements that apply to the parent command can be found. It is only used for ‘actions’ type commands.
- ID:
- This is the code ID used in programming.
- Name:
- On the Room Controls Button, this will be the text that users can access
- Value:
- This will be the section of the parent command that users can access. A perfect example of this would be inserting ‘0’ for Off or ‘1’ for On to some Sharp Displays using ‘POWR000%//x0D’ as 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 also a response_filter section below ‘methods’. A Response Filter determines which connection to listen for by being a beacon. This area does not have any functions defined. The sections devoted to each of these topics will detail how a Response Filter fits into them.
Styles
Your interface elements’ visual styling is controlled by styles. It isn’t hard to learn because the adjustments aren’t very extensive.
The interface contains a number of icons. The icons range from speakers to air conditioners. Below is a list of the current icons.
| 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 |  |
Styles can be modified in three ways: icons (as we discussed above), main methods, and visibility.
An icon is a visual representation of a system. Depending on the application, they may serve as either a mark or a replacement for the text tied to a button. A device called ‘example’ has been defined in the below example.
{
"adapters": [
{
"model": "ExternalControlSystem",
"ip": "tcp://[USER_IP_ADDRESS]:[USER_PORT]",
"ports": [
{
"id": "example",
"name": "Example Device",
"methods": [
...
We can use ‘example’ as a device ID once it is defined. Our example device can be made to have a light icon as the main icon.
"styles": [
"example.icon=icon_light",
"example.main_method=power"
]
We have also defined the Main Method of the device within a single line. You can make the referenced command appear prominently in the device’s title bar using the Main Method, as follows:
In the upper bar, we show the power command separately from other methods because it is the main method.
Visibility is the third style type. A function can be defined in Visibility mode, but it can be completely hidden from the User Interface. You can define it the same way:
"example.power.invisible=true"
This command can be completely hidden from the Rooms User by following the format of “device.command.invisible=true”.
Rules
Room Controls automates using rules. Rules define automatically occurring actions. The Zoom events “meeting_started” and “meeting_ended” (stock Zoom events) can be leveraged to make it so that my display only appears during meetings.
"rules": {
"meeting_started": [
"display.power.on",
"camera.power.wake"
]
),
"meeting_ended": [
"display.power.off"
]
}
Using this example, you can reduce the power consumption of your system.
These commands can easily be stacked if one command per rule is not sufficient. We will consider these events simultaneous even though they technically fire sequentially. To activate my camera when my display wakes, I’ve added “camera.power.wake” beneath “display.power.on” in my example above.
Inside of rules today, you have the following Zoom commands:
- Meetings and Events
- Started “meeting”
- “Meeting_ended”
- Event Audio
- Mute “microphone”
- Unmuted “microphone”
- Event video
- Starts with “video_started” (the camera is unmuted)
- Ends with “video_stopped” (the camera is muted)
- Events in Admin
- Start with “operation_time”
- Or “operation_time_ended”.
Note:
Zoom Rooms settings allow you to set operating hours.
In addition, Response Filters can also be added by the user. As mentioned above, you can also use the trigger events discussed below to automate your own processes based on inputs from the outside.
"rules":{
"operation_time_started":[
"light.power.on"
],
"user_customized_event1":[
"light.power.off"
]
}
Using this example, we are turning off our controlled light using a user-customized event. Inputs like a button, motion sensors, or perhaps a booking system sending an update that there have been no users checked in could trigger this. Your imagination is the only limit to this feature.
Response Filters
Native Zoom Rooms Room Controls now feature Response Filters, which are a powerful enhancement to the functionality. Messages coming back from defined devices are read by these filters and instantly scanned. The Rules Trigger Event (described above) triggers when the phrase (or expression) is identified on that connection.
There are three elements in each Response Filter:
- “name”:
- “Ports” is a section within “methods” that uses the name. Whenever this name appears in the “ports” area, the definition of the connection is spanned
- “filter_regex”:
- Response Filter looks for characters that match the regex (or Regular Expression). If a match occurs, the “trigger_event” will be activated.
- “trigger_event”:
- Within the rules section, there is a Trigger Event. This Trigger Event in Rules will trigger automation when the “filter_regex” is activated.
Using Room Controls
Tap the Room Controls icon on the Zoom Rooms controller to access these additional features.
Room Controls can be found in the main menu when you are not in a meeting.
Tap the Room Controls icon in the top right corner of the controller window during a meeting.
Troubleshooting
A custom configuration must include troubleshooting. It is true that Room Controls can be simple, but they are also flexible enough to be complex if that is what is required. We hope that the following sections will assist in resolving potential 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
As a starting point, these files have been gathered from a variety of sources. Your application may require some modification.
- Files of the generic type
- Zoomed Room Control JSON Profile
- Additional comments for the Zoomed Room control JSON profile
- Of the generic lighting JSON profile (relay)
- JSON profile for generic lighting (serial)
- For Avicor
- JSON profile for IP
- Mid-Atlantic
- JSON Profile (IP) for Racklink
- Shure
- Shure
- Shure’s MXA910 by JSON Profiles (IP):