Crestron e-Control User manual

Crestron e-control™ Software Development Kit & CNX Gateway
Contents
Crestron e-control™: Software Development Kit &
CNX Gateway 1
Introduction ...............................................................................................................................1
What is Crestron e-control Software Development Kit? .............................................1
How do I Choose Whether to Use HTML/Java or ActiveX Components? .................2
What Other System Requirements are There?............................................................. 2
Installing the Software...............................................................................................................4
CNX Gateway Requirements ......................................................................................4
Installing From the CD-ROM......................................................................................4
Installing the SDK (Downloaded From the Website)..................................................4
Installing SIMPL Windows.........................................................................................4
Running the Demos ..................................................................................................... 5
Licensing the CNX Gateway .....................................................................................................5
Calculating the Number of Connections......................................................................5
Transferring an Existing License To Another Computer ............................................6
Setup ..........................................................................................................................................7
Hardware Setup of CNMSX........................................................................................7
Hardware Setup of CEN Series Devices .....................................................................8
Leading Specifications ................................................................................................8
Configure the CNX Gateway ......................................................................................9
Configure the Web Server ...........................................................................................9
Build the Application with ActiveCNX or Java ..........................................................9
Write the SIMPL Windows Program ..........................................................................9
Running ...................................................................................................................................12
Start the CNX Gateway.............................................................................................12
Getting Status Information from the CNX Gateway .................................................12
Start the Visual Basic Program or Web Page ............................................................ 12
Shutting Down the CNX Gateway........................................................................................... 12
Troubleshooting.......................................................................................................................13
Use of Ping or Telnet to Verify Communication.......................................................14
Use of Viewport ........................................................................................................14
Appendix A: Contents of the Crestron e-control SDK CD...................................................... 15
Gateway Folder: ........................................................................................................15
SDK Folder: ..............................................................................................................15
New_Dll Folder:........................................................................................................15
Appendix B: Recommended Reading......................................................................................15
Glossary of Terms....................................................................................................................16
Software License Agreement...................................................................................................18
Operations Guide - DOC. 5778A Contents •i

Crestron e-control™ Software Development Kit & CNX Gateway
Crestron e-control™:
Software Development Kit &
CNX Gateway
Introduction
Crestron e-control consists of two separate products – the Software Development Kit
(SDK) and the CNX Gateway. The SDK is a free download containing tools for
developing demo webpages or Visual Basic programs that have the potential to
communicate with Crestron CNX equipment. The CNX Gateway must be purchased
and licensed from Crestron. It is a software package that performs the actual
communication between the code developed by the SDK and the CNX equipment.
Demos created with the SDK will not be fully functional without the CNX Gateway
to “bridge” the communication gap.
For convenience, the CNX Gateway software package includes all the SDK tools.
What is Crestron e-control Software Development
Kit?
The Crestron e-control SDK is a complete software development kit, rather than a
standalone product. It contains software components, examples, and directions for
writing your own custom user interface to Crestron’s control systems and equipment.
The examples ARE finished products that actually work, but are probably too simple
for typical applications.
The Crestron e-control SDK encompasses two different technologies. You can
choose the one which best suits your application and your development capabilities.
The Crestron e-control SDK has both Web pages that contain compiled Java classes
that are usable from most browsers and an ActiveX control (dubbed
“ActiveCNX™”) that is usable from Visual Basic, Internet Explorer, or any other
ActiveX compatible development environment such as Visual C++.
Operations Guide - DOC. 5778A Crestron e-control™: Software Development Kit & CNX Gateway •1

