Tcl Tool User Guide

0
Revision History
Date Version Changes
05/08/2018 1.0 Initial release.

1
 Table of Contents

Introduction ....................................................................................................................................... 3

Creating a New Project ...................................................................................................................... 4

Configuring Module Properties .......................................................................................................... 8

Adding System Scripts ........................................................................................................................ 9

Configuring System Properties......................................................................................................... 10

Configuring Built-In Properties ........................................................................................................ 13

Writing the Code .............................................................................................................................. 21

Generating the Output Files ............................................................................................................. 25

Creating the Driver ........................................................................................................................... 26

Deploying the .TCM2 File ................................................................................................................. 32

Importing the .TCM2 File / Downloading to Base Station ............................................................... 33

2
Introduction
Tcl Tool is the primary IDE (Integrated Development Environment) that you will use to create URC two-way modules. You may prefer to use external third
party tools for certain parts of the development process (such as editing your code), but Tcl Tool is essentially where you will create and configure your project
and ultimately generate the output files needed to run your module on a URC system.

3
Creating a New Project
To create a new project, go to File -> New. A window will pop up, prompting you to choose a device type:

4
There are three device types to choose from for your module: General Device, Dynamic Interface + Core (DIC) and AVR/Multizone. For our example project,
“Hello World”, we’re going to select General Device since it is the most basic of the three. DIC and AVR/Multizone will be covered in detail later on in this
guide.

Once you’ve entered the name of the project and chosen where to save it, click Next. You will be prompted to enter information for the module’s built-ins.

Built-Ins

Built-ins can be thought of as “submodules” within your main module project. For example, let’s say you’re creating a module for a whole-home system
that handles lighting, climate control and security. You may feel that this is too broad a range of functionality to be handled by a single user interface, but
you still want to present (and develop) the module in as unified a way as possible. By creating three built-ins for your module (one for lighting, one for
climate control and one for security), you can achieve this objective. This will allow you to create three completely different user interfaces with different UI
code that all share the same system (non-UI) code and can all be conveniently packaged within a single output (.tcm2) file.

5
For our project, we will not be including any actual built-ins, so we’re going to add the module as “Device itself” and click OK:

In the Built-In List, you will see “[Self]”. Click “Next” and you will be presented with the Client Information window:

6
Here, you will select any of the client interfaces you want to include in your project. For our example project, we will add Tablet and Phone, which should be
checked by default. Click “Ok” when finished. Don’t worry if you forgot to add a client or added one by accident. You will be able to add or remove clients at
any time during development.
Once you’ve clicked “Ok”, your project has been created and you should see a screen similar to the one below with a Project Tree reflecting the project settings
you’ve just configured:

7
Configuring Module Properties
The module properties window can be accessed by clicking on the root of the Project Tree (the name of the project). When highlighted, you will see the
properties window on the right side of the screen. It contains all of the more general or “universal” properties of the module:

1. Device Name
This is just the name of the project. Make sure not to confuse this with the actual name of the module.

2. Developer’s Company Name

Enter the name of your company here.

3. Device Type
This will be set to the device type that you chose when you first created the project.

4. Version
The version number of the module. URC does not require that a third-party module use a specific
versioning format, but we recommend that you stay consistent with whichever format your company
chooses.

5. Min. TC Version
The minimum version of Total Control required to run the module. For any new development, this should
always be set to the default option, 2.0.

6. Description
Provide a brief description of the module.

7. Built-In Information
This will display any built-ins you’ve configured for the module.

8. Zone Information
Ignore this field unless you are creating a module for a multizone device.

9. Client Information
This will display all the client interfaces in the project.

10. Support Type

Here, you can configure the IP or Serial (RS-232) settings for the module.

8
Adding System Scripts
Now that our module’s general properties are configured, let’s add our main or “Master” Tcl system script. Right-click on “System Scripts” in the Project Tree
and select “Add File”. It will prompt you to enter a filename.

Once you click “OK”, you should see the filename appear under “System Scripts” in the Project Tree. If you open up your project’s folder and navigate
to …\Source\BStation, you will see the newly created source file. The BStation folder will be where all the source code for your project resides.

You may add as many additional system scripts as you’d like. Utilizing several Tcl source files to handle the various features/functions of a module can help to
make your project more organized and modular. To keep things simple for our example though, we will stick with just the master script.

