Table of Contents

hdhomerun_config

The HDHomeRun can be scripted using the hdhomerun_config command line utility.

This utility is cross-platform:

Obtaining hdhomerun_config

Windows (pre-compiled)

Download and install the HDHomeRun software for Windows. The hdhomerun_config.exe executable can be found in the program directory - default C:\Program Files\Silicondust\HDHomeRun.

Windows (MSVC++)

Download and extract the libhdhomerun archive ( https://github.com/Silicondust/libhdhomerun ). Create a new empty project and include all the .c and .h files. From the project properties page under C/C++ advanced, change the Compile As type to C, click apply and then change it back to C++ – this is a workaround for a bug in MSVC++. Under the Linker input, add Ws2_32.lib and iphlpapi.lib as Additional Dependencies.

Compile.

Mac (pre-compiled)

Download the HDHomeRun for Mac software and run the installer. This will install the command line utility for use in the Terminal app.

Linux/BSD

Download and extract the libhdhomerun archive ( https://github.com/Silicondust/libhdhomerun ).

Run “make”

Using hdhomerun_config

The list of supported commands can be obtained by running hdhomerun_config without any parameters:

      hdhomerun_config discover
      hdhomerun_config <id> get help
      hdhomerun_config <id> get <item>
      hdhomerun_config <id> set <item> <value>
      hdhomerun_config <id> scan <tuner> [<filename>]
      hdhomerun_config <id> save <tuner> <filename>
      hdhomerun_config <id> upgrade <filename>

Discover the HDHomeRun devices on the network

The discover command will find HDHomeRun devices that are on the same subnet as the host:

      hdhomerun_config discover

Sending commands to a specific HDHomeRun

The “<id>” shown above represents a unique identifier for a HDHomeRun device, this can be either Device ID, or IP address:

      hdhomerun_config <device id> get help
      hdhomerun_config <ip address> get help

To address by Device ID the HDHomeRun must be on the same subnet as the host.

A Device ID of FFFFFFFF can be used as a wild card for the first HDHomeRun device found on the network. Do not use this syntax if there are multiple HDHomeRun devices on the network, as the device used will be random based on discovery order, which may change between commands.

Query the list of options supported by a HDHomeRun device

The get/set options supported by a specific HDHomeRun device can be queried using the get help command:

      hdhomerun_config <id> get help

Example output:

Supported configuration options:

/tuner<n>/channel <modulation>:<freq|ch>
Get/set modulation and frequency
/tuner<n>/channelmap <channel map>
Get/set channel to frequency map
/tuner<n>/filter 0x<nnnn>-0x<nnnn> [...]
Get/set PID filter
/tuner<n>/program <program number>
Get/set MPEG program filter
/tuner<n>/target <ip>:<port>
Get/set target IP for tuner
/tuner<n>/status
Display status of tuner
/tuner<n>/streaminfo
Display stream info
/tuner<n>/debug
Display debug info for tuner
/tuner<n>/lockkey
Set/clear tuner lock
/ir/target <ip>:<port>
Get/set target IP for IR
/lineup/location <countrycode>:<postcode>
Get/Set location for lineup
/lineup/location disabled
Disable lineup server connection
/sys/model
Display model name
/sys/features
Display supported features
/sys/version
Display firmware version
/sys/copyright
Display firmware copyright
/sys/debug
Display debug info
/sys/restart
Restart tuner/HDHomeRun. For example,
set /sys/restart self

will reboot the HDHomeRun.

Channelmap

The channelmap is used to configure the auto-modulation detection and channel scan. This should be configured correctly for each tuner.

The channelmap configuration is stored in non-volatile memory so only needs to be set once.

format: hdhomerun_config <device id> get /tuner<n>/channelmap
format: hdhomerun_config <device id> set /tuner<n>/channelmap <channelmap>
eg:     hdhomerun_config FFFFFFFF get /tuner0/channelmap
eg:     hdhomerun_config FFFFFFFF set /tuner0/channelmap us-bcast

Channel maps supported by HDHR-US hardware:

Name Description Location
us-bcast Digital Antenna (ATSC) US, Canada
us-cable Digital Cable - Normal frequency layout US, Canada
us-hrc Digital Cable - HRC frequency layout US, Canada
us-irc Digital Cable - IRC frequency layout US, Canada

Channel maps supported by HDHR-EU hardware:

Name Description Location
au-bcast Digital Antenna (Australia) Australia
au-cable Digital Cable (Australia) Australia
eu-bcast Digital Antenna (Europe) Europe, New Zealand
eu-cable Digital Cable (Europe) Europe, New Zealand
tw-bcast Digital Antenna (Taiwan) Taiwan
tw-cable Digital Cable (Taiwan) Taiwan

Channel scan

To run a channel scan:

format: hdhomerun_config <device id> scan /tuner<n> [<log filename>]
eg:     hdhomerun_config FFFFFFFF scan /tuner0 scan0.log

This command will scan all channels on the selected channelmap plus any additional channelmaps associated with the selected channelmap. All standard modulation types for the selected channelmap are tested.

When a digital channel is found it will identify the programs on the channel. The log filename is optional; if included it will log to the given filename.

Tuning a physical channel

To set a channel use the set channel command:

format: hdhomerun_config <id> set /tuner<n>/channel <modulation>:<frequency>
format: hdhomerun_config <id> set /tuner<n>/channel <modulation>:<channel>
eg:     hdhomerun_config FFFFFFFF set /tuner0/channel auto:651000000
eg:     hdhomerun_config FFFFFFFF set /tuner0/channel auto:60

Supported modulation types can be queried with the get sys-features command:

hdhomerun_config <id> get /sys/features

To stop the tuner set the channel to none:

format: hdhomerun_config <id> set /tuner<n>/channel none
eg:     hdhomerun_config FFFFFFFF set /tuner0/channel none

Checking the signal strength

The basic signal information can be obtained by using the get status command:

format: hdhomerun_config <device id> get /tuner<n>/status
eg:     hdhomerun_config FFFFFFFF get /tuner0/status

Example output:

ch=qam:33 lock=qam256 ss=83 snq=90 seq=100 bps=38807712 pps=0
  • ch = channel requested
  • lock = actual modulation detected
  • ss = signal strength. 80% is approximately -12dBmV.
  • snq = signal to noise quality (based on analog signal to noise ratio).
  • seq = symbol error quality (number of uncorrectable digital errors detected).
  • bps = raw channel bits per second.
  • pps = packets per second sent through the network.

More advanced information can be obtained by using the get debug command:

format: hdhomerun_config <device id> get /tuner<n>/debug
eg:     hdhomerun_config FFFFFFFF get /tuner0/debug

Example output:

    tun: ch=qam:33 lock=qam256 ss=84 snq=88 seq=100 dbg=22081-6930
    dev: resync=0 overflow=0
    ts:  bps=38809216 ut=94 te=0 miss=0 crc=0
    flt: bps=38809216
    net: pps=0 err=0 stop=0

Each line contains a prefix to indicate the type of data, followed by the values.

  • tun = tuner status
    • see above section
  • dev = device status
  • ts = transport stream
    • bps = bits per second
    • ut = utilization percentage (100% is filled to capacity)
    • te = transport error counter (uncorrectable reception error)
    • miss = missed packet counter (jump in sequence numbers)
    • crc = crc error counter
  • flt = results after pid filtering
    • bps = bits per second
  • net = network status
    • pps = packets per second
    • err = packets or TS frames dropped before transmission.
    • stop = reason for stopping the stream

The counters are reset to zero upon a channel change, but may indicate a small number of errors caused before the tuner locks on the channel. As a result, diagnostics should be based on the change in values over time, and not the initial values.

Detecting the programs on a physical channel

The HDHomeRun will detect the programs (sub-channels). Use the get streaminfo command to query the detected programs:

format: hdhomerun_config <id> get /tuner<n>/streaminfo
eg:     hdhomerun_config FFFFFFFF get /tuner0/ streaminfo

The output format is:

   <program number>: <virtual major>.<virtual minor> [<name>] [(<flags>)]

Example output:

    3: 20.1 KBWB-HD
    4: 20.4 AZTECA

Digital cable does not always provide the channel name or virtual channel number:

    1: 0
    2: 0 (encrypted)
    3: 0 (control)

It may take several seconds after setting the channel for the stream information to be fully populated (depending on how long the channel takes to lock and how often the stream information is sent by the broadcaster/cable provider).

Filtering by program (sub-channel)

The HDHomeRun supports automatic PID filtering by program number:

format: hdhomerun_config <id> set /tuner<n>/program <program number>
eg:     hdhomerun_config FFFFFFFF set /tuner0/program 3

When filtering by program the PAT and PMT tables are generated by the HDHomeRun. The result is a valid single-program transport stream. The program filter is cleared when a set channel or a set filter command is received.

Advanced: By default the PAT and PMT are generated. To also generate a ATSC-style TVCT use:

hdhomerun_config <id> set /tuner<n>/program "<program number>
tvct_from_pmt=<virtual major>.<virtual minor>(<name>)"
eg:
hdhomerun_config <id> set /tuner0/program "3 tvct_from_pmt=11.2(TEST)"

Filtering by PID

The HDHomeRun supports arbitrary hardware PID filtering:

format: hdhomerun_config <id> set /tuner<n>/filter <filter>
eg:     hdhomerun_config FFFFFFFF set /tuner0/filter "0x0000-0x1FFF"
        hdhomerun_config FFFFFFFF set /tuner0/filter "0x0000 0x0030-0x0033 0x1FFB"

When filtering by PID the stream is filtered but otherwise unmodified.

The filter is cleared to pass-all (0x0000-0x1FFF) when a set channel command is received.

Saving a stream

The hdhomerun_config command can be used to automate the process of saving to the local filesystem:

format: hdhomerun_config <id> save /tuner<n> <filename>
eg:     hdhomerun_config FFFFFFFF save /tuner0 capture.ts

While saving the stream, a single period “.” will be displayed every second. Additionally, as of the 20080609 release, the hdhomerun_config will detect reception and network errors, replacing the “.” with an alternative character to indicate the problem.

Example output:

............n...............................n..........ts..........
-- Video statistics --
23323 packets recieved, 2 network errors, 1 transport errors, 1 sequence errors

Advanced: A filename of “null” indicates no file should be created, allowing the use of the save command as a diagnostic tool.

Advanced: “-” may be used as a filename to indicate standard output, allowing the save command to be used as a pipe on supported platforms.

eg:     hdhomerun_config FFFFFFFF save /tuner0 - | vlc -

Streaming to a target machine

Set the target IP address and port number using the set target command:

format: hdhomerun_config <id> set /tuner<n>/target udp://<ip>:<port>
format: hdhomerun_config <id> set /tuner<n>/target rtp://<ip>:<port>
eg:     hdhomerun_config FFFFFFFF set /tuner0/target udp://192.168.1.100:5000
eg:     hdhomerun_config FFFFFFFF set /tuner0/target rtp://192.168.1.100:5000

The target machine must be listening on the given UDP port. The HDHomeRun will automatically clear the target if a ICMP port unreachable message is received.

A global broadcast (255.255.255.255) or subnet broadcast can be specified however care must be taken to ensure that the broadcast traffic will not cause problems with other devices on the network. If the local network is bridged to a wireless network then the AP will typically transmit at a low broadcast speed saturating the wireless network.



Example: Streaming to VLC

Run VLC: File, Open Network Stream. Select UDP/RTP. Specify port 5000. Discover the HDHomeRun:

      hdhomerun_config discover

Run a channel scan:

      hdhomerun_config FFFFFFFF scan /tuner0 scan0.log

Set the physical channel:

      hdhomerun_config FFFFFFFF set /tuner0/channel auto:651000000

Check sub-programs:

      hdhomerun_config FFFFFFFF get /tuner0/streaminfo

Select a sub-program:

      hdhomerun_config FFFFFFFF set /tuner0/program 3

Set the target:

      hdhomerun_config FFFFFFFF set /tuner0/target <ip address of pc>:5000