prontoscript_installers_guide(1).pdf

Installer’s Guide

ProntoScript Installer’s Guide

ProntoScript Installer’s Guide Version 1.0

Preface This is the first edition of the ProntoScript Installer’s Guide. It is targeted towards installers that want to integrate rich 2-way applications for the Pronto Platform. Programmers that want to develop such 2-way modules are not the intended audience. For them we have provided the “ProntoScript Developer’s Guide”.

Using this guide Realizing reliable, easy-to-use two-way Home Automation and Entertainment systems is a demanding job, even for the very experienced custom install professional. A certain level of knowledge and experience with one-way control systems is required before taking on the two-way challenge:

• The Pronto Control System with Panels, Serial and Wireless Extenders • Basics of TCP/IP Networks • RS-232 control of AV and Home Automation components • Multi-zone control

That being said, Philips is trying to make the job as easy as possible for you with a set of consistent ProntoScript modules, developed by or in cooperation with our integration partners.


Version 1.0 ProntoScript Installer’s Guide

Table of Contents PREFACE 2

USING THIS GUIDE ............................................................................................................................2 TABLE OF CONTENTS 3 1. INTRODUCTION 4

1.1. GETTING A TASTE FOR PRONTOSCRIPT..................................................................................4 1.2. ADDING A PRONTOSCRIPT MODULE TO A PRONTO PROJECT: OVERVIEW ...................................5

2. MERGE-IN A MODULE XCF 6 3. INTEGRATE THE MODULE INTO THE NAVIGATION STRUCTURE 8 4. CONFIGURE & TEST 9

4.1. SETTING PARAMETERS ON THE [PARAMETERS] PAGE HANDS-ON ........................................10 5. PRONTOSCRIPT MODULE UI CUSTOMIZATION 11 6. CONCLUSION 12



1. Introduction

1.1. Getting a taste for ProntoScript

• Download the ProntoScript Tutorial Example from the Pronto website. • Open in ProntoEdit Professional (version 1.1 and up) • Download to the Pronto TSU9600 • On the Welcome page, press . On the Home Page, select the Calculator (last button) • Try it …

If you’re familiar with Pronto, you know this is something that can not be achieved with the traditional Pronto tools like page jumps… there’s something more here and it’s called: ProntoScript So what is ProntoScript?

ProntoScript is a powerful, flexible programming tool to realize two-way modules on the Pronto platform.

What matters most to the custom install professional is the last part: ready-made two-way modules to be plugged into any new or existing automation project. Before we continue to explain step by step how to add, configure and deploy a two-way module to a Pronto project, let’s try some examples in the same Tutorial that actually retrieve information from the outside world (the “two” in two-way )

• You need a wireless access point connected to the internet (without proxy server) • In System PropertiesàWireless Settings, configure the Pronto to connect to this access point

(see the Editor’s Help: Basic ActionsàHow Can I…? àConfigure the Communication Method of the Control Panel) • Instead of the Calculator, try the button “TCP Connect”

Here you see the Time and Data as they are fetched from the google site. Another more in depth example is the “TCP Connect 2”.

• Press “Connect”, a green server status indicates a successful connection (to example.com) • Press “Get Page”: a small html page is retrieved and displayed as ASCII text

If you feel like experimenting more, try to get the data from other URL’s, but expect to see much bigger pages being displayed.



1.2. Adding a ProntoScript module to a Pronto Project: Overview Adding a ProntoScript 2-way module to a project consist of 4 logical steps 1. Merge-in a module xcf The module appears as a Device/Activity in the tree view 2. Integrate the module into the navigation structure Add jumps from the Home Page (and Activity Shortcut Bar) to the module 3. Configure & Test Edit the [PARAMETERS] page to configure IP address, IP port, Extender ID & Ports etc. Test-drive the module 4. Deploy and Backup Deploy with in your real life project Archive the latest version of integrated xcf Train the end users to familiarize them with a 2-way control system In the next chapters we will explain each of these steps in more detail. For customizing graphics/backgrounds of existing ProntoScript modules, see Chapter 5 ProntoScript Module UI Customization



2. Merge-in a module xcf 1. Open the project you are working on in ProntoEdit Professional 2. In the Menu: FileàMerge Configuration:

Browse to the ProntoScript module and open



The Result:

A Home and Module Device/Activity have been added. The Home is not strictly necessary and can be deleted. It does however have a jump to the default hidden [TESTING] page, which can be useful during configuration testing. The Module, in this case an “Example Module” has a standard structure:

• One or more UI pages • An [INSTRUCTIONS] page where the module maker explains you how to configure its

parameters • A [PARAMETERS] page where you can change the module parameters • An optional [RESOURCES] page that should not be altered to insure proper operation of the

module • An optional [TESTING] page that contains unit tests to debug the module within the actual

project context. Before we start to actually use and test the module we’ll first wire it into the navigation structure of your project.



3. Integrate the module into the navigation structure In the most basic systems this means, adding a button to the home page that represents the two-way activity (e.g.: control lights) and adding in its actions, a jump to module. The standard punch through of the Home button takes care of complete, closed loop navigation. Projects based on the Pronto Basic Configuration template work this way. (see Editor’s Help: Creating Jobs starting from a Philips xcf à the 6 steps for customizing the basic configuration file) More complex systems, e.g. those based on the Pronto Multi Room template will require some more work: access from one or more zone pages, quick access from other activities. Regarding quick access from within other activities you should consider whether the two-way module activity is a helper-activity (e.g. tweak lights, temperature, two-way zone-volume etc.). In this case you typically want to “browse back” to the main activity (Watch TV, DVD etc.). You don’t want to re-execute the complete activity. This can be achieved by adding the “browse backward action” instead of explicit page jumps or navigating via Home. The Pronto team proposes to the module developers and installers to use the left firmkey as the default location to add this “Back” navigation.