9
Configuring System Properties
Click on “System Scripts” in the Project Tree. The Properties window will populate with all of the System properties:

1. Master Script
This will be the main script of the module. This is the source file that the base station will execute
upon startup, so the code to initialize the module needs to reside within it.

2. Output
This will be the name of the .vfd file that the system source code is exported to. For URC
certification, the accepted format is “CompanyName_ModuleName.vfd”

3. System Parameter
This is where you will configure system parameters if applicable. System parameters are data that
gets passed into the system script at the start of a module’s execution. You have the option of
adding the parameters as a string in the “String” field, or placing the parameter data in an xml file
and then importing the file (this is usually the better option, as it allows more flexibility and
structure). While the file does need to have a “.xml” extension, its contents do not need to be valid
xml. The file can contain plain text or even JSON data. The module will be parsing it, so use
whatever format suits your module’s needs best.

4. Unified Types
N/A (For future use)

5. APK
N/A

So, let’s start by selecting our master script. Since helloworld.tcl will be the only system script for this project, we will select it as the master.

10
Next, we’ll enter our system vfd file name as URC_HelloWorld.vfd per URC certification guidelines. For this example, we’re going to have the system
parameters come from an xml file, so let’s take a moment to create it. We’re going to call it system_param.xml, but you can call it whatever you’d like.

Here is what our file looks like:

Now, let’s go back to the System Properties in Tcl Tool and import it using the “Browse” button. You have the option of making the parameter user-editable
(by the installer) once the module is imported into the URC Programming software. We want this for our example, so we’re going to check the “User Editable”
box.

11
Once you’ve done all of this, your System Properties window should look similar to this:

12
Configuring Built-In Properties
Each built-in present in a module contains one or more client UIs. Say, for example, that you have two built-ins – one for lighting and one for climate control.
Each of those built-ins might have a Tablet-type UI, a Phone-type UI and a Remote-type UI.

! All built-ins must support the same set of clients. Tcl Tool will not allow you to include a client UI in one built-in without it
also being included in the others within the module.

We will now configure the properties of our single “Self” built-in. Click on [Self] in the Project Tree. The Properties window will populate with the built-in
properties for [Self]:

13
1. Name
The name of the built-in.

2. Launch Script
This is similar to the “master” script we saw earlier in the system properties. It is the client script that will
be executed whenever a UI is launched on a client interface.

3. Built-In Source
This can be ignored. It will always show the name of the built-in.

4. Zone Information – Module Title

This is where you provide the actual name of the module that will be displayed in the URC programming
software once the module is imported into it. If our example contained multiple zones, the drop-down
list would be enabled and we would be able to select each zone and edit its name.

5. Zone Information – Module Parameter

This is similar to the “System Parameter” field we saw earlier. While the system parameters apply to the
entire module, the module parameters only apply to a particular built-in. So, for each instance of a
module, there will be module parameters for each of the module’s built-ins.

6. Output
This will be the name of the .vfd file that the client source files are exported to.

7. Icon File
This is the icon for the module launching button that will appear on the screen of each client interface.

8. Unified Types
N/A (for future use)

14
Let’s start by adding the launch script. We currently don’t have any client scripts available to select as the launch script, so let’s create one now. Right-click on
“Module Scripts” in the Project Tree and select “Add File”. It will prompt you to enter a filename. Enter the name helloworld_client.tcl:

You will see the new file appear under Module Scripts in the Project Tree:

Once again, if you check the source folder for your project (…\Source\BStation), you will see the newly created file. If you open it up, you’ll also see that it’s
completely blank. We won’t write any actual code just yet, since we’re just trying to get everything set up at the moment.

15
 ! The name of the launch script must begin with the full name of the master system script, followed by an underscore. So, for
example, if using a master script named helloworld.tcl, the launch script must begin with “helloworld_”.

Go back to the built-in properties (click on [Self] in the Project Tree). Click on the drop-down list next to “Launch Script” and select helloworld_client.tcl.

Next, we’ll add our module title: “Hello World”.

Now, we’ll configure our client/module parameters. Earlier, when we configured the system parameters, we chose to put them in an XML file and allowed
them to be user-editable. This time, for our client parameters, let’s try putting them in a string and disabling user editing. Leave the “User Editable” box
unchecked, select “String” and type “Hello World!”.

