Basic iPhone Controller

This recipe shows how to create a basic iOS (iPhone/iPad) web app for controlling WATCHOUT. The emphasis is on simplicity, with key features only. Nevertheless, this app can serve as a starting point for many simple control apps.

A web app consists of a set of files which you load onto a web server. You then browse to this location using your iOS device.

WATCHOUT Configuration

This recipe assumes that there is a show on your display computer named “iOSControl1.” Follow these steps to prepare your display computer:

  1. Download the attached “iOSControl1_show.zip” file to your production computer.
  2. Unzip the file, and open the enclosed iOSControl1.watch file using WATCHOUT production software.
  3. Open the single display and change its Address to match the IP address of your display computer.
  4. Make sure your display computer is operational, with WATCHOUT display software running.
  5. Choose “Online” on the Stage menu to transfer the show to the display computer. You can now try out the two timelines in this example by clicking the Play buttons in the Task window.
  6. Finally, choose “Online” again to take the production computer offline. This is necessary to allow the display computer to be controlled from the iOS app.

Web Server Configuration

This recipe uses the same web server as the recipe titled “Uploading with a Browser”, adding a new folder with the web app. Download the attached “iOSControl1.zip” file, unzip it, and copy the entire resulting “iOSControl1” folder to c:\wamp\www, so that the enclosed index.html file is located at c:\wamp\www\iOSControl1\index.html. Make sure that your web server is running, then browse to the app using your iOS device and entering this address (substitute your web server’s IP address as appropriate):

http://192.168.0.48/iOSControl1/

 

If all works well, you will see two buttons, as shown below. If you get no response, make sure your web server is running, and double-check that the IP number (entered as part of the URL above) matches the IP number on the web server.

BasicScreen1.png

Editing the App

You need to make one small change to the web app to match your system’s configuration. Locate the file named “Control.js”, located in the “js” folder of the “iOSControl1” folder you installed in the web server above. Open “Control.js” using a text editor by right-clicking it and choosing “Edit”. The content of the file looks like this:

var wo = new WATCHMan; // Object that talks to WATCHOUT
wo.SetAddress(“192.168.0.49”); // Set address of cluster master
wo.SetConnected(true);         // Connect to WATCHOUT

function cmdBtnClick(evt) {
   wo.Play(evt.target.innerHTML);
}
 

Change the IP address (shown in bold above) to match the address of your display computer. Make sure you keep the quotation marks around the address. Save the file.

This app also includes a file called index.html, located in the “iOSControl1” folder. You don’t need to make any changes to this file, but it is worth opening it to see how it works. To open this file, drag it onto a text editor, such as Notepad. (You may want to add a shortcut to Notepad on your desktop to make this easier.) The interesting part of this file reflects the two buttons shown by the app and looks like this:

<div id=”cmdList”>
  <button onclick=”cmdBtnClick(event)”>Alpha</button>
  <button onclick=”cmdBtnClick(event)”>Beta</button>
</div>
 

Alpha and Beta represent names of timelines that you can start. To change the name of the timelines, simply edit the text Alpha and Beta inside the <button> tags. You can add more buttons to start more timelines by adding more <button> lines, each with its own button name.

Note how each of the buttons has the cmdBtnClick function, which is defined in the “Control.js” file shown above. This function obtains the name of the relevant timeline and calls the Play function of the WATCHMan object. WATCHMan is used to talk to WATCHOUT. By adding more functions like this one, it’s easy to create buttons that perform other WATCHOUT functions. The functions available in the WATCHMan javascript API can be found here.

Loading the Show

The app assumes that the correct show is already loaded by WATCHOUT display software. You could also perform this operation from the control app, but it is usually preferable to have the show loaded automatically when the display computers are started. It’s then ready for immediate action when you press a button on the control app.

To start WATCHOUT automatically and load a show, you need to set up two files on the primary display computer (the one you’re also targeting from the control app):

  • A Startup shortcut that starts WATCHOUT when the computer is started, and also tells WATCHOUT to read further commands from a file.
  • A command file, containing commands to load the desired show.

Follow these steps to create the shortcut:

  1. Open the folder containing your WATCHOUT software.
  2. Right-click on WATCHPOINT.EXE and choose “Send to > Desktop (create shortcut).”
  3. Right-click the resulting shortcut on the computer desktop and choose Properties.
  4. In the Target field, append a space followed by WOStartup.txt (see illustration below). Click OK to close the dialog, saving the shortcut.
  5. Open the Startup folder. Click the Start button, choose “All Programs”, right-click the Startup item and choose “Open All Users.”
  6. Move the shortcut created above from the desktop into this Startup folder.

Shortcut.png

You also need to create the “WOStartup.txt” file referenced by the shortcut above. This is a command file for WATCHOUT, containing the commands required to load the show:

  1. Open your WATCHOUT installation folder.
  2. Right-click inside this folder and choose “New > Text Document” (do not choose “Rich Text Document”).
  3. Name the file WOStartup.txt.
  4. Type the text shown below into the file.
  5. Save the file.

This is the text to be entered into the WOStartup.txt file:

authenticate 1
load “iOSControl1”
 

After completing the steps above, you can test your shortcut by double-clicking it in the Startup folder. This should launch WATCHOUT display software and load the specified show. Since there’s no image at the beginning of the main timeline, the display will just go black.

Testing the App

Reload the app in your iOS device, by tapping the refresh arrow at the right end of the address bar. You should now be able to control the show by pressing the buttons. Each button starts its own auxiliary timeline in the display software. If nothing happens, go through the following checklist:

Make sure that the show is loaded into the display software. This is handled by the startup shortcut and command script described above, which have to be in place.

Restart your display computer. It should run the shortcut placed in the startup folder, causing WATCHOUT display software to launch, and then immediately load the show specified in the command file, making the screen go black.

If WATCHOUT display software starts, but the logo remains on screen, double-check that the name of the command file is appended inside the shortcut (as shown in the screenshot above), and that the command file “WOStartup.txt” contains the text shown above, and is located in the WATCHOUT installation folder (i.e., same folder as WATCHPOINT.EXE).

Installing the App on your Home Screen

Once everything is working OK, you can install the app on the home screen of your iOS device. Do so by tapping the InstallBtn.png button located at the navigation bar at the bottom of the iPhone display (see iPhone illustration above). Tap this button, then choose “Add to Home Screen”. This adds an icon to the home screen, allowing you to start the app without going through the web browser.

Starting the app from the home screen also removes the navigation bar from the bottom of the screen, providing more space for your buttons (see illustration below). Furthermore, since the app is now installed on your device, it will work even if the web server isn’t accessible. You can test this by stopping the web server: click the green “W” icon shown in your computer’s task bar and choose “Stop All Services”. Now reload the app from your home screen to make sure it’s still working.

BasicScreen2.png

App started from the home screen.

Even More Technical Details

Here are a few pointers if you want to delve even deeper into this subject. You don’t need to read this in order to use this recipe in its basic form.

The secret ingredient that makes this web page work as a stand-alone app is in the file named “cache.php”. This file produces what’s known as a web app manifest. You can actually see what this file generates by browsing to it:

Remember to (re)-start your web server, and substitute your server’s address in the URL. As you can see, the manifest lists all the files used in the app. Towards the end, you’ll also see a comment starting with the word “Hash.” This tells your iOS device if the app has changed on the server, making it download the new version (assuming the server can be reached).

The two icon files found in the iOSControl1 folder are used by your iOS device when the app is installed on the home screen. They both contain the same image, but at different resolutions. This accounts for the high-resolution “Retina” display of the iPhone 4.

You can learn more about how to create web apps here:

Files attached to this recipe: