Volume Control & Custom Button Tutorial

"Remotescape Volume Control sounds interesting, but how hard is it to configure? I'd like to get a sense of how it works before I get started."

This tutorial will show you step-by-step the configuration of Remotescape Volume Control for an example home entertainment system. Here are the A/V components in the environment for this tutorial:

  • Kaleidescape Mini System.
  • Two additional Kaleidescape zones, one connected to a Denon DRA-697CI amplifier with RS-232C serial control.
  • A Global Caché GC-100 IP to serial/IR network adapter, for controlling the Denon amplifier via serial protocol.

Creating your Remotescape Dealer Account

All of the configuration for Remotescape Volume Control is done using the Remotescape installer portal: no configuration is done on the iPhone at all. Once you select your Kaleidescape zone in the Remotescape Settings tab, the corresponding Volume Control configuration is loaded automatically from our servers. This design feature enables the volume control buttons automatically for any iPhone, iPod touch, or iPad brought into the home, without any configuration needing to be entered on the device.

To begin, you need to create an account on the installer web portal. Accounts are free, and your account can be used right away after completing the sign-up process:

      Sign up for a Remotescape Dealer Account

You can sign up as a Kaleidescape dealer, or a Remotescape customer. Most Remotescape customers will prefer to have their Kaleidescape installer configure volume control for them, but users are welcome to configure volume control themselves if they have the technical knowledge and documentation for their audio components. The only difference between the two types of accounts is pricing: dealer discounts on zone licenses are only available to official Kaleidescape dealers. If you have applied as a dealer, then your application will be reviewed within a few business days.

If you are applying for dealer pricing, make sure you specify your company's name and web site on the sign-up page. Official Kaleidescape dealers will automatically get dealer pricing (make sure you check that box on the sign-up form, and that your company is listed in the Kaleidescape dealer locator.)

Once you create your Remotescape dealer account, sign in with your e-mail address and enter a password. At this point, you are ready to configure Volume Control.

Managing your Dealer Account

Each dealer account can have one or more users associated with it. Initially, one user account is created in your dealer account with your name and e-mail address. You can add additional users for other employees in your company in the Administration section on the main page.

You can also edit your company details from the main page. If you have requested dealer pricing, then the Kaleidescape dealer field in the company detail page will be marked Yes. Please allow up to one week for your application for dealer pricing to be reviewed.

Zone Licenses

Remotescape Volume Control is priced per configured Kaleidescape zone (that is, Kaleidescape zones you wish to enable volume control in). Licenses for volume control start at $99 (US) for one zone (MSRP).

Click the Purchase more zone licenses button on the main page to buy zone licenses. If you applied for dealer pricing and have been approved by Remotescape, then this button will take you automatically to the dealer store. Otherwise, you will be taken to the retail store. Once you purchase zone licenses, they are added immediately to your dealer account. If you refresh the main dealer page shortly after you complete your purchase, the zone license inventory will be updated to reflect the newly acquired licenses.

Discounts are provided for bulk purchases of 5 or 10 zone licenses. Simply purchase the license bundle in the store that suits your needs.

Customer Sites

You must create a customer site for each location you wish to configure Volume Control in. You may add as many customer sites as you require (there is no cost to create customer sites). A customer site typically corresponds to a single home, yacht, aircraft, etc. You must provide a unique name for a customer site, but the remaining details are optional (name, address, etc.)

After you create a new customer site, click on it from the main page to continue.

A/V Zones

A/V Zones in Remotescape correspond to Kaleidescape Player zones. For example, the Kaleidescape Mini System has three zone outputs, and we want to program one of them in this example.

Click the Add A/V zone button to add a new zone. After you create a new A/V zone, click on it in the displayed list to continue.

Adding an A/V zone

Zone Details

Click on the Edit zone button to configure it.

A/V zone details