Next, let’s take a look at the client output (.vfd) file name. By default, it should be the name that was chosen for the system .vfd file, except with “GUI”
appended to the end of it.

! The name of the client output filename must be in the format [SystemOutputFileName]GUI.VFD. So, since our system
output file is called URC_HelloWorld.vfd, our client output file is URC_HelloWorldGUI.VFD. If for some reason it is not in this
format, be sure to correct it before continuing. The module will not work properly if this formatting is not followed.

16
Finally, we need to add the icon file. Pick an icon that you’d like to use for this project. There are a few restrictions for the icon:

1) It must be a .png file.

2) It must be exactly 675x450 pixels.
3) The filename must be in the format [IconName]_[HexRGBCode].png (i.e. ABC Security_8E2B2B.png)

HexRGBCode is a web-format hexadecimal number that represents the color of the label area where the title of your module’s launch button will appear
onscreen. Below is a picture of the launch button for our example icon ABC Security_8E2B2B.png. Notice the color behind the text. This is the color
represented by HexRGBCode.

To make your launch icon look best, choose a HexRGBCode color that complements the colors used in the icon itself. Darker colors provide better contrast for
the white label text.

17
Your built-in properties have now been configured and should look similar to this:

18
Now, you may notice that under Tablet and Phone in your Project Tree, it still says “Missing UI Data”. This is because we have not yet created the .dat files that
contain the Graphical User Interface. This GUI is created using the UI Tool program, which can be found under the “Tool” tab of TCL Tool.

Before proceeding, please refer to the UI Tool User Guide and follow Tutorial 1: Hello World.

Now that you’ve completed Tutorial 1 in the UI Tool User Guide, you should have a file called HelloWorld.dat for the Phone UI. So, what about the Tablet in
our project? Well, we could go back to UI Tool and recreate the UI, this time doing it specifically for Tablet. But, there’s an alternative …

If streamlining and speed of development is a priority for you and you don’t mind (or actually prefer) that the Phone and Tablet share the exact same UI, you
will benefit from Phone-Tablet Linking. For our example project, we are going to utilize this feature.

Phone-Tablet Linking

With the phone and tablet interfaces having similar proportions and capabilities, you may often find that it makes the most sense that the two interfaces
share a UI. As of Total Control version 2.0, that is made possible by utilizing the linking feature in TCL Tool. To link the Phone and Tablet together, first make
sure you have both the Phone and Tablet interface present in your Project Tree. Then, right-click on “Tablet” in the Project Tree and select “Link with
Phone”:

19
Now, you can go ahead and add the .dat file by first clicking on “Missing UI Data”. Then, in the Properties window, click “Browse” and import the file. You
should see the following screen once you’ve imported hit.

You should now see the .dat file name in the Project Tree:

20
Writing the Code
It is now time to write the Tcl Code for our Hello World project. Let’s start with the master system script we created earlier. You can double-click on
helloworld.tcl in the Project Tree to open this file in Tcl Tool. Alternatively, you can open it in your favorite text editor. We actually recommend using a text
editor that supports Tcl syntax highlighting such as Notepad++ or Atom. The text editor in Tcl Tool, while convenient for quick viewing and editing, lacks syntax
highlighting and other more advanced features/functionality and is therefore not suited to serve as a comfortable environment for extended code writing
sessions.

The first thing we need to do when starting a new master script is to load the URC API packages. Refer to the “Project Setup” section of the URC Tcl API
Documentation for details on this. Your code should look like this:

#=================================================================================================================================
# helloworld.tcl
#=================================================================================================================================

source [file dirname [info script]]/URC_API.tcl

::URC::LoadPackages {URC::LOG 1}

#=================================================================================================================================

Since this is a very basic module, our system script code is going to be fairly simple and straightforward. We’re only going to have the system script do two
things:

1) Output a log message to indicate that the script has started execution.
2) Parse the system parameters we created earlier and log their values.

As you can see in the code above, we only load a single package, the LOG package. This is the only package we need to accomplish our two objectives.

So, let’s start with objective #1:

#==========================================================================================================
# helloworld.tcl
#==========================================================================================================

source [file dirname [info script]]/URC_API.tcl

::URC::LoadPackages {URC::LOG 1}

21
::URC::LOG::Trace "Starting helloworld.tcl..."

#==========================================================================================================

