CQC Client: User's Guide

CQC Client is an application for the iPhone or iPod Touch which lets you connect to one or more Charmed Quark servers and interact with the template you have set up using CQC's tools.

I imagine that a 30-page document would probably be appropriate, but until I have time to write such a tome, here's a quick guide to getting started. If you find topics that I should cover, please let me know.

CQC Server Setup

The CQC system supports remote clients like the iPhone using an installable component called the Remote Viewer Server. You can check whether it's already present and running by looking for a process called CQCRemVSrv.exe. To install it, run the CQC installer and select the "full custom install" option. You must use a relatively recent copy of the CQC software. If you have multiple machines, we recommend installing it on the master server.

As the installer runs, one of the screens you will see is for the Remote Viewer Server. Make sure the check mark labelled "Install The Server" is checked. Usually, you should leave the port numbers unchanged. If you modify the view or image port numbers, you will need to use the new numbers when you set up the iPhone. If you want to be able to access your system from anywhere, make sure that connections to the view and image ports are allowed through any firewalls and routers you may have. The admin port does not need to be accessible.

You must then set up at least one user. The "Default User Drawn Interface" under Administer > Accounts > Users > More determines the initial template that you see every time you connect. Of course, widgets on the initial template can direct the user to other templates from there. I am told that the default password for newly created users is Welcome.

There's a Remote Viewer Guide on the Charmed Quark site with additional information. Regarding its discussion of the two client modes, the iPhone client is using Advanced Mode. But of course. :)

Installation on the iPhone

Just buy the application from Apple's iTunes store, and you're ready to go!

Client Setup

When you start CQC Client, the first screen you will see is the server list, which shows all the servers you have defined. By default the list is empty, so the first thing you need to do is create a definition for your server. To do this, touch the + button in the upper left to add a new server.

This will bring up the server definition screen. On the iPad, all options are visible at once. On the iPhone, tap the buttons at the top to switch between the pages of options.

Name: a descriptive name for the server to be displayed in the server list
Host: the host name (e.g. www.myhouse.com) or IP address (e.g. 192.168.1.15)
Ports: the port numbers of the RIVA and image servers; usually, the defaults are correct
User Name: the user name to use when logging into the server
Password: the password associated with the user name

Status Bar: whether the phone status bar (with signal strength, time and battery level) should be hidden, or displayed with a black or (on the iPhone only) white background
Scrolling: whether the template should never scroll, should scroll freely, or should scroll a page at a time
Orientation: whether the output should always be displayed in portrait mode, should be switched automatically according to the phone orientation, or should always be displayed in landscape mode
Orientation Hot Keys: whether the client should send hot key messages to the server indicating the phone orientation
Gesture Hot Keys: whether gestures should be recognized and sent to the server as hot keys
Background: the color to use when painting the screen background outside of the template; this is usually visible only when you scroll past the end of the template

Autoconnect: whether CQC Client should connect to this server automatically when it starts; the Wifi option tells the client to autoconnect only when connected via Wifi (you can have one server set to Wifi autoconnect and one server set to regular autoconnect at one time; if a Wifi autoconnect server is specified, and you are connected via Wifi, it takes precedence)
Optimization: how to trade off display speed versus strict RIVA protocol compatibility:

None means that the client downloads and draws each image before continuing to the next command in the RIVA stream
Low means that the client attempts to draw the screen before images are fully loaded, and then redraw as images become available, but does not start processing a new set of drawing commands until the old set has been fully displayed (this was the default in earlier versions of CQC Client)
High means that the client will proceed with drawing a new set of drawing commands before all the images are loaded on the old screen; if the new set of drawing commands fills the entire screen, any queued image download requests are flushed

Protocol: which protocol version to use when communicating with the server. You should select the most recent version that your server supports. Version 4 is the default, but if you can't connect, try changing to an earlier version (or upgrading your server). The features introduced in each version:

Version 2: explicit template sizes and sound
Version 3: environment variables (the app uses version 3 if you choose version 2 but then define any environment variables)
Version 4: the RIVA Command message

