HDHomeRun Plugin: Teaching the House What the TV Is Doing

HDHomeRun: Teaching the House What the TV Is Doing

Available now in the HomeSeer plugin store.

This one started with a piece of hardware I already liked quite a bit.

An HDHomeRun is, at heart, a collection of television tuners sitting on the network with remarkably little opinion about who uses them.

That is part of what makes them such good hardware.

It is also what makes them mildly frustrating from an automation standpoint.

The HDHomeRun knows perfectly well that tuner 2 is locked onto a channel and streaming something.

The house, meanwhile, knows nothing.

Someone may be watching television.

Something may be recording.

A media server may have grabbed a tuner.

Or some application may simply be sitting there quietly holding one hostage.

HomeSeer has no idea.

I wanted it to know.

Fortunately, the HDHomeRun itself is remarkably willing to talk.

Possibly the simplest protocol in the house

For the basic information I wanted, there is no pairing ceremony.

No account.

No cloud dependency.

No OAuth dance.

The device exposes straightforward local interfaces that tell you what the box is, what channels it knows about, and what each tuner is doing.

That is genuinely enough to turn:

“Is anyone watching television?”

into something HomeSeer can actually answer.

And from there, automation becomes obvious.

Maybe do not reboot the media server while someone is watching something.

Maybe do not shut down AV equipment.

Maybe change lighting based on viewing activity.

Or simply expose what each tuner is doing somewhere else in the house.

The interesting part is that the HDHomeRun already knows all of this.

The plugin just introduces it to HomeSeer.

One thing I deliberately do not use

HDHomeRun discovery can also expose a per-device value called DeviceAuth, used by SiliconDust's own cloud-facing services.

The plugin does not need that value for ordinary local tuner monitoring and control.

So it leaves it alone.

It is not stored.

It is not logged.

It does not become part of the plugin's normal state.

That is intentional.

One of the simplest security rules I know is also one of the most effective:

Credentials you do not handle are credentials you cannot leak.

If the plugin does not need a secret, there is no reason for that secret to become the plugin's responsibility.

Asking rather than guessing

This is probably my favorite part of this one.

The readily available device information gives you things such as the model and tuner count.

What I did not want to do was build capability detection around the model name.

I have several HDHomeRuns here.

Two can transcode.

Two cannot.

The easy answer would have been:

If the model name contains HDTC, it transcodes.

And that would work.

For the models sitting here.

Today.

But that is really just a guess about SiliconDust's naming convention.

The moment they release something with different capabilities and a different model scheme, the plugin becomes wrong despite the device itself knowing perfectly well what it can do.

So instead of asking:

“What are you called?”

and inferring capabilities from that, the plugin asks:

“What can you do?”

HDHomeRun's own control protocol exposes:

/sys/features

On the hardware I tested, the transcoding model reports capabilities including a transcode line, while the non-transcoding models do not.

The plugin does not need to know what an EXTEND is.

It just needs to know whether the device says it can transcode.

That is a much better contract.

A future box can describe itself using the same capability vocabulary, and code written before that box existed may still understand it.

There is a general rule hiding in there that applies far beyond television tuners:

Ask the device what it can do instead of inferring it from what somebody named it.

Model-string matching looks inexpensive.

It is really a maintenance burden with very good initial marketing.

The guide

Once tuner status was working, guide information was an obvious next step.

HDHomeRun itself provides enough guide information for ordinary viewing, and current SiliconDust service levels include basic guide data without requiring a paid DVR subscription.

For many households, that is entirely sufficient.

But when I compared it with what I wanted from HomeSeer, some limitations became noticeable, especially around minor broadcast subchannels.

Some had incomplete listings.

And the metadata was not always as rich as I wanted for things such as episode information, original air dates, and series relationships.

That led me to experiment with Schedules Direct.

Technically, it is an interesting integration.

Legally, it needs an asterisk.

A fairly large one.

Schedules Direct is not just “bring your own account”

Schedules Direct provides much richer guide data, and the API itself is reasonably straightforward once you understand its shape.

Authentication produces a token.

Then come the account's lineups.

Then the station map.

Then schedules by station.

Then the program records referenced by those schedules.

That last separation is important.

A schedule does not contain a complete copy of every program.

It contains program identifiers.

The same program may appear on several stations, at several times, so schedule data and program metadata are deliberately separate.

From a programming standpoint, that is sensible.

It is also why this path is several hundred lines rather than one convenient URL.

But there is something more important than the implementation:

Schedules Direct licenses its data for personal, noncommercial use through approved software.

That does not mean:

“It is my subscription, so anything I do with it inside my house is automatically permitted.”

Their current rules are more specific than that.

Software using the service has to be approved.

And some applications, including Plex and Emby, are explicitly excluded even when data reaches them indirectly through XMLTV.

So this is one place where technical possibility and permission are two different questions.

I had originally treated the feature as a simple household-use case.

After going back through the current licensing terms, I do not think that is a safe assumption.

The right answer is to get explicit approval for the HomeSeer integration rather than inventing my own interpretation of somebody else's license.

That is less exciting than another clever API trick.

It is also the correct thing to do.

Publishing guide data sounded better before reading the fine print

One of the original ideas was to let the plugin publish guide data it had already fetched as XMLTV and JSON for other local software to consume.

From a systems-design point of view, I still like the idea.

Fetch something once.

Cache it.

Let several local consumers use the result instead of every application independently authenticating and downloading the same information.

That reduces duplicate traffic and avoids several applications all deciding they need to log into the same service on their own schedules.

Architecturally:

One fetcher, several consumers.

Very tidy.

Unfortunately, licensing gets a vote.

Schedules Direct specifically restricts redistribution and use by unapproved applications.

So the fact that the files never leave the house does not automatically make redistribution to another application permissible.

And that means this feature cannot simply be described as:

“Use your Schedules Direct account once and feed everything else.”

Not without Schedules Direct agreeing that this particular use is allowed.

That is an important correction.

Sometimes writing the documentation finds a bug in the code.

Sometimes it finds a bug in your assumptions.

Both count.

The local side remains the part I like most

Fortunately, none of that changes the core of the plugin.

The HDHomeRun itself remains a wonderfully straightforward local device.

It can tell HomeSeer:

Which tuners exist.

Which ones are currently active.

What they are tuned to.

What channels the device knows about.

What capabilities the hardware actually reports.

And all of that can happen directly on the local network.

No cloud account is required simply for the house to know whether someone is using a tuner.

What I like about this one

The plugin is not trying to replace television software.

It is not a DVR.

It is not another media ecosystem.

It takes state that already exists inside the HDHomeRun and makes that state useful elsewhere.

Which tuner is busy?

What is it doing?

Is something being watched?

Is something recording?

What channels are available?

What does this particular piece of hardware actually support?

Those are simple questions.

But once HomeSeer can answer them, the television system stops being an isolated island and becomes another participant in the house.

And the capability detection contains the part I like most:

Do not keep a catalogue of everything a manufacturer has ever sold if the equipment can describe itself.

Ask the box.

It is usually a more reliable witness than the model number printed on it.