{"id":20687173,"url":"https://github.com/pete-rai/node-sky-gnome","last_synced_at":"2025-04-22T15:07:57.603Z","repository":{"id":57362507,"uuid":"120221594","full_name":"pete-rai/node-sky-gnome","owner":"pete-rai","description":"A node module which connects, reads and inteprets the Sky Gnome protocol giving access to live TV metadata.","archived":false,"fork":false,"pushed_at":"2018-02-05T22:12:36.000Z","size":31,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T16:11:38.732Z","etag":null,"topics":["dvr","gnome","ird","metadata","pvr","rs232","serial","set-top-box","sky","skyhd","skyplus","skyq","stb","tv"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/sky-gnome","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pete-rai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-04T20:44:18.000Z","updated_at":"2022-09-28T22:22:03.000Z","dependencies_parsed_at":"2022-09-13T21:00:48.268Z","dependency_job_id":null,"html_url":"https://github.com/pete-rai/node-sky-gnome","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pete-rai%2Fnode-sky-gnome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pete-rai%2Fnode-sky-gnome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pete-rai%2Fnode-sky-gnome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pete-rai%2Fnode-sky-gnome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pete-rai","download_url":"https://codeload.github.com/pete-rai/node-sky-gnome/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250264910,"owners_count":21402003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dvr","gnome","ird","metadata","pvr","rs232","serial","set-top-box","sky","skyhd","skyplus","skyq","stb","tv"],"created_at":"2024-11-16T22:56:19.693Z","updated_at":"2025-04-22T15:07:57.584Z","avatar_url":"https://github.com/pete-rai.png","language":"JavaScript","readme":"# node-sky-gnome\n\n\u003e Visit my [Blog](http://www.rai.org.uk) to get in touch or to\nsee demos of this and much more.\n\n## Overview\n\nThis is a node module which connects, reads and interprets the Sky Gnome protocol.\nYou find the module listed in the official node package manager repo:\n\n\u003e [www.npmjs.com/package/sky-gnome](https://www.npmjs.com/package/sky-gnome)\n\nEvery retail Sky set-top-box pumps out a bunch of information about it's current\nstate over a serial interface. If you pull the box out and look at the back panel,\nyou will see an [RS-232](https://en.wikipedia.org/wiki/RS-232) interface port.\nNow, unless you bought your computer in the last century, you won't have a native\nRS-232 port, but luckily you can buy an [RS-232-to-USB cable](https://www.amazon.co.uk/s?field-keywords=rs232+to+usb)\nfor around the same cost as a cup of coffee.\n\nPlug one end into the set-top-box, the other into your computer (after you install\nthe drivers that come with the cable), run this code and - hey presto - you will\nget lots of dynamic, contextual, JSON about the current channel, programme and\nset top box state.\n\nWhy does the box make this information available? Well it all stems back to a\nconnected speaker they used to sell called [Sky Gnome](https://en.wikipedia.org/wiki/Sky_Gnome).\nAlas, these speakers are no more, but the Gnome protocol is still there and even the\nnew boxes are still sending lots of useful data over the serial interface.\n\n_I am unclear if this works only on Sky UK boxes. I suspect it will work across\nall the Sky European boxes at least, but have no evidence either way._ If you know,\nthen please do [get in touch](http://www.rai.org.uk) and share this information.\n\nMy thanks to Joseph Heenan over at [Dusky Control](https://www.dusky-control.com)\nfor [documenting the Gnome protocol](https://www.dusky-control.com/gnome-protocol.shtml).\n\n_NOTE: When you buy the cable, make sure you get one without the two female ended nuts\neither side of the pins (or at least with removable nuts). There are nuts like these\naround the port on the box itself - so, if the cable has them too, it ain't gonna fit._\n\n### License\n\nThis plugin is available under [the MIT license](https://github.com/pete-rai/node-sky-gnome/blob/master/LICENSE).\n_Please respect the terms of the license._\n\n### Karmaware\n\nThis software is released with the [karmaware](https://pete-rai.github.io/karmaware) tag\n\n### Disclaimer\n\nI've done best efforts testing on my own set top box. If you find any problems,\ndo let me know by raising an issue [here](https://github.com/pete-rai/node-sky-gnome/issues).\nBetter still, create a fix for the problem too and drop in the changes; that way\neveryone can benefit from it.\n\n### Installation\n\nThis project assumes you are familiar with the whole [nodejs](https://nodejs.org/en/) thing.\n\n```\nnpm install sky-gnome\n```\n\n### Dependencies\n\nThis plug relies on the [serialport node module](https://www.npmjs.com/package/serialport) - but\nthis is all taken care of for you by the node package manager. You just need to install this\nsky-gnome module.\n\n## Example Usage\n\nHere is a simple example of using this node module:\n\n```javascript\nconsole.log ();\nconsole.log ('-'.repeat (80));\nconsole.log ('node sky-gnome example code - press RETURN to exit')\n\nvar stop = false;\n\nprocess.openStdin ().on ('data', function ()\n{\n    stop = true;\n    this.pause ();\n});\n\nconst SkyGnome = require ('sky-gnome');\n\nvar stb = new SkyGnome ('/dev/cu.usbserial');  // the path to your serail interface\n\nstb.listen (function (error, data)\n{\n    console.log ('-'.repeat (80));\n\n    if (error)\n    {\n        console.log (error);\n    }\n    else\n    {\n        console.log (data);\n    }\n\n    return stop;  // or dont have a return at all to carry on forever\n});\n```\n\nWhen you try this for yourself, you need to know the path to your serial-to-USB interface.\nOn my Mac, this is '**dev/cu.usbserial**' - but on your computer this may be in a different\nplace. The documentation that came with your cable should detail it's exact location.\n\n### Output Data\n\nHere is a breakdown of all the data that you can expect to receive from the set\ntop box. _NOTE: You will not get all this data, all the time._ It arrives in logical\nbunches depending upon the triggering action which occurred on the box. Play with it\nfor a while and you will see how it all works.\n\n| Key | Type | Description |\n|:---|:---:|:---|\n| received | date | When the message was received from the set top box |\n| channel.* |   | Information about the current channel |\n| channel.number | int | Three digit channel number |\n| channel.name | string | Channel name as per in the EPG |\n| program.* |   | Information about the current programme |\n| program.title | string | Name of the current programme |\n| program.synopsis | string | Description of the current programme |\n| program.season | int | Season number |\n| program.episodes | int | Episode number |\n| program.episode | int | Total number of episodes |\n| program.duration | int | Programme duration in minutes |\n| program.year | int | Year of production |\n| program.warnings | array of string | Content warnings (see below) |\n| showing.* |    | Information about the current programme showing |\n| showing.started | date | When the current programme began |\n| showing.attributes | array of string | Content attributes (see below) |\n| epg.* |   | The raw as received data from the Gnome protocol |\n| epg.channel | string | Channel number - the raw as received data |\n| epg.started | string | Programme start time - the raw as received data |\n| epg.title | string | Programme name - the raw as received data |\n| epg.description | string | Programme description - the raw as received data |\n| system.* |    | Information about the current state of the set top box |\n| system.message | string | A user message from the set top box |\n| system.trickplay  | string | Sky+ actions like rewind, pause, playback, et al |\n| system.pin | boolean | T = pin required, F = pin not required |\n| system.power | boolean | T = powered on, F = powered off |\n| system.interactive | boolean | T = entered interactive, F = left interactive |\n| system.other | array of string | As yet unmapped actions (none expected) |\n\nHere is the full list of items you may see in the _showing.attributes_ property:\n\n* audio description\n* copy protected\n* dolby stereo\n* high definition\n* subtitles\n* sign language\n* ultra high definition\n* widescreen\n\nHere is the full list of items you may see in the _program.warnings_ property:\n\n* strong language\n* flashing images\n* violent scenes\n* sex or nudity\n* mature themes\n* mono sound only\n\n#### Extended Metadata\n\nYou may notice that the data coming back from this node module, goes beyond that\nwhich the Gnome protocol makes available by itself. That is because this module\nextracts additional information from within the body of the synopsis. Sky has a\nhabit of packing stuff in there. For example:\n\n\u003e 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_)\n\nAs you can see here, we have the _year of production_ and the _running time_ within\nthe synopsis text. This node module pulls stuff like this out via some regex magic\nand makes it available directly. It also, removes them from the synopsis to give\na cleaner content descriptor. It does some other useful stuff too, like rejoining\nlong titles that have been split into the synopsis with trailing ellipses.\n\nDespite all this goodness, if you just want the original data as received via the\nGnome protocol, then that is present too within the 'epg' portion of the JSON\ndocument.\n\nFinally, here is an example of the JSON documents you can expect:\n\n```javascript\n{\n    received: '2018-02-04T23:14:04.591Z',\n    channel:\n    {\n        number: 311,\n        name: 'Sky ScFi/HorHD'\n    },\n    program:\n    {\n        title: 'Rogue One: A Star Wars Story',\n        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.',\n        season: null,\n        episodes: null,\n        episode: null,\n        duration: 128,\n        year: 2016,\n        warnings: []\n    },\n    showing:\n    {\n        started: '2018-02-04T21:00:00.000Z',\n        attributes: []\n    },\n    epg:\n    {\n        channel: '311',\n        started: '9.00pm',\n        title: 'Rogue One: A Star Wars Story',\n        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)'\n    },\n    system:\n    {\n        message: null,\n        trickplay: null,\n        pin: null,\n        power: null,\n        interactive: null,\n        other: []\n    }\n}\n```\n\n_– [Pete Rai](http://www.rai.org.uk)_\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpete-rai%2Fnode-sky-gnome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpete-rai%2Fnode-sky-gnome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpete-rai%2Fnode-sky-gnome/lists"}