sky-gnome

node-sky-gnome

Visit my Blog to get in touch or to see demos of this and much more.

Overview

This is a node module which connects, reads and interprets the Sky Gnome protocol. You find the module listed in the official node package manager repo:

www.npmjs.com/package/sky-gnome

Every retail Sky set-top-box pumps out a bunch of information about it's current state over a serial interface. If you pull the box out and look at the back panel, you will see an RS-232 interface port. Now, unless you bought your computer in the last century, you won't have a native RS-232 port, but luckily you can buy an RS-232-to-USB cable for around the same cost as a cup of coffee.

Plug one end into the set-top-box, the other into your computer (after you install the drivers that come with the cable), run this code and - hey presto - you will get lots of dynamic, contextual, JSON about the current channel, programme and set top box state.

Why does the box make this information available? Well it all stems back to a connected speaker they used to sell called Sky Gnome. Alas, these speakers are no more, but the Gnome protocol is still there and even the new boxes are still sending lots of useful data over the serial interface.

I am unclear if this works only on Sky UK boxes. I suspect it will work across all the Sky European boxes at least, but have no evidence either way. If you know, then please do get in touch and share this information.

My thanks to Joseph Heenan over at Dusky Control for documenting the Gnome protocol.

NOTE: When you buy the cable, make sure you get one without the two female ended nuts either side of the pins (or at least with removable nuts). There are nuts like these around the port on the box itself - so, if the cable has them too, it ain't gonna fit.

License

This plugin is available under the MIT license. Please respect the terms of the license.

Karmaware

This software is released with the karmaware tag

Disclaimer

I've done best efforts testing on my own set top box. If you find any problems, do let me know by raising an issue here. Better still, create a fix for the problem too and drop in the changes; that way everyone can benefit from it.

Installation

This project assumes you are familiar with the whole nodejs thing.

npm install sky-gnome

Dependencies

This plug relies on the serialport node module - but this is all taken care of for you by the node package manager. You just need to install this sky-gnome module.

Example Usage

Here is a simple example of using this node module:

console.log ();
console.log ('-'.repeat (80));
console.log ('node sky-gnome example code - press RETURN to exit')
 
var stop = false;
 
process.openStdin ().on ('data', function ()
{
    stop = true;
    this.pause ();
});
 
const SkyGnome = require ('sky-gnome');
 
var stb = new SkyGnome ('/dev/cu.usbserial');  // the path to your serail interface
 
stb.listen (function (error, data)
{
    console.log ('-'.repeat (80));
 
    if (error)
    {
        console.log (error);
    }
    else
    {
        console.log (data);
    }
 
    return stop;  // or dont have a return at all to carry on forever
});

When you try this for yourself, you need to know the path to your serial-to-USB interface. On my Mac, this is 'dev/cu.usbserial' - but on your computer this may be in a different place. The documentation that came with your cable should detail it's exact location.

Output Data

Here is a breakdown of all the data that you can expect to receive from the set top box. NOTE: You will not get all this data, all the time. It arrives in logical bunches depending upon the triggering action which occurred on the box. Play with it for a while and you will see how it all works.

Key	Type	Description
received	date	When the message was received from the set top box
channel.*		Information about the current channel
channel.number	int	Three digit channel number
channel.name	string	Channel name as per in the EPG
program.*		Information about the current programme
program.title	string	Name of the current programme
program.synopsis	string	Description of the current programme
program.season	int	Season number
program.episodes	int	Episode number
program.episode	int	Total number of episodes
program.duration	int	Programme duration in minutes
program.year	int	Year of production
program.warnings	array of string	Content warnings (see below)
showing.*		Information about the current programme showing
showing.started	date	When the current programme began
showing.attributes	array of string	Content attributes (see below)
epg.*		The raw as received data from the Gnome protocol
epg.channel	string	Channel number - the raw as received data
epg.started	string	Programme start time - the raw as received data
epg.title	string	Programme name - the raw as received data
epg.description	string	Programme description - the raw as received data
system.*		Information about the current state of the set top box
system.message	string	A user message from the set top box
system.trickplay	string	Sky+ actions like rewind, pause, playback, et al
system.pin	boolean	T = pin required, F = pin not required
system.power	boolean	T = powered on, F = powered off
system.interactive	boolean	T = entered interactive, F = left interactive
system.other	array of string	As yet unmapped actions (none expected)

Here is the full list of items you may see in the showing.attributes property:

• audio description
• copy protected
• dolby stereo
• high definition
• subtitles
• sign language
• ultra high definition
• widescreen

Here is the full list of items you may see in the program.warnings property:

• strong language
• flashing images
• violent scenes
• sex or nudity
• mature themes
• mono sound only

Extended Metadata

You may notice that the data coming back from this node module, goes beyond that which the Gnome protocol makes available by itself. That is because this module extracts additional information from within the body of the synopsis. Sky has a habit of packing stuff in there. For example:

A ragtag group of rebels embark on a daring, against-all-odds mission to thwart the planet-destroying plans of the Empire. Thrilling fantasy adventure with Felicity Jones. (2016)(128 mins)

As you can see here, we have the year of production and the running time within the synopsis text. This node module pulls stuff like this out via some regex magic and makes it available directly. It also, removes them from the synopsis to give a cleaner content descriptor. It does some other useful stuff too, like rejoining long titles that have been split into the synopsis with trailing ellipses.

Despite all this goodness, if you just want the original data as received via the Gnome protocol, then that is present too within the 'epg' portion of the JSON document.

Finally, here is an example of the JSON documents you can expect:

{
    received: '2018-02-04T23:14:04.591Z',
    channel:
    {
        number: 311,
        name: 'Sky ScFi/HorHD'
    },
    program:
    {
        title: 'Rogue One: A Star Wars Story',
        synopsis: 'A ragtag group of rebels embark on a daring, against-all-odds mission to thwart the planet-destroying plans of the Empire. Thrilling fantasy adventure with Felicity Jones.',
        season: null,
        episodes: null,
        episode: null,
        duration: 128,
        year: 2016,
        warnings: []
    },
    showing:
    {
        started: '2018-02-04T21:00:00.000Z',
        attributes: []
    },
    epg:
    {
        channel: '311',
        started: '9.00pm',
        title: 'Rogue One: A Star Wars Story',
        description: 'A ragtag group of rebels embark on a daring, against-all-odds mission to thwart the planet-destroying plans of the Empire. Thrilling fantasy adventure with Felicity Jones. (2016)(128 mins)'
    },
    system:
    {
        message: null,
        trickplay: null,
        pin: null,
        power: null,
        interactive: null,
        other: []
    }
}

– Pete Rai