Notes on setup of HDHomeRun, tvheadend, kodi live tv

HDHomeRun provides a source of tv in htsp format. They provide an app for windows/linux/mac which enables watching the tv stream directly, and changing channels. They also provide a Kodi Add-on which allows watching the streamed material directly from there. However, this is just watching, and doesn’t enable the guide, PVR etc.

To use the built in features in Kodi for “live tv”, you have to have another piece of software, which Kodi calls the “backend”. There are apparently different backends supporting different hardware, but one of the backends is called “tvheadend”, and it supports HDHomeRun, and is supported by Kodi.

The tvheadend software has to be installed. apt-cache search tvheadend shows:
tvheadend – Tvheadend
tvheadend-dbg – Debug symbols for Tvheadend
kodi-pvr-tvheadend-hts – Kodi PVR Addon TvHeadend Hts – PVR API:1.9.2
kodi-pvr-hts – TVHeadEnd PVR for Kodi
kodi-pvr-hts-dbg – debugging symbols for TVHeadEnd PVR for Kodi

The “kodi-pvr” bits are kodi add-ons that have to be added to kodi (in linux only) in order to provide the api between kodi and the backend. Kodi for mac and windows has the pvr bits included, but they have to be added in linux.After the apt install, add-ons->my add-ons->PVR clients,  select TVHeadend HTSP Client and configure it, then Activate it.

Since the kodi I watch is on coriander (the mac mini), the pvr stuff is already installed with kodi. I only needed to install the tvheadend piece somewhere, and I put it on cinnamon where the large file media array is, so that PVR recorded material can be stored there too.
I installed the tvheadend piece on cinnamon (ubuntu). It runs as a daemon, started out of init.d. It runs as its own user “hts” so there is a /home/hts. Inside /home/hts there is a directory .hts, inside the directory /home/hts. /home/hts contains two directories, one for tvheadend, and the other for the program guide stuff (more about this later). The tvheadend directory has the configuration and “database” for tvheadend.

Configuration of tvheadend is done with a web browser, on localhost:9981 (or 192.168.x.y:9981). If authorization is requested and you don’t have it, start the process in the foreground with the -C option which will allow browser access from anywhere by anybody. Once you are in with the browser, one of the settings is access stuff.

There are websites with info about initial setup. The trick I was missing originally was that once it is started, and tvheadend discovers the presence of the HDHomeRun boxes to provide source material, it won’t user them until you create what tvheadend calls a “network” (configuration->dvb inputs->network), and then go back and assign the tv adapters (configuration->dvb inputs->tv adapters) to the network. Then it will scan and populate the channels.

Once this is set up, Kodi can be set up to access it. This requires activating the pvr client (after installing it first if you are on linux). Then configuring it in system->settings->tv. It has to be given a userid/password, and the ip address and port number where to reach the tvheadend backend server (on cinnamon in my case). When that is all done, kodi can communicate with the backend, and it will enable the “TV” (some skins call it “Live TV”) entry in the Kodi main menu.

The EPG is harder. There are (I think) options to get some EPG stuff for free, but I chose to use the service, which costs $25/yr. I enrolled at their website, and then set up a “lineup” (i.e. I picked what geographical area I want a guide for, by zip code). Now tvheadend can be configured to get that data.

In tvheadend: configuration->Channel/EPG->EPG Grabber is where one sets that up. In the general config I recommend don’t set “update channel name” because that overwrites the tvheadend “name” field, which I’d like to modify occasionally. I have the other two checkboxes set on. In “Internal Grabber” I picked “XMLTV: North America (Data Direct)”. [See discussion later – I changed this to XMLTV: Combine data from several other grabbers to get it to acquire both Boulder and Denver channels]

This causes tvheadend to uses a program in /usr/bin called tv_grab_na_dd. I’m not sure when this got installed – it might have been installed with tvheadend. There are a bunch of these tv_grab things, and na is for north america, and dd is something like data direct and I use dd instead of the direct tv one.

tv_grab_na_dd is a perl script, and keeps its config info, and its “database” (an xml file) in ~/.xmltv. Since it is going to be run out of tvheadend, which is running under user hts, if you want to run tv_grab_na_dd directly, you have to su hts first, and run it as hts (otherwise the ~/.xmltv will be under the wrong user). The first thing it has to do is to build a config file, which means creating a ‘.conf’ file in /home/hts/.hts/.xmltv.
su hts
tv_grab_na_dd –configure

When I ran this it failed, Turns out it had a bad url inside it for where to get the channel data. At about line 728 of the script, it had a url
my $dd_service=’’;
and this was wrong. After looking around I discovered the service had moved, and replace this with:
my $dd_service=’’;
This was a big breakthrough.
Now the configure phase will run, and it will download some stuff.

The configure script asks a bunch of questions including info about your schedulesdirect login info, and the lineup, etc. I encountered problems with this, and ended up building some of the config file by hand. Once it was built sufficiently, I could run tv_grab_na_dd out of tvheadend. The parts of the config file I set up by hand were:
password: xxx
timeoffset: +0000
lineup: PC:80023
auto-config: add

