DirecTV (SHEF)

Control a DirecTV satellite receiver over the LAN using DirecTV's SHEF (Set‑top HTTP Exported Functionality) remote API — the same HTTP service the DirecTV mobile app uses. One receiver becomes one GEM device, commands target the device directly, and the driver creates no zones. There is no account and no pairing: with SHEF turned on at the receiver, GEM just needs the box's IP address and port 8080.

This is the classic "shared satellite box feeding a matrix" source — add the receiver as an AV source and users get an on‑screen DirecTV remote with a channel browser, a D‑pad, and DVR transport on any touchpanel.

How it connects

• The connection is plain HTTP to the receiver's IP on TCP port 8080 (the SHEF port).
• There is no authentication — any device on the LAN that can reach port 8080 can control the receiver. Keep receivers on a trusted/management VLAN if that matters on the job.
• Every Status Poll Interval (default 30 s) GEM asks the receiver what it's tuned to and records the program title and call sign on the device. That is what drives the now‑playing line on the source panel.

What's controlled

• Navigation — full D‑pad (up / down / left / right / select), plus Menu, Info, List (recordings), Back, and Exit.
• DVR transport — play, pause, rewind, fast‑forward, record, stop, and the instant‑replay (jump back) / advance (jump forward) keys.
• Tuning — tap a channel in the on‑screen channel browser, or send a channel number with the set_channel command. DirecTV tunes by major channel number only.
• Color keys — the red / green / blue / yellow on‑screen overlay buttons.
• Any other remote key — power, Guide, channel up/down, previous channel, the number pad, and the rest of the handset are reachable through the catch‑all remote_key command (see Commands).

This driver exposes no dedicated power, volume, or mute commands — see Power, volume, and standby.

Prerequisites

• A DirecTV receiver on the same LAN as GEM, reachable by IP (no NAT between them).
• External Access / the SHEF API enabled on the receiver. On most receivers this is under Settings → Whole‑Home → External Device (some firmware lists it under Settings → Network Setup → External Device). It must be set to Allow before GEM can control the box.
• Give the receiver a static IP or a DHCP reservation so its address never moves — the device row is pinned to one IP, and a moved address means GEM can no longer reach it.

Genie minis are separate devices

A Genie whole‑home system has one main server plus several Genie mini clients. Each tuner is reachable on its own IP, so create one GEM device per receiver/mini you want to control — there is no single device that fans out to every room.

Setup

Open Devices

1. Enable External Access / SHEF on the receiver (see Prerequisites) and note its IP.
2. Go to System → Devices → Add Device and choose the DirecTV (SHEF) driver. The driver suggests the AV subsystem — keep that.
3. Set Receiver IP Address to the box's LAN IP. Leave SHEF Port at 8080 unless you have changed it on the receiver — the driver also forces port 8080 on connect.
4. Save and enable the device. Within a few seconds GEM connects and begins polling the tuned channel.

Using DirecTV as an AV source

To put the receiver on a touchpanel as a selectable source with an on‑screen remote, create an AV source for it:

Open AV Sources

1. In AV Sources, click Add and set:
   • Device — this DirecTV device.
   • AV Type — Video.
   • Label — what users see (e.g. "DirecTV" or "Satellite").
   • Component — directv. (directv_dvr renders the same panel — either value works.)
   • Channel Provider — the channel lineup to show in the browser (see Channels and tuning).
2. Choose whether it's a Global source (selectable in every zone — typical for a shared receiver feeding a matrix) or pin it to one AV Zone.
3. Save. When a user selects that source in a room, GEM draws the DirecTV panel: a channel browser on the left and an on‑screen remote on the right.

The on‑screen panel has a channel browser (with a search field and a Fav / All toggle) plus three remote pages you cycle with the More button:

• Navigation — the D‑pad and select, Guide, Exit, the REC / List / Info / Back row, and the color keys.
• DVR — play / pause / exit, rewind / fast‑forward / back, REC / Stop / List, and skip buttons.
• Advanced — the number pad (0–9, dash, Enter, Menu) and channel up / down.

Tune from the channel browser

In the current build the number pad, CH ▲ / CH ▼, Prev Chan, Guide, and the Back 10s / Forward 30s skip buttons on the panel are not wired to SHEF commands — they do nothing on their own. Tune with the channel browser instead (it sends a real tune), and for Guide, channel up/down, previous channel, power, or a raw digit, put a remote_key command on a UI button or in a macro with the matching key (see Commands). The D‑pad, select/enter, transport, record, info, list, exit, back, menu, dash, and the color keys all work directly.

Channels and tuning

DirecTV has a native channel command, so tapping a channel in the browser tunes it directly — no per‑digit emulation. The number you tune is the major channel number only: 206 (ESPN), 501 (HBO). SHEF cannot address sub‑channels such as 101‑1 or 4‑2.

To populate the channel browser, build a Channel Provider lineup and bind the source to it with the Channel Provider field above:

1. Open Channels and create a provider (for example satellite_directv).
2. Add channels by hand (number, name, call sign, logo, favorite/enabled), or set the provider's External provider ID and use Sync to pull the lineup from the online listings service.
3. The browser shows that provider's enabled channels in sort order; if any channel is favorited it collapses to a favorites‑only view.