You must specify the serial number for the Kaleidescape Player serving this zone, as well as the zone number. The Kaleidescape serial number for a Player is available in the Home page of the Kaleidescape Installer Web Utility: it is best to copy and paste it from that page to make sure you enter it correctly. In the Remotescape app, a Kaleidescape zone is selected from the Settings tab, where all Kaleidescape Players discovered on the same network as the iPhone are displayed. When Remotescape starts, it checks the serial number of the selected zone in the Settings tab against the Volume Control database. If a match is found, then the corresponding volume control settings are downloaded and saved on the device.

If a matching Volume Control configuration is found on the Remotescape servers at startup, then the three volume control buttons are enabled accordingly (mute toggle, volume up, volume down.) Otherwise, the volume control buttons are not enabled.

You do not specify any configuration in the Remotescape app on the iPhone or iPod touch. All configuration data is downloaded automatically, through the above discovery process.


Components are the non-Kaleidescape devices you need to send commands to in order to control the volume. Click on the Add a component button to add at least one component to your zone configuration.


A component must have a unique name, and must have a fixed static IP address and TCP port that it receives commands on. Note that DNS host name resolution is not supported at this time, only IP addresses.

In our example, we are using a GC-100 RS-232 bridge adapter to send serial commands to the Denon amplifier. The GC-100 adapter connects to the Ethernet LAN, and then via serial cable to the Denon amplifier. This bridge device is not required in systems where the audio equipment is directly IP addressable. In our example, the GC-100 adapter has been configured to use a static IP (not DHCP), and receives its serial commands on TCP port 4999.

Some components may need to receive commands on more than one TCP port. If this is necessary in your configuration, simply create a separate component (with the same IP address) for each TCP port number.

Kaleidescape Activity Events

There are four events associated with volume control that can be configured, which are displayed in the Zone details page. You do not have to specify commands for each one.

The Activity Starting event is triggered when a zone is selected from the list in the Settings tab of the Remotescape app, either explicitly by the user, or automatically when the app launches. This can be useful for sending initialization commands to the audio equipment (power on, input selection, etc.)

There are currently three buttons in the Remotescape user interface that can be configured: mute toggle, volume up, and volume down. These buttons correspond to the other three events in this web page.

Configuring Events

Click on the Volume up event to begin configuring it. An event triggers a series of actions. An action is a single command sent to a component, or a timed wait/delay operation.

Click on the Add action button to add an action to the Volume up button. As we only have one component in our setup, the GC-100 is automatically selected for us. We have not yet added any commands, so click on the New command button at the end of the command line. For our Denon amplifier, the serial control protocol documentation indicates the command for master volume up is as follows:

Volume up command

Different components may require different end-of-command sequences. In the case of the Denon amplifier, carriage return is required to end all commands. Click the Create new command button to return to the action page, where the new volume up command is automatically selected.

Volume up action

Click Save changes to complete the action, and Done on the next page to complete the Volume up event.

Commands can also be entered and edited from the zone overview page directly. The new Volume up command is listed, and you can click on the Add a command button to add a new command without assigning it immediately to an event.

Events can have a series of commands associated with them. In our example, we want the Activity Starting event to power on the amplifier, switch to the DVD input connected to the Kaleidescape zone, and set the volume to an appropriate level. Here are the commands for this event:

Startup event with multiple commands

Here, we are pausing after the power-on command since the amplifier cannot receive additional commands until it is finished powering on. Note that Remotescape cannot currently be configured to wait for component responses, such as power on complete, so using pauses is important in some cases. After the amplifier is on, then we select the DVD input source where the Kaleidescape zone is connected. To be safe, we pause again for a short time, then set the volume to a fixed output level (since different inputs on this amplifier have different levels.)

We similarly programmed the volume down and mute toggle events. Interestingly, the Denon serial interface does not have a mute toggle command: only discrete mute on and off. To work around this, we set the Mute event to perform a "mute on" command only. The Denon amplifier automatically un-mutes when the volume up and down commands are received (although we could have added a mute off command to the volume up and down events as an alternative).

Assigning Zone Licenses

