Freeview NZ Channel Launcher

Version 1.02

A favourites-driven channel launcher for IR-controlled Freeview NZ boxes. Provides a Web Object UI with categorised channel grid and per-instance favourites. Each driver instance controls one Freeview NZ box, so add the driver once per physical box.

Setup

1. Add IR commands

In Integration Designer, add the device profile for your Freeview NZ box, TV or receiver from RTI's device library. Control can be IR, IP, or RS232 - whatever transport your device supports. Drag the digit buttons (0-9) and the SELECT/OK button onto a workspace so they have device IDs. Create one macro per button - each macro should be a single command step that fires that one digit (IR / IP / RS232 / VHD - any RTI-supported transport). Eleven macros total: Digit 0 through Digit 9 plus SELECT.

If using IR control: receivers vary in IR carrier frequency (typically 36 or 38 kHz). Use the appropriate IR profile for the specific model. If using IP or RS232 control, this is not relevant - just confirm the device profile in RTI's library matches your hardware. If digits are being dropped, confirm the IR emitter is in line-of-sight of the Freeview NZ box and that the carrier frequency matches.

2. Configure the driver

- Box Index: unique number for this box (1-8). Each driver instance needs a different value.

- Box Name: friendly label shown in the Web UI (Lounge, Bedroom, etc.).

- Digit 0...9 macros, SELECT macro: pick the macros you created in step 1.

- Inter-Digit Delay: milliseconds between digit IR commands. Default 350ms works for most boxes. Increase to 500 if digits are dropped.

- Channel Scheme: Standard for the bundled Freeview NZ channel list. Custom for hosting your own channels.json (set the URL below).

- Channel Data URL: optional - leave blank to use the channel list bundled with the driver. Set to a URL of your own hosted channels.json if you want to push updates without re-installing.

- Web Server Port: 0 = auto (8090 + Box Index). Set explicitly only if you have a port conflict.

3. Set Visible Categories

In the Visible Categories config section, tick the channel categories this household actually watches. Hidden categories' channels do not appear anywhere in the UI, not even in the All tab.

- Show Favorites Tab - show the starred channels tab. Default on.

- Show All Tab - show the All Channels catch-all tab. Default on.

- Show Sport, Movies, News, Entertainment - default on.

- Show Lifestyle, Documentary, Kids, Music - default off. Turn on if the household uses these categories.

4. Choose a Theme

In the Appearance config section, pick a colour theme: Dark (default), Light, Charcoal, Accent Red, Navy, or Custom. The Custom theme uses the six hex code settings below the theme picker.

5. Add a Web Object to your interface

On the panel where you want the channel grid, add a Web Object and point its URL at the driver's web server. The URL appears in the driver's "Web URL" system variable after the driver loads:

http://<processor-ip>:8091/

Replace 8091 with whatever port the driver is using (Box Index 1 = 8091, Box Index 2 = 8092, etc.).

Layer / Pop-up Workflow

The driver exposes a boolean system variable called Show Freeview NZ Layer (sysvar ShowFreeviewNZLayer). Bind a panel layer's Visibility condition to this variable, then use the driver's Open/Close/Toggle Layer functions to control it from buttons or macros.

Recommended setup:

1. On the panel layer containing your Web Object, set the layer's Visibility Condition to Show Freeview NZ Layer == true.

2. Wire a button on the main page to call the driver function Open Layer (or Toggle Layer).

3. The Close button on the Web Object itself calls back to the driver and sets the variable to false, hiding the layer.

For panels where you prefer to test for false (Visibility Condition can only test for true on some panel types), the driver also exposes Show Freeview NZ Layer (Inverted) (sysvar HideFreeview NZLayer) which is the boolean negation.

The driver also fires LAYER_OPENED and LAYER_CLOSED events if you want to trigger other actions when the layer toggles.

Using It

Tap a channel tile to tune. The driver fires the digit macros in sequence (350ms apart by default), then SELECT 500ms after the last digit.

Tap the star on any tile to add or remove it from Favourites. Favourites for this box are persisted across processor reboots.

The Favourites tab is the default tab if you already have favourites. On a fresh install with no favourites, the grid opens to All Channels and shows a hint to tap a star.

Multiple Boxes - Favourite Sharing

Each driver instance keeps its own favourites list. Lounge and bedroom Freeview NZ boxes do not automatically share favourites in v1.00. If you want a shared house-wide list, contact support - v1.01 will add an optional external system variable picker that lets all instances read and write the same favourites string.

Triggering from Macros

The driver exposes these functions you can call from Integration Designer macros:

Channel Tuning

- Tune Channel (string) - tune to a channel number e.g. "503"

- Tune Channel (Integer) - same, for integer parameters

- Tune Favorite (integer 1-N) - tune to the Nth favourite

- Cancel Tune - stop an in-progress digit sequence

Favorites

- Add Favorite, Remove Favorite, Clear All Favorites

UI Layer

- Open Layer, Close Layer, Toggle Layer

Diagnostics

- Print Status - dump status to TraceView for diagnostics

- Reload Channel Data - refresh the channel list (use after changing Channel Scheme)

Commercial venues

The bundled commercial channel list is a sport-focused starter set. Commercial Freeview NZ packages vary substantially by venue type (pub, club, gym, hotel) and contract. Before deploying in a commercial venue, verify the channel numbers against the actual Commercial venues package, and either edit channels-commercial.json before packaging or set Channel Scheme to Custom and point Channel Data URL at your own hosted JSON.

Multiple Boxes

For each additional Freeview NZ box, add another instance of this driver and give it a unique Box Index. Each instance has its own digit-macro pickers (different IR codes if the boxes are in different rooms with different IR emitters), its own Web Object URL, and its own ShowFreeviewNZLayer variable.

Troubleshooting

Digits dropped - increase Inter-Digit Delay to 500ms. Confirm the IR emitter is in line-of-sight and rated for 36 kHz.

Web UI shows "Failed to load channels" - the processor cannot reach itself on the configured port. Use Print Status from a macro to confirm the driver bound to the port. If "Port in use" appears in Driver Status, change Web Server Port in config.

Web Object on the panel is blank - check the panel can reach the processor's IP on the configured port. The processor IP appears in the driver's Web URL system variable.

Channel numbers wrong - confirm Channel Scheme is set correctly (Residential vs Commercial). channel numbering changes occasionally - if the bundled list is stale, set Channel Scheme to Custom and host your own JSON.

Layer wont close - confirm the layer's Visibility Condition is bound to this driver instance's ShowFreeviewNZLayer variable, not another instance's. The Close button in the Web UI sets the variable on the instance whose web server is being viewed.

Support

david@smarthomeprogramming.com.au