See Channels for the full lineup workflow, favorites, logos, and syncing.

Power, volume, and standby

• No dedicated power command. To power the box, send the remote_key command with key set to poweron or poweroff (or power to toggle). Put it on a UI button, in the source's On Macro / Off Macro, or in any macro.
• No volume or mute. A DirecTV receiver is a source feeding a matrix, switcher, or AV receiver — control room volume on that AV gear (the AV zone), not on the satellite box.

Status polling

GEM polls the receiver's tuned channel on a timer and records it on the device:

• The poll runs the get_status command (DirecTV's getTuned) every Status Poll Interval (status_interval, default 30000 ms) and writes the receiver's reply to the status attribute as JSON. The source panel reads the program title and call sign from it for the now‑playing line.
• If status polls interfere with playback on a Genie client, set disable_status to true to stop the periodic poll. You can still run get_status on demand.
• DirecTV responds aggressively to polling: back‑to‑back commands within ~250 ms can return an occasional 503. GEM paces its own poll; if you script rapid command bursts, add a short delay between them.

Attributes

Set these in System → Devices on the device's Attributes tab (see Devices → Attributes).

Device — required

Attribute	Type	Description
ip	string	The receiver's LAN IP address (Receiver IP Address).

Device — optional

Attribute	Type	Default	Description
port	int	8080	SHEF Port. The driver forces 8080 on connect — SHEF only listens there — so this is informational.
disable_status	bool	false	Disable Status Polling — turn off the periodic getTuned poll if it interferes with a Genie client.
status_interval	int	30000	How often (ms) GEM polls the tuned channel. Advanced — not shown in the add‑device form; add it by hand to change the cadence.

GEM also writes a read‑only status attribute (JSON) holding the receiver's last getTuned reply — the tuned program's title, call sign, and channel. You do not set it by hand; it updates on its own and is useful as a trigger condition.

Commands

Driver‑declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. See Commands for running and scripting them.

Navigation and menu

Command	Action
up down left right select	D‑pad navigation and select (enter is also accepted).
back	Back / return.
exit	Exit the current menu/overlay.
menu	Open the menu.
info	Info / banner.
list	Open the recordings (My Playlist) list.
dash	The ‑ key (for hyphenated entry).

DVR transport

Command	Action
play pause	Play / pause.
rewind fast_forward	Rewind / fast‑forward (aliases scan_back / scan_forward).
record stop	Start recording / stop.
replay	Instant replay — jump back (alias instant_replay).
advance	Advance — jump forward.

Color keys

Command	Action
red green blue yellow	The on‑screen color overlay buttons.

Tuning

Command	Action
set_channel (arg channel)	Tune to a major channel number, e.g. {channel: 206} (alias channel). Sub‑channels are not addressable.

Any other remote key

Command	Action
remote_key (arg key)	Send any SHEF remote key by name. Use this for keys without a dedicated command above — poweron, poweroff, power, guide, chanup, chandown, prev (previous channel), the digits 0–9, format, and active.

Status

Command	Action
get_status	Read the currently tuned program (DirecTV getTuned). Runs automatically on the poll interval; you can also run it on demand.

Known limitations

• Major channels only. SHEF tunes by major number; sub‑channels (101‑1, 4‑2) cannot be selected.
• No power / volume / mute commands. Power the box with remote_key (poweron / poweroff); control room volume on the AV receiver or matrix, not on the satellite box.
• One device per tuner. A Genie main server and each Genie mini are separate IPs and separate GEM devices — there is no single device that controls every room.
• Aggressive polling pushback. Rapid back‑to‑back commands can draw an occasional 503; pace bursts and leave status polling at its default cadence.
• Some panel buttons are unwired. The number pad, CH ▲/▼, Prev Chan, Guide, and the 10s/30s skip buttons on the on‑screen panel are not backed by SHEF commands in the current build — tune from the channel browser and use remote_key for those keys (see the note under Using DirecTV as an AV source).

Troubleshooting

Symptom	Check
get_status returns 403 / 503, or the device won't connect	External Access / the SHEF API is disabled, or the receiver is in standby. Enable it under Settings → Whole‑Home → External Device (or Settings → Network Setup → External Device) and confirm the box is on.
Status polls cause buffering on the receiver	Set disable_status to true to stop the periodic getTuned poll.
Channels don't tune	Confirm you're sending the major number (no sub‑channel suffix) and that the source's Channel Provider lineup uses major numbers.
Channel browser is empty	The AV source has no Channel Provider set, or the provider has no enabled channels — see Channels.
Power button does nothing	There is no power command; send remote_key with key = poweron / poweroff.
Commands stop after an IP change	The receiver's address moved. Pin it with a DHCP reservation and update the Receiver IP Address.

See also

• AV Sources — add the receiver as a selectable source and pick the directv panel.
• Channels — build the channel lineup the browser shows.
• AV Zones — how sources are selected and routed in rooms.
• Commands — running and scripting device commands.
• Devices — adding and configuring devices.