Software Development Kit & CNX Gateway Crestron e-control™
How do I Choose Whether to Use HTML/Java or
ActiveX Components?
Use the HTML/Java/Web page method if you need platform independence (i.e., you
must run from Macintoshes as well as PCs) and you have the ability to write HTML.
At this time, Crestron does not provide any method for developing Web pages. We
suggest using a third-party Web page development tool such as Microsoft
FrontPage ’98 or AdobePage Mill to produce great looking Web pages without
having to code in HTML directly. The compiled Java classes that Crestron ships with
the SDK are used within the Web page to communicate with Crestron equipment.
The Web page method also means that no special software is needed to access the
Crestron equipment; the act of viewing the Web page is all that is required.
The latest version of VisionTools™ Pro (VT Pro-e) is able to produce HTML-
encoded Web pages, just as previous versions of VisionTools produces touchpanel
displays.
Use the ActiveCNX method if you want to program in Visual Basic to provide a
completely custom look to your interface, or you need a background non-visual
interface to Crestron control systems.
What Other System Requirements are There?
Refer to the diagram on the next page for a graphical representation of the required
system components.
1. The Crestron e-control SDK requires that there be a Windows 95/98 or
NT PC accessible on your network to run the “CNX Gateway”. The
Gateway is an application that routes packets from the SDK Java
components or ActiveX controls to Crestron’s control systems or
Ethernet-enabled (CEN series) devices.
2. If you are running the CNX Gateway and the browser on different PCs,
OR if you are using Internet Explorer as your browser, you must also
run a Web Server on the network, perhaps Microsoft’s own Personal
Web Server that is distributed free with Windows 95/98 or downloaded
from their Web site. The “CNX Gateway” and Web Server must be
running on the same machine to remotely access and control the system
from any LAN location.
3. The PC with CNX Gateway and all Crestron equipment must be
connected to the TCP/IP network and given static IP addresses.
4. SIMPL Windows, Crestron’s graphical programming environment,
must be used to program any control system that accepts commands
from a virtual Touchpanel, just as it is used to program the control
system to respond to wired or wireless touchpanels. A sample SIMPL
Windows program has been included in this SDK. Crestron’s Ethernet-
enabled devices (CEN series) can be controlled directly without any
special programming, if there is no control system, or if multiple points
of control are required. Of course, they can also be controlled through a
SIMPL Windows program running on the control system.
2 •Crestron e-control™: Software Development Kit & CNX Gateway Operations Guide - DOC. 5778A

Crestron e-control™ Software Development Kit & CNX Gateway
e-control™ System Architecture
A
ctiveCNX
Control
Clients
Server
VC++ VB IE
Web
Browser
Crestron
Network
A
ny Crestron
Controllable
Device
CNX
Gateway/
Web Server
Operations Guide - DOC. 5778A Crestron e-control™: Software Development Kit & CNX Gateway •3

Software Development Kit & CNX Gateway Crestron e-control™
Installing the Software
Depending upon where you received your e-control software, installation procedures
may vary. Currently, there are two ways to get a copy of the e-control SDK software.
1. Purchase the CNX Gateway from Crestron (you receive a CD-ROM).
2. Download the e-control Software Development Kit (SDK) from the
Crestron website.
If you have purchased the CNX Gateway from Crestron, then you should have
received a CD-ROM which contains both the CNX Gateway and the SDK software
necessary for doing custom programming. Using the SDK alone, you will be able to
develop solutions, but you will not be able to test them by connecting to a Crestron
control system. Contact Crestron for more information about licensing the CNX
Gateway.
CNX Gateway Requirements
The minimum system requirements for the CNX Gateway are as follows.
• Pentium 200
• 32Mb RAM (for Windows95)
64 Mb Ram (for Windows98/NT)
Installing From the CD-ROM
To prevent installation problems, you should exit all programs prior to running the
install application. Insert the CD into your drive. From the Start menu, select Run,
then click on Browse. Locate the CD-ROM drive, select “setup.exe" and hit OK. Hit
OK again to run it. Follow the instructions on the screen to install the software. By
default, this will install both the CNX Gateway and the e-control SDK on the
computer. If you want to install only one of these packages, you can simply uncheck
the check-box next to the component you do not want to install.
Installing the SDK (Downloaded From the Website)
If you download the e-control SDK from the Crestron website, you should have a
single executable file. Simply run this file by double-click on its icon. Follow the on-
screen instructions to complete the installation. Realize that this installation does not
include the CNX Gateway.
Installing SIMPL Windows
If you will be programming Crestron control system processors (as opposed to
controlling CEN series devices), you will need to install SIMPL Windows version
1.30.01 or later (with SIMPL Windows Library Update file, v62 or higher) and the
Crestron database. They are available on the Crestron ControlCD (v6.1 or higher),
that is available free for authorized Crestron dealers, or from our FTP site. The
SIMPL Windows release notes detail how to enable Ethernet access to the CNMSX
and how to program SIMPL Windows to respond to the SDK.
4 •Crestron e-control™: Software Development Kit & CNX Gateway Operations Guide - DOC. 5778A

