Layout Controls for Cisco endpoints

You can enhance your meeting room experience with the Layout Controls feature, which allows you to switch between different conference layouts using the touch panel of a Cisco room system during a call.

The Layout Controls feature uses the Layout Controls macro installed on the endpoint, which sends the appropriate DTMF digits (typically *8 for Pexip meetings) to the conference to trigger a layout change. You can still use the endpoint's keypad to change the layout and manage meetings but the Layout Controls macro provides an improved user experience with the addition of the Layout Controls button on the endpoint's touch panel.

The endpoint must be dialed in as a host participant to use this control, however the button will always appear on the touch panel for all endpoint participant types.

On this page:

Supported endpoints and conferences

Layout Controls is supported:

  • on Cisco Room Devices MX, SX, DX and Room Kit Series, but not SX10.
  • in Pexip, BlueJeans, Zoom, Webex, Google Meet, and Microsoft Teams conferences.

Prerequisites

  • Firmware CE9.14 or newer, or RoomOS 10 or newer.
  • Administrator user access to the Cisco endpoint for configuration.

Manual installation of Layout Controls

The following instructions explain how to install the Layout Controls macro manually on a single endpoint. If you use Enhanced Room Management (ERM) and want to provision the macro on multiple endpoints simultaneously, proceed to ERM installation of Layout Controls.

During the macro installation, you will require some or all of the following files so we recommend that you download them now (if the file/link fails to download automatically in some browsers, you may need to right-click on the link and select Save link as...).

Download link Required?
macro.js Required in all installations.
settings.js Required in all installations.
checksum.txt Optional file to verify the macro.js file. Instructions on how to verify are described below.

To verify the macro you can use the following commands and compare the value to the file in checksum.txt.

Windows

certutil -hashfile C:/Users/user1/Downloads/macro.js SHA256

Linux

sha256sum [file location].

Example:

sha256sum ~/Downloads/macro.js

MacOS

shasum -a 256 [file location].

Example:

shasum -a 256 ~/Downloads/macro.js

Installing the Layout Controls macro

  1. Log into the web interface of your Cisco endpoint in your browser.
  2. Go to Macro Editor.

  3. Select Enable Macros. This prompt only appears if you have never used a macro before.
  4. In the Macro Editor, select Import from file and select the settings file (settings.js) that you downloaded earlier.
  5. Select the Save to video system icon:

  6. Select Import from file again, and select the macro file (macro.js) that you downloaded earlier.
  7. Select the Save to video system icon.

  8. Toggle the macro switch from off to on.
  9. Refresh the web page.

With immediate effect, the touch panel of the Cisco endpoint shows the Layout Controls button during conferences and is ready for use by host participants.

If required, you can rename the macro in the Macro Editor. You must not rename the settings file but you can edit the default settings.

Editing the default macro settings

By default, the layout controls macro sends the *8 DTMF digits to the conference, which is the default command used to cycle the layout in a Pexip-managed conference (including Teams and Google Meet interop conferences).

However, if you want the macro to also work with other conferencing providers, or if you have customized the DTMF digits in your Pexip Infinity theme, you can configure the settings.js file to send (override) different DTMF digits instead.

The settings.js file includes 3 pre-defined alternative conferencing providers (to handle Zoom, BlueJeans and Webex hosted conferences) in the dtmfs array as shown below:

const dtmf_macro_settings = {
  "button": {
    "Icon": "Tv",
    "Name": "Layout Controls"
  },
  "dtmfs": [
    { "id": "[z|Z]oom", "name": "ZOOM", "dtmf": "11" },
    { "id": "bjn.vc", "name": "BJN", "dtmf": "*1" },
    { "id": "@.*\\.webex", "name": "WEBEX", "dtmf": "2" }
  ]
}

You can modify, add, or delete the dtmfs array entries as required. Each object in the array contains three keys:

  • id: this defines a regular expression (regex) used to identify the conference provider by matching the domain of the URI used to access the conference.
  • name: the name of the conferencing provider that is prompted on logs.
  • dtmf: the DTMF digits to send to the conference when the id is matched (instead of the default *8).

You can also modify the button object if you want to change the name (label) of the button that appears on the endpoint control panel.

Note that the file is in JSON format and you must ensure that you do not break the JSON syntax if you edit the file.

Troubleshooting

If you need to troubleshoot the Layout Controls macro at any point, you can download logs from the web interface in

System Maintenance > Issues and Diagnostics > Systems logs > Download logs...

ERM installation of Layout Controls

If you use Enhanced Room Management (ERM), you can enable Layout Controls on multiple endpoints simultaneously.

During the macro installation, you will require some or all of the following files so we recommend that you download them now (if the file/link fails to download automatically in some browsers, you may need to right-click on the link and select Save link as...).

Download link Required?
macro.js Required in all installations.
settings.js Required in all installations.
checksum.txt Optional file to verify the macro.js file. Instructions on how to verify are described below.

To verify the macro you can use the following commands and compare the value to the file in checksum.txt.

Windows

certutil -hashfile C:/Users/user1/Downloads/macro.js SHA256

Linux

sha256sum [file location].

Example:

sha256sum ~/Downloads/macro.js

MacOS

shasum -a 256 [file location].

Example:

shasum -a 256 ~/Downloads/macro.js

Installing Layout Controls macro in ERM

  1. Go to Enhanced Room Management > Panels and macros.
  2. On the Room Controls tab, select the + button.

  3. Enter a title and description for the settings.
  4. Attach the settings.js file that you downloaded earlier and select Add.
  5. Again, select the + button.
  6. Enter a title and description for the macro.
  7. Attach the macro.js file that you downloaded earlier and select Add.

The Layout Controls macro and settings are now installed in ERM.

Provisioning Layout Controls on multiple endpoints in ERM

The following instructions explain how to provision one or more Cisco endpoints in ERM with Layout Controls.

  1. Go to Enhanced Room Management > Systems.
  2. On the Search tab, select all room systems that you want to deploy Layout ControlsSIP Guest Join to.
  3. Select Provisioning.
  4. Select Apply macros/panels and from the Controls options select Layout Controls macroAd hoc join macro.
  5. To enable the macro on the endpoints with immediate effect select Apply, otherwise select Schedule for the night.