Configuring CrestronMobile v3

CrestronMobile v3 has two operating modes:

• a compatibility mode where it works the same way CrestronMobile v1 did
• a configured mode where you can provide one or more configuration objects that tell CrestronMobile how to operate.

Compatibility mode

The first mode is simple: at startup, it looks for an external TCP system named "CrestronMobile". If found, a new CrestronMobile object is instantiated. This object is configured to talk to a Crestron processor via your GUI's CrestronMobile external system.

The password to connect to the Crestron processor should be stored in a global (Project) token named cmPassword. If this token is missing, the default password (1234) will be used.

Configured mode

This is the new operating mode for CrestronMobile v3. When using the configured mode, you can connect simultaneously to several Crestron processors, and make a very precise configuration for each system.

Providing the configuration information

On startup, CrestronMobile will go through every external system defined in your GUI. For each TCP system it finds, it will look if a global JavaScript variable named CrestronMobileConfig_{system name} is defined.

If this variable is defined and is an object, then a new CrestronMobile object (one object connects to one Crestron processor) is created. The process goes on for every TCP system found in your GUI.

So for example, if you have three Crestron processors and name the external systems in your GUI: Crestron1, Crestron2 and Crestron3, you can create three configuration objects (see below) named CrestronMobileConfig_Crestron1, CrestronMobileConfig_Crestron2 and CrestronMobileConfig_Crestron3 to have the CrestronMobile module automatically create connections to the threee processors at startup.

Features

The configured mode has a number of powerful features you can take advantage of when developing large projects:

Per-processor join assignments

Each processor connection can be configured to manipulate only a specific set of joins from your GUI. This can be the joins related to objects on one or more pages, arbitrary additional joins, and you can even specify joins to exclude from the dialog.

This way, you can reduce network traffic and memory use, limiting unnecessary join updates sent to all processors when only one should receive them.

Per-page joins

When you specify the names or name patterns of pages to assign to a processor, CrestronMobile will go through the specified pages and pull the join informations of all the objects used in these pages (and the subpages they refer to). All the elements contained in the pages (in both Portrait and Landscape orientations) will be looked at, and their joins will be collected. The software also looks at the subpage references and goes through the contents of of every referenced subpage (including the join associated with the subpage reference itself) and binds them to the same joins on the processor.

Additional joins

If you want to bind additional joins that are not in your specified list of joins, you can list them in the additionalJoins property.

Exclusions

In some cases it may be useful to be able to say: "bind all the joins on these pages to this processor, but leave out this and that join". For example, a connection / disconnection indicator typically is a local join used within iViewer and should not be bound to its value on the processor. List all such joins in the optional excludedJoins list.

Password configuration

The configuration object contains the password to use when connecting to a specific processor. You can perfectly have multiple passwords (one for each processor).

Configuration details

A configuration object is a JavaScript object with named properties. Here is an example of a complete configuration object:

var CrestronMobileConfig_Crestron1 = {
    // A list of pages for which we are monitoring all joins of. A page name can be a regular expression
    // In a given page, joins of all elements (including elements in referenced subpages) will be processed
    // If you omit this property or set it to null or to an empty array, all pages will be looked at.
    pages: [".*"],

    // An optional additional list of joins we also want to handle,
    // that don't match objects in defined pages
    additionalJoins: [ ],

    // An optional exclusion list that allows you to exclude joins in the relevant pages
    // from interaction with the Crestron processor
    excludedJoins: ["d9000"],

    // The password to use to connect to this Crestron processor
    password: "1234"
};

The example above highlights what can be specified by a configuration object:

• pages (Array): a list of page names or patterns (regular expressions) from which CrestronMobile will obtain the joins to bind to the processor (see Per-page Joins above). If this property is omitted or null, all the pages will be looked at. If it is an empty list, you can specify the joins to bind in the additionalJoins property.
• additionalJoins (Array): an optional list of joins to bind to the processor, in addition to the ones pulled from the pages specified in the pages array.
• excludedJoins (Array): an optional list of joins to exclude from binding, so as to make sure they are never updated by a change on the processor.
• password (String): the password to use when connecting to the processor. If ommitted, the default string 1234 will be used.