Crestron e-control™ Software Development Kit & CNX Gateway
Running the Demos
NOTE: Change the communication component in the HTML code of the demo.
Make sure the IP address is the IP address of the control system. Also, the control
system programming needs to have the IP address of the CNX Gateway.
To run either of the CNMSX demo programs that are shipped with this SDK, use the
Viewport to load “Net Demo.bin". This file has been written for a CNMSX-PRO. If
you are using a unit without a front panel (eg., CNMSX-AV), then you should open
the file “Net Demo.smw" in SIMPL Windows and change the control system type to
the appropriate model. The program can then be recompiled and uploaded to the
actual unit.
Start the CNX Gateway running. The CNX Gateway IP Address of the computer is
displayed in a dialog box. From the Viewport in SIMPL Windows, assign the same
Gateway IP Address to IP ID 03. Click “Functions”, then “Setup IP Table…”. Click
“Add”. Set the IP ID to 03 and type in the IP Address. Click “Send IP Table to
control system”.
In each demo verify that the IP address is set to the IP address of your particular
control system and verify the IP ID is also set to 03.
Now the Visual Basic CNMSX or HTML demo can be executed.
Licensing the CNX Gateway
Unlike most Crestron software, the CNX Gateway is a licensed product, which
means that you may not freely distribute copies. Each individual copy must be paid
for and licensed. All licenses for the CNX Gateway must be purchased from
Crestron. Each Gateway license is designed to work only on a single machine.
Because of this, you must provide Crestron with the “Site Code” for the computer
you plan to run the Gateway on. Crestron can then issue the appropriate “Site Key”
to enable your software.
Install the Gateway if you have not already done so, and run it. If it has not yet been
licensed, a licensing window will open automatically. Contact Crestron Customer
Support with the “Site Code” given in the this dialog and the number of connections
you wish to purchase (connections are discussed in more detail below). You may
also cut and paste the site code into an email message if you prefer. Address the
email to [email protected]. Crestron Customer Support will issue a “Site Key”
which must be typed or pasted into the Site Key field. Once entered, click on the
Update License button.
If you do not want to wait for the site key to be issued, exit the program. It can be re-
started at any time. The same site key will always be valid on the same PC. The site
key will not work on a different PC.
Calculating the Number of Connections
The number of connections needed is determined by the overall system
configuration. The number of connections equals the number of computer users
(those using e-control SDK’s Java components or ActiveX components), the number
of CNMSX control systems being accessed, and the number of CEN series
components being accessed directly (not through a CNMSX). Connections over and
above the licensed number will be refused. Licenses can be upgraded to support
Operations Guide - DOC. 5778A Crestron e-control™: Software Development Kit & CNX Gateway •5

Software Development Kit & CNX Gateway Crestron e-control™
additional connections by calling Crestron Customer Support and getting a new site
key.
Transferring an Existing License To Another
Computer
As mentioned above, a license is only valid on the computer for which it was
obtained. However, a license can be transferred from one computer to another. There
are several reasons to transfer a license. The application developer may set up the
system off-site, then transfer the license to the actual computer on-site when ready.
Alternatively, if the hardware or operating system on the computer where the CNX
Gateway is licensed is upgraded, the license ceases to be valid. However,
transferring the license to another computer before the upgrade and then back to the
original machine after the upgrade avoids any possible problems.
On both the source computer (where the license is currently valid) and the
destination computer (where the license will be transferred), make sure the CNX
Gateway is installed and running. If the Gateway “Update/Transfer License” window
is not displayed, right-click the CNX Gateway icon in the system tray and choose
Properties. Click on the About tab and select the Update License button to bring up
the “Upgrade/Transfer License” window. Make sure this window is active on both
computers.
On the destination computer, create a preparation file on a diskette in the A: drive by
inserting a blank diskette and selecting Prepare Diskette. This will create a file on
this diskette which indicates who will be receiving the license. Alternately, this file
can be created on another portable media (e.g. Zip disc) or a network drive by simply
using the “Windows Open” dialog to browse for a new file location. When
transferring via a network drive both computers need read/write access to the drive
being used.
After the last step has completed, remove the diskette from the drive and insert it into
the source computer’s floppy drive, and click on the Transfer License. The source
computer will read the preparation file to see which computer wants the license. It
encodes the license with the destination and writes it back to the same file on the
floppy diskette (or network drive). The source computer has now passed the license
to the file. Only the designated computer can use the license, so the CNX Gateway is
no longer licensed on the source computer.
NOTE: At this point in the transfer procedure your CNX Gateway license resides
on a file on the diskette or network drive, and not on the computer. If this file should
become lost or damaged, your license will be lost as well. Because of this, please use
the utmost care while performing this transfer.
Bring the diskette back to the destination computer. Click on the Transfer License
button. The computer reads the license information off the diskette and transfers the
license to itself. The CNX Gateway should now be licensed on this machine.
6 •Crestron e-control™: Software Development Kit & CNX Gateway Operations Guide - DOC. 5778A