Integrating CasaTunes and other iOS Apps

Contents

IntroductionCasaTunes custom URL schemeExamples

Introduction

The CasaTunes iPhone and iPad Apps (iOS Apps) enable launching the CasaTunes App from a 3rd party iOS control App and returning control back to the iOS control App without requiring users to manually switch between applications.

This seamless integration is a great advantage to homeowners and integrators, as it allows them to pick and choose the best home automation and whole house music control solutions available.

This integration is made possible by application developers who implement support for custom URL schemes in their applications. The concept of a custom URL scheme is analogous to launching an application from the command line and specifying various optional startup parameters.

In order for a control App to launch the CasaTunes App, the control App must implement support for entering 3rd party url schemes. Today, there are many control Apps that can launch other Apps, including those from Bitwise Controls, CommandFusion, OnControls, and Roomie.

When CasaTunes is launched from another iOS App, iOS displays a back arrow and the name of the control App that launched CasaTunes in the top left hand corner of the iOS device. Touching the back arrow returns control back to the original control App that launched the CasaTunes App.

You can create a CasaTunes url and add it to your Home screen. This is a good way to setup a shortcut to open the CasaTunes App to a certain room with the provided parameters

CasaTunes custom URL scheme

The CasaTunes custom URL scheme is defined as follows:

casatunes://?key1=value1&key2=value2&key3=value3

Notes:
The “?” goes before the first key/value parameter and “&” before each additional key/value parameter
The Key/Value parameters are optional, so if you simply specified “casatunes://” with no parameters it would launch the CasaTunes App
You must replace space characters in the names of rooms, sources, and playlists with %20
You can test and verify your custom URL commands by entering them in the Safari browser on your iOS device

The following optional parameters can be specified:

Key
Value
Room
Specifies the room name or ID of the room you want to display
Source
Specifies the name or ID of the source to set for the selected room
Playlist
Specifies the name of a CasaTunes playlist to play in the selected room
Volume
Specifies the volume level for the selected room
Power
Specifies whether the power for the selected room should be “off” or “on”
BackURL
Specifies the custom URL to “launch” when you select to “return” back to the control App that launched CasaTunes. You only need to specify this if you want the CasaTunes iOS App to return control back to the control App after the Timeout seconds below
Timeout
You can have CasaTunes automatically launch the custom URL specified in the BackURL option if there has been no activity for the timeout period. The timeout period is specified in seconds.

Examples

Example 1

casatunes://?power=on&room=office&source=1&volume=40

Start the CasaTunes App and select the Office, power on the room, switch the source to the second source (zero based), and set the volume level to 40.

Example 2

casatunes://?power=on&room=office&source=1&volume=40&backURL=bwtouch://&timeout=30

Start the CasaTunes App and select the Office, power on the room, switch the source to the second source (zero based), and set the volume level to 40. After 30 seconds on inactivity, return control back to the BitWise control App (whose url scheme is bwtouch://)