Hubitat driver for DirecTV IP control of receivers
* Change History:
*
* Version Date Who What
* ---- ---- --- ----
* 1.0 2024-02-26 Roger Noia Initial Release
*
This driver uses the DirecTV SHEF API. As implemented, it only uses HTTP Gets, but the API permits other methods for the adventurous. This driver was created so I could use Hubitat to replace my now defunct Logitech Harmony remote and not use an IR-based remote. As I know nothing about Groovy but had a good knowledge of Perl and Javascript, I used this as an exercise to learn how to do what I needed. I then took the extra step to document to the best of my ability so other non-developers won't have to go through what I did. (*note: I was able to functionally replicate most of what this driver does using Rule Machine itself)
This driver permits local, direct control of a DirecTV receiver using DirecTV's own API that runs on the receiver itself for on-demand access to information on the receiver.The following functions are available:
- Check the operating mode of the receiver
- Change the operating mode of the receiver (on or standby)
- Check the currently playing channel and program
- Change the channel
- Send "remote" buttons: here is what DirecTV provdies for: "power", "poweron", "poweroff", "format", "pause", "rew", "replay", "stop", "advance", "ffwd", "record", "play", "guide", "active", "list", "exit", "back", "menu", "info", "up", "down", "left", "right", "select", "red", "green", "yellow", "blue", "chanup", "chandown", "prev", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "dash", "enter"
- Anything involving the playlist as the DirecTV API no longer permits this
- Getting the current state of the receiver requires polling the receiver so it's not possible to have real-time, event-based triggers of what happens on the receiver. Considering the rather sluggish performance of my DVR, spamming the DVR with requests to have up-to-the-second visiblity of what is playing isn't realistic or recommended. It would probably make the already slow-performing receiver unresponsive. Once a minute, sure that should be ok.
- If the receiver is "off" (meaning in standby) issuing some commands like getTuned throws a 500 server error on the DirecTV receiver itself.
- If the DirecTV receiver is shut off via remote or manual button press, this driver won't know about it until the getMode function checks.
- The DirecTV API responds with a "success" code upon receiving a command, but this doesn't mean it actually did what you asked - only that it received the command. For commands like "tuneTo", there is a noticeable 1-2 second delay between it saying "success" and the channel actually changing, so any further actions need to be paused before another command is done. Commands like "getTuned" have a very fast response - milliseconds or even instantaneous
- The DirecTV receiver must (obviously) be connected to your home network, but Internet access isn't required - everything runs locally on the receiver
- The DirecTV receiver must have a static/fixed IP address
- Not all program options, response data are currently utilized in this driver (such as program recorded times, duration). Refer to DirecTV SHEF IP control API to see what's available. https://blog.solidsignal.com/docs/DTV-MD-0359-DIRECTV_SHEF_Command_Set-V1.3.C.pdf
- There are a few API commands that have been deprecated by DirecTV - the legacy "playlist" and "play" commands that would be used to play a recording for example so it's unlikely they will come back
- The "getTuned" command used only shows what is _currently_ being watched (i.e. on the connected screen) so it is assumed that any useful commands (or any command involving a channel or what is being played) will not work against the headless Genie 2 Server (model HS17). I don't have this DVR, so don't know what happens
- The DirecTV receiver needs to have external device access enabled (see below)
- DirecTV may (does) charge for the "whole home dvr" service which this depends on - if you don't have whole home DVR service, it is unlikely your DVR will respond to your commands
- DirecTV Satellite HR-54 DVR
- C61 (R2 Genie Mini)
It's assumed to work with any other Genie Satellite receiver DVR that connects directly to a screen.
It is unknown if this would work with a DirecTV stream box as there is no DVR server. It should work with non-DVR, legacy regular receivers (with their own tuners)
To use this driver, the DirecTV DVR and clients need to have special permissions set in the configuration UI, per the API documentation.Once you have the device setup with the driver, specify the IP address on the device preferences page and you should be all set. Do an "initialize" and verify the state attributes update and show, at a minimum, the receiver is off. Turn the receiver on (press on) and then press "getTuned" to get the current program playing. The state attributes should update in real-time on the device page.
2.4 SHEF Opt In In order to use SHEF in your network, it must be enabled in the set-top box by navigating to the “External Device” settings screen (Menu->System Setup->Whole-Home->External Device) screen. Once on this screen select “Allow” for “External Access” as shown in Figure 2-2 (in the API doc). Also turn on the other options as desired.
This driver allows commands to be issued against it from rule machine's ability to target actuators and switches. Just issue the command shown on the device page (which are the functions defined in the driver) via: Run custom command > Actuator > Function name (getTuned)- with no parameters for the following commands: getTuned, getMode, getLocations, on, off, powerToggle, clearState
- The following commands require a seconary parameter be passed:
- tuneTo: Channel number. Optionally use a Major.Minor channel number (such as 229.1). The driver will catch your intent and send the correct channel to the receiver. In the receiver's guide, the channel number will appear as "229-1" just replace the dash with a period when using this driver
- sendKey: key (by name, from this:"power", "poweron", "poweroff", "format", "pause", "rew", "replay", "stop", "advance", "ffwd", "record", "play", "guide", "active", "list", "exit", "back", "menu", "info", "up", "down", "left", "right", "select", "red", "green", "yellow", "blue", "chanup", "chandown", "prev", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "dash", "enter" only the keys listed work). Note: newer DirecTV remotes don't have all the buttons anymore but the keys still work via API. For example, the BLUE button marks a recording as "keep"
- Create a virtual button device. Go to DEVICES - add device - virtual - virtual button. You can make as many buttons on your device as you want
- If you don't already have the built-in button controller app, install it by: Go to APPS - press the "add built in app" button at the top right.- Search for "button controller"
- Add a new button controller and link it to the new device you created in the first step
- Configure the button controller by selecting the button number and button state (pressed) and entering the commands you want the butotn to do - it works and looks just like Rule Machine
- To issue a remote button key you'll want to do: Run a custom command - Actuator - Pick your DirecTV device - sendKey, paramter=string, then in the input box enter the keyname you want (chanup) in this case. If you ever forget a key's name, you can see the complete list on the DirecTV device page under the dropdown for "sendKey" - here is the config to run the custom command.
here's what it should look like if you want to use the getTuned command
- Go to your dashboard configuration page - add the _button device_ to the dashboard
- Go to your dashboard and add a new button and link it to the _button device_ you just added -I have a problem with buttons not retaining configuration when freshly added, so just hit save
- Click your just-added button and configure it: confirm it's still assigned to the device you want, and enter the button number (that corresponds to the definiton in the button controller) and match it to the state in your controller (pushed, released, held, double tapped)
- Press the button and confirm it does what you expected
- As this driver simulates a switch, rule machine can trigger this device via simple Switch on/off commands which would then send the command to the receiver.
- Anything the driver sees/cares about is saved to state attributes for usage in dashboards via the obviously named attribute: Channel Callsign, Channel numnber, Program Title, Episode Title, Is the current program a recording, Recorded program scheduler priority
- Client names/locations, mac addresses are permanently saved to the state variable in the device page so the user can easily get access to the necessary mac address. Refresh the browser after issuing the "getLocations" functon. This will be used to issue commands to a specific receiver client
- The "initialize" function does: getMode (what is current state), clearState (attributues) and getLocations (get clients)
- The "refresh" function does: getMode, getTuned (what is currently being played), getLocations
- I recommend putting a button on your dashboard then telling a button controller to run "getTuned" for spontaneous/on-demand updating of what is playing. See my personal dashboard on the screens at the end
- The debugMode option in preferences is very chatty - every command will be displayed for troubleshooting purposes.
- The getMode command has an optional feature - fix the mode. If set to the default "nocheck" - it just tells you the mode. If you change the option or pass the specified parameter of "ShouldBeOn" of "ShouldBeOff" it will attempt to fix the receiver's mode i.e. - turn it on if it's off and vice versa
Hidden functionality
Device Page with the receiver off - notice the favorite remote buttons directly in the commands - optional within the code.
State variables showing the clients and receivers on your network - this persists. The number under the red is the receiver's MAC address and is needed to issue commands to that receiver