High Resolution: on a device with a retina display, whether to display the template using the full screen resolution, so that a 480 by 320 template would take up only the upper left quarter of an iPhone screen; the default is for a 480 by 320 template to occupy the entire iPhone screen, as it does on earlier iPhones
Idle Timer: how long the phone should wait before dimming the screen and then going to sleep to conserve power; this can vary from the iPhone default of about a minute when the slider is all the way to the left, up to 60 minutes when the slider is all the way to the right

Environment Variables: environment variable values to send; any nonblank variables are sent; requires the protocol to be set to v2 or higher (the app automatically shifts up to v3 if you specify v2 but then define any environment variables)

Enter the necessary information and press Done at the upper right. You will be returned to the main screen, and your server list will now show the server you just defined. You can add another server by pressing the + button again, and edit, reorder or delete servers by pressing the Edit button.
But for now, press the server you defined. The display will "flip over", and a spinning indicator will appear in the center of the screen, with a cancel button below. If all goes well, these will disappear almost immediately when a connection is made to your CQC server, and the template will begin to load (a small spinner in the upper left corner of the screen lets you know that you are receiving data from the server).
If there's a problem connecting, the spinner and cancel button will stick around on the screen. If they stay for too long, you probably are not making a good connection with the server. Click the cancel button to return to the main screen, check your server definition, and make sure that the CQC RIVA process is running on your server.
Once you have connected, and are viewing your template, if you have the Gesture Hot Keys setting turned on, you can touch the screen with four (or more) fingers to bring up a menu that lets you:

disconnect and return to the main screen, or
edit the server settings (except for the connection parameters and the Hide Status Bar setting).

Templates

Now the hard work begins: designing templates for the iPhone. Remember that you can create separate portrait and landscape templates if you want, and switch between them according to hot keys sent by the phone when it rotates. Remember also that you can use gesture hot keys to trigger actions: two-finger swipes can move through a list, and so on.

The following hot keys are sent by the client:

AppKey1 (phone switches to portrait orientation)
AppKey2 (phone switches to upside-down portrait orientation)
AppKey3 (phone switches to left landscape orientation)
AppKey4 (phone switches to right landscape orientation)
AppKey5 (phone is face up)
AppKey6 (phone is face down)
AppKey7 (a shake begins)
AppKey8 (a shake ends or is cancelled)
NavUp (one-finger swipe up)
NavDown (one-finger swipe down)
NavLeft (one-finger swipe left)
NavRight (one-finger swipe right)
PageUp (two-finger swipe up)
PageDn (two-finger swipe down)
Previous (two-finger swipe left)
Next (two-finger swipe right)
ChannelUp (pinch out)
ChannelDn (pinch in)
VolumeUp (clockwise rotation, where two fingers move past each other)
VolumeDn (counterclockwise rotation)

The Orientation Hot Keys and Gesture Hot Keys settings must be enabled for orientation and gesture hot keys to be sent to the server. Single-finger swipes are sent only if scrolling is disabled; otherwise, single-finger swipes scroll the screen instead.

In versions 1.1 and earlier of the client, two-finger swipes sent the NavUp, NavDown, NavLeft and NavRight hot keys.

There is a limit to the number of pixels on the template (because of memory constraints on the device). On the newest devices, the template can be up to 4,897,600 pixels. On older iPhones and iPads, the limit is 1,228,800 pixels. On iPod Touches running a really old version of the OS, the limit is 307,200 pixels. Within that total pixel limit, you can size the template rectangle as desired: square, long and thin, etc. Be aware that, on the newer iPhones and iPads with retina displays, there are four times as many pixels on the screen. On the iPhone, for instance, the screen is 960 by 640, even though the template is ordinarily scaled to be only 480 by 320 on one screen (unless you turn on high resolution mode). However, the pixel limit should be enough for the template to take up several pages, either one on top of another or side by side.

Sounds

The application currently has 25 sounds built in. When you add a sound to your template, CQC sends the path of the sound file to client applications. Obviously, the path to the sound on your hard drive isn't very helpful on the iPhone, so the client looks for certain strings in the path, and if it finds one it recognizes, it plays the associated sound. Here is the sound library (together with a zip file containing all the sounds, so you can download them to your computer for use in building interfaces).