4. Configure & Test The next step is to configure the two-way module to work correctly in your particular project situation. This typically involves setting a number of parameters to establish connectivity: For TCP/IP based modules:

• IP Address or Host Name (e.g. 192.168.1.100 or “Fireball”) • IP Port (e.g. 80, 8080, … ) • System ID or Address

Many vendors have internal addresses to distinguish between multiple instances of the same component in a system (e.g. thermostats, lighting pads)

For RS-232 based modules

• Extender id (0,1..9,A..F as found on the back of the extender) • Extender serial port number

Please Note:

1. In order for ProntoScript to be able to access a particular extender, it has to be defined, “declared” at system level

The extender as it can also be defined at Device/Activity level, e.g. for Power Sense commands, are not being used by ProntoScript: Therefore it is required as a mandatory parameter in the [PARAMETERS] page.

2. The same goes for the Extender serial port number: it has to be an explicit parameter. Please note that on the Extender, the ports are numbered from 1 to 4 where as a (JavaScript) programming convention, they are numbered as 0 to 3 in ProntoScript. Read the [INSTRUCTIONS] page to check which convention the module maker has chosen. If in doubt, set the parameter to 1 and see which extender serial LED’s blink when testing. It can be port 1 or port 2, depending.

This brings us to testing the module. We propose the following approach:

• After configuring the essential parameters, give it a quick round of testing: if your module “comes to life”, you’ve made a big step and you can iteratively maximize the functionality. It gives a boost of confidence to see these “signs of life” when trying something new ☺

• If after some attempts, you have no success, i.e. you see no sign of life, it may be best to take step back before getting frustrated… have a look at the following checklist

1. Do I have basic connectivity?

1. Is my panel connected to the router? (check on device settings) 2. Am I seeing the extender? (see on device diagnostics or editor discovery) 3. Does it receive basic IR commands? Check LED’s on front of extender.

2. Do I have the right serial cable? Straight, Cross, 3 –wire, with some control signals pulled up or down or looped back … Check manufacturers specification!

3. Is the baud rate correct? Apart from 9600 there is hardly any standard in baud rate: check module instructions and manufacturers specifications. The other serial port settings (1 stop bits, no parity and 8 bits) are pretty much standard, i.e.



need no changes. If Hardware Flow Control is used on your equipment, there is often an setting to work without it. Please note that many components have configurable baud rate, the ProntoScript module is typically set up for the default value!

4. IP connection: Can you “ping” the Pronto, the extender and the component from a PC on the same network? This can be a huge time saver. StartàRun... Type cmd and press ok. In the console type ping followed by the IP address of Pronto, Extender or A/V component.

If you get a reply, you can access the device via the IP network. In case of a connectivity issue, you get a “Request timed out.”

4.1. Setting Parameters on the [PARAMETERS] page hands-on This is an example of a [PARMETERS] page. All the parameters that the module makers want to expose to the custom installer for configuration are clearly indicated with a yellow background. All other elements of a 2-way module should in principle be treated as “read-only”1: you will not need to change any of those to achieve a successful 2-way integration.

1 In our custom installer oriented philosophy we have opted not to make the module read-only in the literal sense. If for a reason we cannot foresee you should need to make changes to the module, we don’t want to prevent you from doing so.



5. ProntoScript Module UI Customization The customization of a ProntoScript differs typically from what you’re used to with normal Pronto Pages. With normal pages the UI is not dependant on any programming logic, i.e. the button actions. You can freely change button locations, delete buttons, or change their appearance. With ProntoScript modules, this is not always the case! (Parts of) the UI of two-way modules are dynamic:

• Button and Label texts are updated with two-way system information (track title, lighting scene…) • Buttons can be hidden and unhidden when needed • Buttons can change appearance dynamically (taking bitmaps from the [RESOURCES] page) • Buttons can be moved on the page • …

It’s easy to understand that one can easily break the programming logic of such a dynamic UI when deleting, copy-pasting or modifying such buttons and panels. We suggest the following approach:

1. Use the module as is. The two-way modules are made professionally in a color scheme that typically matches the Pronto or equipment manufacturer’s style. They blend in well with typical projects. Using as is guarantees a UI operation as anticipated by the ProntoScript Partner or module maker.

2. If you really want to customize a module: consider changing the Background image. This is typically a full screen panel at the bottom of the page. Check under propertiesàadvanced. If the ProntoScript Name is empty, it is not used in the script and can safely be adapted

3. Read the [INSTRUCTIONS] for instructions by the ProntoScript Partner or module maker on UI customizations or skinning options offered

4. Contact the ProntoScript Partner or module maker in case of questions related to a specific module

Please note: Philips strongly discourages you to make changes to the ProntoScript code yourself without the proper qualifications and training. Small changes to the code can have serious consequences to the perceived reliability of the Control System you’re building: the Pronto can e.g. appear to be frozen because you introduced an endless loop into the code. Information on training and certification can be obtained from www.pronto.philips.com/professionalarea



6. Conclusion With ProntoScript, Philips has added powerful two-way control to the Pronto line. It allows, you, the custom installers to make your custom install jobs more user friendly and reliable. Keeping your productivity in mind we have packaged the power of ProntoScript in easy to use modules that can be plugged into a new or existing job with ease. We ask you to keep an eye on the Pronto website for new and updated modules and wish you success with Pronto and ProntoScript! ProntoTeam

prontoscript_installers_guide(1).pdf

Documents

prontoscript developers

prontoscript tutorial

home page

welcome page

parameters page handson

readymade twoway modules

twoway challenge

page jumps theres