Once you have configured your zone, the last remaining step to use it in Remotescape is to assign a zone license to it. You will not be able to test or use the volume control features until you purchase zone licenses and assign one to this zone. If the zone is unlicensed and you have unassigned zone licenses purchased and available, there is a link in the Zone licensing details section to assign a license to the zone. If you do not have any zone licenses available, then you can purchase them immediately from the presented link. Purchased zone licenses will show up in your dealer account automatically shortly after you complete the transaction. Do not access the Remotescape zone licensing store except through the links in the Remotescape installer web portal.

Assigning a zone license

Once you assign a license to a zone, the only way to recover it for use elsewhere is to delete the zone completely. Note that this will disable Remotescape Volume Control for that zone.

Zones without a license

Testing Volume Control

Once you have configured volume control in the installer web portal and licensed each zone, you are ready to test it on an iPhone, iPod touch, or iPad. Make sure you have downloaded and installed Remotescape on the device, and have checked the App Store for the latest update.

Remotescape Volume Control  

Start Remotescape, and select the zone you configured volume control for in the Settings tab. At this point, the volume control button in the upper right of all screens can be pressed to open the volume control window.

The leftmost button is the Kaleidescape pause toggle button, and is not part of the Volume Control feature. The second button is the mute toggle button, and pressing it will activate the associated commands. The remaining two buttons are volume up and down. You can press and hold volume up and volume down to repeat the actions for these buttons. The actions will be repeated 5 times per second while the buttons are held down.

The Activity Starting event's commands are sent when the corresponding A/V zone is selected, either directly by the user, or automatically when the Remotescape app launches. There is no Activity Ending command, since Apple does not allow applications to perform long-running operations when they are closed.

Diagnosing Problems

Remotescape Volume Control includes a detailed application log to help diagnose and resolve configuration problems. As Volume Control is configured and buttons are pressed in the Remotescape app, detailed messages are sent to its built-in log. You can view the log by going to the Settings tab in Remotescape, and tapping twice quickly on the footer area where the version number and copyright notice are found. Some examples of problems that the application can help resolve include:

  • Volume Control settings not found.
  • Incorrect Kaleidescape component serial number or zone output number.
  • Incorrect component IP address or TCP port number.
  • Incorrect, or poorly formatted control commands.
  • Volume Control events/actions not configured.
  • Wi-Fi connection not working on device.
  • Volume Control configuration update not synced.
  • A/V zone license not assigned.

Opening the application log

Opening the application log


The application log lists the last 100 messages, with the most recent ones shown at the top. Messages that indicate an error or warning will have a corresponding icon in the left column, while informational messages have no icon. Tap on any message line to see the complete message text.

Tap the Clear button to remove all current messages from the log. Tap the Sync button to cause Remotescape to check for the latest Volume Control settings for this Kaleidescape Player and zone. Note that Remotescape automatically updates the configuration settings when it starts and occasionally while it's running.

Messages are collected regardless of whether the application log is displayed. You can use the Volume Control buttons while the application log is visible to resolve problems interactively.

Remotescape Custom Buttons

You can add custom buttons to Remotescape that send arbitrary commands to any components in your home. Start by clicking on the 'Add custom button' link in the installer portal under the 'External Device Control' table:

Adding a custom button

Enter the text label for the new button (image buttons are not supported). Click 'Create new button', and now you can specify the actions to associate with the new button. Custom buttons use the same components and commands as volume control events, so adding the custom button actions is the same process.

Adding actions to a custom button

In the example above, we've added a 'Mid volume' custom button that sets the volume to a specific level in one tap. Now, when we tap on the volume control button in Remotescape for iPhone and iPod touch, we see the new button displayed under the volume controls:

Custom buttons in Remotescape for iPhone

On the iPad, a new button is displayed to the left of the volume controls when there are custom buttons defined for the selected zone. Tap on it, and a window of the custom buttons pops up:

Custom buttons in Remotescape for iPad

Where to Get Help

If you are a Remotescape user and need help configuring volume control or custom buttons, you should contact the installer who set up your Kaleidescape System. Or, you can find a Kaleidescape dealer near you at the Kaleidescape web site. Let them know you want them to configure Remotescape for you, and direct them to our web site.