The client is looking for strings that match the names of the sound files. So if your sound file path contains the string "beep01" anywhere in the path, the beep01 sound will be played. Otherwise it looks for beep02, and so on.

RIVA Command Messages

Starting with protocol version 4, the CQC server supports the concept of a RIVA Command, which simply causes the server to send four strings (a command and three parameters) to the RIVA client, which can do whatever it wants with the information. In CQC Client, we have defined two such commands, which are used to add things like security cameras to your RIVA templates.

OpenOverlayURL Command

This command string tells the client to open an overlay, which is just a rectangle floating over the template and displaying an image of a specified URL. The three parameters are:

the URL to be displayed; this can be an HTML page or a simple image file; images are much more efficient, as they do not require the client to render the page
a comma-separated list of coordinates (x, y, width, height)
a comma-separated list of named options (in the form option=value), if any:
- overlayId: an identification string which can later be used to modify or delete the overlay
- refreshInterval: if greater than zero, the number of seconds between periodic fetches of the URL (useful for security camerages); if there is no refresh interval, the client will simply take a snapshot of the URL contents and continue to display them unchanged, never refetching
- scaleToFit: if true, the contents of the URL are scaled to fit the overlay rectangle; otherwise, the contents are cropped
- persistent: if true, the overlay stays around until the client disconnects, or an explicit CloseOverlay is received; by default, overlays are also removed whenever a new template message is received (which requires protocol version 2 or higher)

CloseOverlay Command

This command string tells the client to close the overlay with the identification string specified in the first parameter. The other parameters should be blank for future compatibility.

Overlay IDs

If you specify an overlay ID in the options string of the OpenOverlayURL command, you can later send a CloseOverlay command with that same string to remove the overlay. If you send an OpenOverlayURL with an overlay ID equal to an existing overlay, that overlay is replaced with the new one. If you omit the overlay ID, the overlay sticks around until the template changes (or forever if the persistent option is used).

Example

As a test, you can define a template with three buttons, each of which sends a RIVA Command to the client. Use the following settings (in each case, the four strings are the command and the three parameters).

First Button

OpenOverlayURL
http://207.251.86.238/cctv26.jpg?math=0.44182078493759036
200,20,352,240
overlayId=test,refreshInterval=3,scaleToFit=no

Second Button

OpenOverlayURL
http://207.251.86.238/cctv264.jpg?math=0.9366616716142744
200,20,352,240
overlayId=test,refreshInterval=3,scaleToFit=no

Third Button

CloseOverlay
test
[leave second and third parameters blank]

Pressing the first and second buttons should display Web cams of Times Square and the Long Island City, Queens approach to the Midtown Tunnel, each refreshing every three seconds. The third button should turn off the camera.

Image Cache

In accordance with the RIVA protocol, CQC Client maintains a cache of downloaded images. The cache is divided into three sections:

the CQC repository, containing images which are part of the template itself,
media art, which comes from the Covert Art Browser, and
everything else, which generally means Web image widgets.

Each of the three sections has a set capacity (I believe it is around 150 images at the moment). Items in the cache can be stored either in permanent storage (staying cached across application invocations) or temporarily in memory. Items in the repository cache are always stored permanently. Items in the other two sections are stored permanently only if they are below a size cutoff (24K on the iPad, 12K on the iPhone); otherwise they are stored temporarily in memory.

Low memory conditions may require the application to flush images from the cache. Least recently used images are flushed first.

You can browse the contents of the image cache. This is useful when trying to figure out whether template performance is being impacted by lack of cache space. On the main screen (listing the available server definitions), press Downloads on the tab bar at the bottom. This will bring up a display similar to the one shown at right, showing the contents of each of the three cache sections. For each image, the application displays the path (as sent by the CQC server), the host and port of the CQC image server (since images from different servers must be stored separately), the RIVA serial number of the image, and the file size (on the iPhone, rotate the device to landsapce orientation to see this). A check mark at the right indicates that the image is stored permanently.

