Narwhals Playing Mahjong

    directv-remote

    0.0.3 • Public • Published

    directv-remote

    Node.js module for manipulating DirecTV STBs (Set Top Boxes) over their REST API

    Setup

    Install from npm:

    npm install directv-remote
    

    For full functionality make sure to enable external device access on your cable box:

    Menu > Settings > Whole-Home > External Device > Allow
    

    Usage Notes

    See the API spec below for actual usage examples.

    Instantiate a Remote class using the IP address of a valid STB, then call any of the Remote's functions to actually talk to the box.

    Functions can be called with or without callback functions. If you choose to forego a callback function, it's output will be logged to the console instead of returned.

    If you choose not to pass in an optional parameter but are still using the callback function, you'll need to pass undefined in place of the missing param. I plan to refactor to remove this annoyance, but as of now it's not a priority.

    There is a Mocha test suite in the test.js file, that consists of a number of integration tests. These tests require a Whole-Home DVR setup (Genie STBs) and actually send commands to the boxes while expecting real responses. This is also a good example of this library's functionality.

    API

    DirecTV.validateIP(ipAddr, callback)

    Verify that an IP address is in fact that of a valid DirecTV Set Top Box.

    The parameter ipAddr is required and expected to be a string.

    No arguments other than a possible exception are given to the completion callback.

    Example:

    var DirecTV = require('directv-remote');
    var ipAddr = '192.168.1.103';
    
    DirecTV.validateIP(ipAddr, function(err) {
        if (err) return console.log(err);
        console.log(ipAddr, 'is a valid STB');
    });
    
    // returns '192.168.1.103 is a valid STB'
    

    DirecTV.Remote(ipAddr)

    Instantiates a DirecTV Remote object. The resulting object will be referred to as Remote from here forward.

    The parameter ipAddr is required and expected to be a string.

    Example:

    // Create a new Remote
    var Remote = new DirecTV.Remote(ipAddr);
    

    Remote.getOptions([callback])

    Lists the available endpoints on the system.

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getOptions(function(err,response) {
        if (err) return console.log(err);
        console.log(response);
    });
    
    // has the same effect as
    
    Remote.getOptions();
    
    // for compactness, callback functions will not be shown in the rest of the examples
    

    Remote.getLocations([type], [callback])

    Returns an array of the networked Set Top Boxes.

    The parameter type is an optional parameter. The documentation labels it as an int and during my testing the only values that don't return Forbidden are 0 and 1. With Whole-Home DVR (Genie STBs) enabled in my house, passing 1 shows currently offline STBs.

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getLocations(1);
    

    Remote.getSerialNum([clientAddr], [callback])

    Returns the serial number of the Set Top Box.

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getSerialNum('88F7C7DA0264');
    

    Remote.getVersion([callback])

    Returns Set Top Box version information as well as a systemTime property, which is the current epoch timestamp.

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getVersion();
    

    Remote.getMode([clientAddr], [callback])

    Returns the mode that the Set Top Box is currently operating in. It seems this returned mode property reflects the status active (0) or inactive (1), though this isn't documented behavior.

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getMode('88f7c7da1456');
    

    Remote.processKey(key, [clientAddr], [callback])

    Send standard remote control key presses to the STB.

    The parameter key is a required string value, that corresponds to buttons on the remote, such as:
    format, power, rew, pause, play, stop, ffwd, replay, advance, record, guide, active, list, exit, up, down, select, left, right, back, menu, info, red, green, yellow, blue, chanup, chandown, prev, 1, 2, 3, 4, 5, 6, 7, 8, 9, dash, 0, enter

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.processKey('guide', '88F7C7DA0264');
    

    Remote.processCommand(cmd, [callback])

    Send command request to the STB.

    The parameter cmd is a required hex value, such as:

    Command Definition
    FA81 Standby
    FA82 Active
    FA83 GetPrimaryStatus
    FA84 GetCommandVersion
    FA87 GetCurrentChannel
    FA90 GetSignalQuality
    FA91 GetCurrentTime
    FA92 GetUserCommand
    FA93 EnableUserEntry
    FA94 DisableUserEntry
    FA95 GetReturnValue
    FA96 Reboot
    FAA5 SendUserCommand
    FAA6 OpenUserChannel
    FA9A GetTuner
    FA8A GetPrimaryStatusMT
    FA8B GetCurrentChannelMT
    FA9D GetSignalQualityMT
    FA9F OpenUserChannelMT

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.processCommand('FA91')
    

    Remote.getProgInfo(channel, [startTime], [clientAddr], [callback])

    Returns program information for the specified channel, time and STB.

    The parameter channel is required and is an int.

    The optional parameter startTime is an epoch timestamp int, the default if not provided is now.

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getProgInfo(300, 1416999600)
    
    // returns info about the program airing on channel 300 at 1416999600
    

    Remote.getTuned([clientAddr], [callback])

    Returns information about the program currently being viewed.

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.getTuned()
    

    Remote.tune(channel, [clientAddr], [callback])

    Tunes the STB to a specific channel.

    The parameter channel is required and is an int.

    The parameter clientAddr is an optional string used to specify a separate networked STB. This is the same clientAddr referenced in the response from getLocations().

    The optional callback function accepts two parameters, an error and the response. If the optional callback parameter is not provided, then the response or error are simply printed to the console upon completion.

    Example:

    Remote.tune(299, '88F7C7DA0264')
    

    Credit

    This code is loosely based on the research done by Jeremy Whitlock for his directv-remote-api project. It has been rewritten from the ground up to work on Node.js, without the jQuery and Underscore.js deps.

    To-Do List

    • implement key holds
    • write better API examples that show manipulation of returned data
    • refactor to combine the multiple parameters of each function into an options object

    Keywords

    none

    Install

    npm i directv-remote

    DownloadsWeekly Downloads

    9

    Version

    0.0.3

    License

    BSD

    Last publish

    Collaborators

    • raptastics