====== hdhomerun_config ======

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

This utility is cross-platform:
  * Windows, Linux, Mac, *BSD, Solaris.
  * 32-bit or 64-bit operating systems.
  * Big-endian and little-endian CPUs.
  * PC or embedded platforms.

===== Obtaining hdhomerun_config =====
<WRAP indent>

=== Windows (pre-compiled) ===
<WRAP indent>

Download and install the [[https://download.silicondust.com/hdhomerun/hdhomerun_windows.exe|HDHomeRun software for Windows]]. The hdhomerun_config.exe executable can be found in the program directory - default C:\Program Files\Silicondust\HDHomeRun.

</WRAP>

=== Windows (MSVC++) ===
<WRAP indent>

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.

</WRAP>
=== Mac (pre-compiled) ===
<WRAP indent>

Download the [[https://download.silicondust.com/hdhomerun/hdhomerun_mac.dmg|HDHomeRun for Mac software]] and run the installer. This will install the command line utility for use in the Terminal app.

</WRAP>
=== Linux/BSD ===
<WRAP indent>

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

Run "make"

</WRAP>
</WRAP>

===== Using hdhomerun_config =====
<WRAP indent>

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>

</WRAP>

===== Discover the HDHomeRun devices on the network =====
<WRAP indent>

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

</WRAP>

===== Sending commands to a specific HDHomeRun =====
<WRAP indent>

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.

</WRAP>

===== Query the list of options supported by a HDHomeRun device =====
<WRAP indent>

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

</WRAP>

===== Channelmap =====
<WRAP indent>

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.

<code>
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
</code>

<WRAP box>
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 |
</WRAP>

<WRAP box>
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               |
</WRAP>

</WRAP>

===== Channel scan =====
<WRAP indent>

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

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.

</WRAP>

===== Tuning a physical channel =====
<WRAP indent>

To set a channel use the set channel command:
<code>
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
</code>

Supported modulation types can be queried with the get sys-features command:
<code>
hdhomerun_config <id> get /sys/features
</code>

To stop the tuner set the channel to none:
<code>
format: hdhomerun_config <id> set /tuner<n>/channel none
eg:     hdhomerun_config FFFFFFFF set /tuner0/channel none
</code>

</WRAP>

===== Checking the signal strength =====
<WRAP indent>

The basic signal information can be obtained by using the get status command:
<code>
format: hdhomerun_config <device id> get /tuner<n>/status
eg:     hdhomerun_config FFFFFFFF get /tuner0/status
</code>
Example output:
<code>ch=qam:33 lock=qam256 ss=83 snq=90 seq=100 bps=38807712 pps=0</code>

  * 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:
<code>
format: hdhomerun_config <device id> get /tuner<n>/debug
eg:     hdhomerun_config FFFFFFFF get /tuner0/debug
</code>

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.

</WRAP>

===== Detecting the programs on a physical channel =====
<WRAP indent>

The HDHomeRun will detect the programs (sub-channels). Use the get streaminfo command to query the detected programs:
<code>
format: hdhomerun_config <id> get /tuner<n>/streaminfo
eg:     hdhomerun_config FFFFFFFF get /tuner0/ streaminfo
</code>

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).

</WRAP>

===== Filtering by program (sub-channel) =====
<WRAP indent>

The HDHomeRun supports automatic PID filtering by program number:
<code>
format: hdhomerun_config <id> set /tuner<n>/program <program number>
eg:     hdhomerun_config FFFFFFFF set /tuner0/program 3
</code>

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:
<code>
hdhomerun_config <id> set /tuner<n>/program "<program number>
tvct_from_pmt=<virtual major>.<virtual minor>(<name>)"
</code>
<code>
eg:
hdhomerun_config <id> set /tuner0/program "3 tvct_from_pmt=11.2(TEST)"
</code>

</WRAP>

===== Filtering by PID =====
<WRAP indent>

The HDHomeRun supports arbitrary hardware PID filtering:
<code>
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"
</code>

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.

</WRAP>

===== Saving a stream =====
<WRAP indent>

The hdhomerun_config command can be used to automate the process of saving to the local filesystem:
<code>
format: hdhomerun_config <id> save /tuner<n> <filename>
eg:     hdhomerun_config FFFFFFFF save /tuner0 capture.ts
</code>

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:
<code>
............n...............................n..........ts..........
-- Video statistics --
23323 packets recieved, 2 network errors, 1 transport errors, 1 sequence errors
</code>

**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.

<code>eg:     hdhomerun_config FFFFFFFF save /tuner0 - | vlc -</code>

</WRAP>

===== Streaming to a target machine =====
<WRAP indent>

Set the target IP address and port number using the set target command:
<code>
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
</code>

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 ===
<WRAP indent>

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

</WRAP>
</WRAP>

{{tag>troubleshooting}}
{{tag>development}}