We’re using the Trace procedure because we’re outputting a message whose main objective is to “trace” the execution of the code, letting us know where
exactly we are in execution. For more information about the various types of LOGs, refer to the URC Tcl API Reference.

Now, let’s move on to objective #2: Parsing the system parameters…

To get access to the system parameters, we need to call the procedure ::URC::Settings::Get::Parameters. We can then parse through the
contents, extract the values of each parameter and log them:

#==========================================================================================================
# helloworld.tcl
#==========================================================================================================
source [file dirname [info script]]/URC_API.tcl
::URC::LoadPackages {URC::LOG 1}

::URC::LOG::Trace "Starting helloworld.tcl..."

set params [::URC::Settings::Get::Parameters]

set paramList [split $params "\n"]

set param1 -1
set param2 -1
set param3 -1

foreach param $paramList {

set propertyValuePair [split $param "="]
set property [lindex $propertyValuePair 0]
set value [string trimright [lindex $propertyValuePair 1] "\r\n"]
switch -nocase -- $property {
"PARAM1" {set param1 $value}
"PARAM2" {set param2 $value}
"PARAM3" {set param3 $value}
default {::URC::LOG::Warning "Invalid parameter: \"$property\". Cannot parse."}
}

22
 ::URC::LOG::Info "$property = $value"
}

#==========================================================================================================

Save your file. We’ll test it out and check our results when we download to the base station later on.

Now that our master system script is ready to go, we’ll go ahead write our master client script, which will have the responsibility of manipulating the UI. The
first few steps are going to be the same as they were for the system script, except this time we’re going to load URC::UI in addition to URC::LOG:

#==========================================================================================================
# helloworld_client.tcl
#==========================================================================================================

source [file dirname [info script]]/URC_API.tcl

::URC::LoadPackages {URC::LOG 1} {URC::UI 1}

::URC::LOG::Trace "Starting helloworld_client.tcl... "

#==========================================================================================================

You may be wondering why we need to load the LOG package again. The reason is that the client script and the system script do not execute in the same Tcl
interpreter. In fact, for every single client device in your project, a new Tcl interpreter will be instantiated on the base station when a module is launched on
that client. So, even though the LOG package gets loaded when the system script starts, the client script cannot utilize it because it does not exist in it’s
interpreter’s memory.

In Tutorial 1: Hello World from the UI Tool User Guide, you created a basic UI with a text field. Our goal is to parse our client parameters and display them in
this text field.

Since we chose to make our client parameter a simple string with no line breaks, there actually isn’t any parsing to do. We can directly set the text field to the
value of the parameter using the URC::UI::Set::Text procedure and then display the main page using the ::URC::UI::Display::Page
procedure:

23
#==========================================================================================================
# helloworld_client.tcl
#==========================================================================================================

source [file dirname [info script]]/URC_API.tcl

::URC::LoadPackages {URC::LOG 1} {URC::UI 1}

::URC::LOG::Trace "Starting helloworld_client.tcl..."

set param [::URC::Settings::Get::Parameters]

::URC::UI::Set::Text txt_main $param
::URC::UI::Display::Page page_Main

#==========================================================================================================

That’s it! Our client script is complete. It’s now time to generate the output .vfd files and deploy our module.

24
Generating the Output Files

First, make sure you’ve saved your project file. Then, on the “Tool” tab, click “Generate”. You’ll be prompted with the following window:

Click on “Generate”. You should see a message indicating that the operation was successful. If you get an error message saying that the operation failed, the
“Output” area should give you details about what caused the failure.

25
Creating the Driver
Since this is the first time deploying the .tcm2 file for our Hello World module, we first need to take a moment to create our module’s driver in the URC
programming software, as the “Deploy” step will require it.

Open up you URC Accelerator 2.0 software and click on ”My Database” on the top banner. Then, select “New Driver”:

26
Select “Start Blank – Device Not Found” at the bottom of the “Create a New Driver” window:

27
Select “Non AV General Device” and click “Next”:

28
You should now see the driver-editing window:

29
Under “Brand”, enter your company name as you would want it to be displayed in Accelerator’s database.

Under “Models”, click “Add” and add the name “Hello World”.

! All model names listed under a single brand MUST be unique.

In the dropdown menu under “Device Type Category”, let’s choose “AUX” since our module doesn’t really fit any other category.

