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:
<br>*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](https://github.com/whitlockjc/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