With this much info, tv_grab_na_dd would run correctly out of tvheadend, and it would download the epg data into the file xmltv.xml within the directory /home/hts/.xmltv.

So to recap: /home/hts/.hts with single subdirectory tvheadend is the home location for tvheadend where it keeps all its stuff. and /home/hts/.xmltv is where the tv_grab_na_dd config file and the downloaded xmltv.xml file is located.

Now this wasn’t enough to actually get the EPG data into tvheadend, or into Kodi. The next step was to configure each channel for the EPG stuff. What is happening is to associate each channel – as seen by the tvheadend software, with the corresponding “channel” as the external guide service sees them.

In tvheadend at Configure->Channel/EPG->Channels, I had to visit each channel, and then double click on the EPG Source field. I would then get a drop-down with all the “channels” that are listed in the xml file. Probably these is some elegant thing I have missed that would automate all this, but I ended up going through these one by one, and for each channel I selected the EPG Source corresponding to that channel. The common piece of data that was my primary guide was the channel number, like 23.1 or 10.2, because that appears in both. Sometimes there were two channels (two services) in tvheadend which had the same number, and I had to figure out which was which.

Not every channel that I am getting in the HDHomeRun is in the XML file I got from the tv_grab_na_dd download. This (I think) has to do with the whole “lineup” business in schedulesdirect. You tell schedules direct that you want the lineup for zip code 80023, and it gives you a list of stations and programming in that area. But it turns out I am actually receiving some channels from Boulder that aren’t actually in that list. I then went back to schedules direct, and added another lineup, for Boulder.

But tv_grab_na_dd will only handle one lineup. You tell it in the config file what lineup you want (must be one you already registered with schedules direct as one of yours). It will download that lineup. If I switch to the Boulder one, it drops some stations. If I switch to the Broomfield one it drops some other stations. Whichever group I chose to give up, I am giving up the guide data for those channels. Of course I can still watch them, but I can’t see the guide data.

There is some documentation out there for using tv_grab to get multiple lineups, and a way to merge them. At the moment I haven’t experimented with that.

Next I wanted to get the icons for the tv stations. I found them online. No need to go into that. I have all the icons for the stations I get. I put them in the downloads folder on cinnamon, and then copied them into a directory I created for this at ~/.hts/tvheadend/TVChannelIcons. Then for each channel in Configure->Channel/EPG->Channels I adjusted the “User Icon” field (double click, type in name) to have a url to the icon (e.g. file:///home/hts/.hts/tvheadend/TVChannelIcons/NBC.gif). [On subsequently rebuilding this whole thing, I now find that for at least some of them, tvheadend now reaches out and finds some icons. I haven’t researched what is going on here. Instead of a url like file:///<downloaded icon> the field containes <picon>

Last thing, to figure out how to get the listings both for Boulder and Denver. I switched to using “XMLTV: Combine data from several other grabbers” in Configuration->Channel/EPG-> EPG Grabber, which I discover invokes “tv_grab_combine” script.

28 September 2015
I noticed that there was no live tv and no epg data. Had been messing with the stuff in the distribution panel downstairs, and I had also upgraded Cinnamon to Vivid. The tvheadend software had to be restarted on ubuntu because the HDHomeRun had been down when Cinnamon had rebooted. So the live tv came back, but the epg data was still completely non-existent.

Research revealed that when I reinstalled ubuntu, the files in /usr/bin/tv_grab* had been reloaded, and my changes in /usr/bin/tv_grab_na_dd had been lost. After I made the changes again (as shown above), and then did a restart of tvheadend (systemctl restart tvheadend) it was ok.

When I was trying to troubleshoot this, it occured to me that I wasn’t sure where the cron was for reloading the data, and I looked for it in /etc/cron* but it isn’t there. After I got it running again, I looked and it is not in the system cron stuff, so I’m assuming it must be run directly out of the tvheadend daemon.

21 October 2016

tvheadend began to get a hard crash, causing a core dump. I have no idea what happened to it, but I eventually gave up, and reinstalled. That didn’t fix it, I had to throw away the config andd restart..

One problem I had after reinitializing was that the inbuilt webserver would not let me in with a browser. Turns out after some research that the webserver is launched to disallow logins. You have to start tvheadend with a -C flag so that it will allow an anonymous login, and then you can get in and set up a password.


In tvheadend, as far as I can tell, here is the way they use the words.

Network is a logical construct for matching hardware devices into TVHE. You assign a device (in my case a tuner in HDHomeRun) to a network.

A TV Adapter is a piece of hardware, like said HDHomeRun tuner.

A Mux, or Multiplexor, is an Mpeg2 Transport Stream on a frequency. It may contain more than one “service”, i.e. program stream. A mux is a particular tuner frequency on a Network (where there is hardware on the network).

A service is a stream of content. More than one service can be present that are actually carrying the same content (e.g 2 NBC affiliates on different frequencies), or even the same NBC affiliate on two different frequencies – one from Boulder and one from Denver.

A channel is a