Leave “Default Sub-Menu” as “None/Top Level”.

Click the “Edit” button next to “Control Types”. Select “Two Way/Advanced Module Only” and click “OK”:

For Project Tree Name, let’s call it “Hello World”.

We can leave “Icon” blank, as the icon will be the one we imported while configuring our module’s built-in properties in Tcl Tool.

Finally, uncheck the box on the bottom right that says “This Device is an AV Source or Switcher”.

30
You may have noticed that we skipped a crucial step here. We didn’t add a 2-way .vfd file:

The reason is that our vfd files have not yet been imported into Accelerator. So, what we’re going to do is save our driver file as-is, deploy our .tcm2 file (with
the driver included), import the .tcm2 into Accelerator and then update our driver to include the .vfd files that have just been imported by way of the .tcm2.

So, go ahead and save your driver file as helloworld.cd2.

31
Deploying the .TCM2 File
In Tcl Tool, under the “Tool” tab, click “Deploy:

You will be prompted to include a custom driver. Click “Yes” and add the driver file you’ve just created. You’ll then be prompted to add additional driver files.
Click “No”. You’ll be prompted witht the “Deploy” window. Check the boxes next to Phone and Tablet and click “Deploy”:

You will be prompted to save your .tcm2 file. You can save it in the root of your Hello World project folder or wherever else you’d like.

32
Importing the .TCM2 File / Downloading to Base Station

! This section assumes that you already have basic experience programming with the URC Accelerator software.

Open up URC Accelerator and create a new file. Add Phone and Tablet to the project and save. Next, click File, select “Import TCM Files” and open the .tcm2
file you just created. You will be prompted with the following screen:

33
Confirm that all the information is correct and click “Import”.

Interface Support

You’ll notice that your module supports several interfaces besides just iPhone/Android phone and tablet. This is because Phone and Tablet are form factors
rather than singular interfaces. As such, they are utilized by several of the devices in URC’s product line that conform to them.

Your module has now been imported into Accelerator. All of it’s output files have been unpacked and placed in their appropriate directories within the
Accelerator program folder. However, there’s one last step before the module is ready to be added to our Project Tree. Remember when we were creating
our driver and skipped the part where the system .vfd file is selected? Well, since our .vfd files have been imported into Accelerator via the .tcm file, we can
now go back and do that. So, go ahead and open up the driver file again (My Database -> Edit Driver). Click “Select Module” and you should see a window pop
up with your module’s .vfd file inside:

Select it and click “OK”. You’ll see another window pop up with some information about the file. Click “Apply”:

34
Your driver file is now complete and the module is ready to be used in your project. However, make sure to re-deploy your .tcm with the updated driver
included before releasing your module.

Click on “Program” at the top of Accelerator and go to Step 4. Under item 2 (Select Database), select “My”. In the drop-down menu under item 3 (Select
Module Type), choose “Two/Way/Advanced Modules”. Under item 4 (Select Category), choose “AUX”. Under item 5 (Select Brand), you should see your
company name. After selecting it, you should see the model HELLO WORLD under item 6 (Select Model). Finally, under item 8 (Select 2-Way…), you should see
the name of the built-in with a checked box next to it (This is the name that you added while configuring the built-in properties earlier in Tcl Tool):

35
36
Click “Add Selected Modules” to add the module to your project. You should now see the module in your Project Tree:

There’s now just a few quick things we still need to do before downloading to the base station…

Go to Step 6 (Network Setup) under “Program” and click on “URC Device” to configure your base station’s network settings. Next, click on “Non URC Device”.
You should see the module listed. Although the module will not be connecting to any device to control it, we recommend adding a fake IP address (i.e.
0.0.0.5), as this ensures the persistence of the device’s settings as you add and remove other devices from your project.

Next, go to Step 10 (Edit User Interfaces) and Accelerate.

Go to Step 11 (3rd Party 2-Way Settings). You should see the client parameter that you added as a string as well as the system parameter that you added as
an .xml file in Tcl Tool:

37
38
Next, go to Step 12 (Macro Editing) and Accelerate.

Click on Step 14 (Themes & Graphics). You should see your module along with it’s launch icon:

It is finally time to download! Click the “Download” button on the top banner and download the project to your base station. Once it finishes downloading
and reboots itself, launch the module on your phone or tablet device. You should see the text “Hello World!” printed on the screen.

39