Use the deletion controls at the left to remove an image from the cache or clear out an entire cache section.


Client Setup When you start CQC Client, the first screen you will see is the server list, which shows all the servers you have defined. By default the list is empty, so the first thing you need to do is create a definition for your server. To do this, touch the + button in the upper left to add a new server.

This will bring up the server definition screen. On the iPad, all options are visible at once. On the iPhone, tap the buttons at the top to switch between the pages of options. Name: a descriptive name for the server to be displayed in the server list Host: the host name (e.g. www.myhouse.com) or IP address (e.g. 192.168.1.15) Ports: the port numbers of the RIVA and image servers; usually, the defaults are correct User Name: the user name to use when logging into the server Password: the password associated with the user name
Status Bar: whether the phone status bar (with signal strength, time and battery level) should be hidden, or displayed with a black or (on the iPhone only) white background Scrolling: whether the template should never scroll, should scroll freely, or should scroll a page at a time Orientation: whether the output should always be displayed in portrait mode, should be switched automatically according to the phone orientation, or should always be displayed in landscape mode Orientation Hot Keys: whether the client should send hot key messages to the server indicating the phone orientation Gesture Hot Keys: whether gestures should be recognized and sent to the server as hot keys Background: the color to use when painting the screen background outside of the template; this is usually visible only when you scroll past the end of the template
Autoconnect: whether CQC Client should connect to this server automatically when it starts; the Wifi option tells the client to autoconnect only when connected via Wifi (you can have one server set to Wifi autoconnect and one server set to regular autoconnect at one time; if a Wifi autoconnect server is specified, and you are connected via Wifi, it takes precedence) Optimization: how to trade off display speed versus strict RIVA protocol compatibility: None means that the client downloads and draws each image before continuing to the next command in the RIVA stream Low means that the client attempts to draw the screen before images are fully loaded, and then redraw as images become available, but does not start processing a new set of drawing commands until the old set has been fully displayed (this was the default in earlier versions of CQC Client) High means that the client will proceed with drawing a new set of drawing commands before all the images are loaded on the old screen; if the new set of drawing commands fills the entire screen, any queued image download requests are flushed Protocol: which protocol version to use when communicating with the server. You should select the most recent version that your server supports. Version 4 is the default, but if you can't connect, try changing to an earlier version (or upgrading your server). The features introduced in each version: Version 2: explicit template sizes and sound Version 3: environment variables (the app uses version 3 if you choose version 2 but then define any environment variables) Version 4: the RIVA Command message High Resolution: on a device with a retina display, whether to display the template using the full screen resolution, so that a 480 by 320 template would take up only the upper left quarter of an iPhone screen; the default is for a 480 by 320 template to occupy the entire iPhone screen, as it does on earlier iPhones Idle Timer: how long the phone should wait before dimming the screen and then going to sleep to conserve power; this can vary from the iPhone default of about a minute when the slider is all the way to the left, up to 60 minutes when the slider is all the way to the right
Environment Variables: environment variable values to send; any nonblank variables are sent; requires the protocol to be set to v2 or higher (the app automatically shifts up to v3 if you specify v2 but then define any environment variables)

Enter the necessary information and press Done at the upper right. You will be returned to the main screen, and your server list will now show the server you just defined. You can add another server by pressing the + button again, and edit, reorder or delete servers by pressing the Edit button. But for now, press the server you defined. The display will "flip over", and a spinning indicator will appear in the center of the screen, with a cancel button below. If all goes well, these will disappear almost immediately when a connection is made to your CQC server, and the template will begin to load (a small spinner in the upper left corner of the screen lets you know that you are receiving data from the server). If there's a problem connecting, the spinner and cancel button will stick around on the screen. If they stay for too long, you probably are not making a good connection with the server. Click the cancel button to return to the main screen, check your server definition, and make sure that the CQC RIVA process is running on your server. Once you have connected, and are viewing your template, if you have the Gesture Hot Keys setting turned on, you can touch the screen with four (or more) fingers to bring up a menu that lets you: disconnect and return to the main screen, or edit the server settings (except for the connection parameters and the Hide Status Bar setting).