hdhomerun

README

hdhomerun

Package hdhomerun enables interacting with SiliconDust HDHomeRun devices. MIT Licensed.

Documentation

Overview

Package hdhomerun enables interacting with SiliconDust HDHomeRun devices.

Index

• Constants
• func IsNotExist(err error) bool
• func ParseDeviceID(id string) ([]byte, error)
• type CableCARDStatus
• type Client
  • func Dial(addr string) (*Client, error)
  • func NewClient(conn net.Conn) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Execute(req *Packet) (*Packet, error)
  • func (c *Client) ForEachTuner(fn func(t *Tuner) error) error
  • func (c *Client) Model() (string, error)
  • func (c *Client) Query(query string) ([]byte, error)
  • func (c *Client) SetTimeout(d time.Duration)
  • func (c *Client) Tuner(n int) *Tuner
• type DeviceStatus
• type DeviceType
  • func (t DeviceType) String() string
• type DiscoveredDevice
• type Discoverer
  • func NewDiscoverer(options ...DiscovererOption) (*Discoverer, error)
  • func (d *Discoverer) Discover(ctx context.Context) (*DiscoveredDevice, error)
• type DiscovererOption
  • func DiscoverDeviceID(id string) DiscovererOption
  • func DiscoverDeviceType(t DeviceType) DiscovererOption
• type Error
  • func (err *Error) Error() string
• type NetworkStatus
• type Packet
  • func (p *Packet) MarshalBinary() ([]byte, error)
  • func (p *Packet) UnmarshalBinary(b []byte) error
• type StopReason
• type Tag
• type TransportStreamStatus
• type Tuner
  • func (t *Tuner) Debug() (*TunerDebug, error)
  • func (t *Tuner) VChannel() (string, error)
• type TunerDebug
• type TunerStatus

Examples

• Discoverer (Discover)

Constants

const (
	DeviceTypeTuner   = DeviceType(libhdhomerun.DeviceTypeTuner)
	DeviceTypeStorage = DeviceType(libhdhomerun.DeviceTypeStorage)

	// DeviceTypeWildcard is used during discovery to request that all
	// types of devices reply to the request.
	DeviceTypeWildcard = DeviceType(libhdhomerun.DeviceTypeWildcard)
)

Possible DeviceType values.

const DeviceIDWildcard = "ffffffff" // libhdhomerun.DeviceIdWildcard

DeviceIDWildcard is used during discovery to request that a device with any ID reply to the request.

Functions

func IsNotExist

func IsNotExist(err error) bool

IsNotExist determines if an error occurred during Client.Query because the specified key does not exist.

func ParseDeviceID

func ParseDeviceID(id string) ([]byte, error)

ParseDeviceID parses an eight character hexadecimal string into its byte representation for transmission in a Packet.

Types

type CableCARDStatus

type CableCARDStatus struct {
	BitsPerSecond int
	Resync        int
	Overflow      int
}

CableCARDStatus is the status of a CableCARD, if one is present in the device.

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client is an HDHomeRun client. It can be used to perform various operations on HDHomeRun devices. Clients are safe for concurrent use.

func Dial

func Dial(addr string) (*Client, error)

Dial dials a TCP connection to an HDHomeRun device.

For more control over the Client, use a net.Conn with NewClient instead.

func NewClient

func NewClient(conn net.Conn) (*Client, error)

NewClient wraps an existing net.Conn to create a Client.

func (*Client) Close

func (c *Client) Close() error

Close closes the Client's underlying connection.

func (*Client) Execute

func (c *Client) Execute(req *Packet) (*Packet, error)

Execute sends a single request to an HDHomeRun device, and reads a single reply from the device.

Execute is a low-level method that does no request validation, and should be used with great caution.

Most users should use the Query method instead.

func (*Client) ForEachTuner

func (c *Client) ForEachTuner(fn func(t *Tuner) error) error

ForEachTuner invokes the input function for each tuner available to an HDHomeRun device. Iteration stops when no more tuners are available.

func (*Client) Model

func (c *Client) Model() (string, error)

Model returns the model name of an HDHomeRun device.

func (*Client) Query

func (c *Client) Query(query string) ([]byte, error)

Query performs a read-only query to retrieve information from an HDHomeRun device. A list of possible query values can be found by sending "help" as the query parameter.

If the query tries to read a key that does not exist, IsNotExist can be used to check this error.

func (*Client) SetTimeout

func (c *Client) SetTimeout(d time.Duration)

SetTimeout sets a per-request timeout for a combined write and read interaction with an HDHomeRun device. For finer control, use a pre-configured net.Conn with NewClient.

SetTimeout will override any deadlines configured on a net.Conn used with NewClient.

func (*Client) Tuner

func (c *Client) Tuner(n int) *Tuner

Tuner accesses methods of an HDHomeRun tuner with the specified index.

type DeviceStatus

type DeviceStatus struct {
	BitsPerSecond int
	Resync        int
	Overflow      int
}

DeviceStatus is the status of the tuner while processing a stream.

type DeviceType

type DeviceType uint32

A DeviceType is a constant indicating the type of an HDHomeRun device, such as a tuner or storage unit.

func (DeviceType) String

func (t DeviceType) String() string

String returns the string representation of a DeviceType.

type DiscoveredDevice

type DiscoveredDevice struct {
	// ID is the unique ID of this device.
	ID string

	// Addr is the network address of this device.
	Addr string

	// Type is the type of device discovered, such as a tuner or storage unit.
	Type DeviceType

	// URL, if available, is the URL for the device's web UI.
	URL *url.URL

	// Tuners is the number of TV tuners available to the device.
	Tuners int
}

A DiscoveredDevice is a device encountered during discovery. Its network address can be used with Dial to initiate a direct connection to a device.

type Discoverer

type Discoverer struct {
	// contains filtered or unexported fields
}

A Discoverer can discover HDHomeRun devices on a network.

Example (Discover)

This example demonstrates the use of a Discoverer to discover devices until a timeout elapses.

package main

import (
	"context"
	"io"
	"log"
	"time"

	"github.com/joydip/hdhomerun"
)

func main() {
	// Discover devices of any type with any ID.
	d, err := hdhomerun.NewDiscoverer()
	if err != nil {
		log.Fatalf("error starting discovery: %v", err)
	}

	// Discover devices for up to 2 seconds or until canceled.
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	for {
		// Note: Discover blocks until a device is found or its context is
		// canceled.  Always pass a context with a cancel function, deadline,
		// or timeout.
		//
		// io.EOF is returned when the context is canceled.
		device, err := d.Discover(ctx)
		switch err {
		case nil:
			// Found a device.
			// If only one device is expected, invoke cancel here.
			log.Println("device:", device)
		case io.EOF:
			// Context canceled; no more devices to be found.
			return
		default:
			log.Fatalf("error during discovery: %v", err)
		}
	}
}

func NewDiscoverer

func NewDiscoverer(options ...DiscovererOption) (*Discoverer, error)

NewDiscoverer creates a Discoverer that can discover devices using a UDP multicast mechanism. By default, the Discoverer will look for any type of device with any ID.

If needed, DiscovererOptions can be provided to modify the behavior of the Discoverer.

func (*Discoverer) Discover

func (d *Discoverer) Discover(ctx context.Context) (*DiscoveredDevice, error)

Discover discovers HDHomeRun devices over a network. Discover will block indefinitely until a device is found, or the context is canceled. If the context is canceled, an io.EOF error will be returned.

type DiscovererOption

type DiscovererOption func(d *Discoverer) error

A DiscovererOption is an option which modifies the behavior of a Discoverer.

func DiscoverDeviceID

func DiscoverDeviceID(id string) DiscovererOption

DiscoverDeviceID requests that a Discoverer only search for devices with the specified ID.

func DiscoverDeviceType

func DiscoverDeviceType(t DeviceType) DiscovererOption

DiscoverDeviceType requests that a Discoverer only search for devices with the specified type.

type Error

type Error struct {
	Message string
}

An Error is an error message returned by an HDHomeRun device.

func (*Error) Error

func (err *Error) Error() string

Error implements error.

type NetworkStatus

type NetworkStatus struct {
	PacketsPerSecond int
	Errors           int
	Stop             StopReason
}

NetworkStatus is the status of an outgoing network stream from the tuner.

type Packet

type Packet struct {
	// Type specifies the type of message this Packet carries.
	Type uint16

	// Tags specifies zero or more tags containing optional attributes.
	Tags []Tag
}

A Packet is a network packet used to communicate with HDHomeRun devices.

func (*Packet) MarshalBinary

func (p *Packet) MarshalBinary() ([]byte, error)

MarshalBinary marshals a Packet into its binary form.

func (*Packet) UnmarshalBinary

func (p *Packet) UnmarshalBinary(b []byte) error

UnmarshalBinary unmarshals a Packet from its binary form.

type StopReason

type StopReason int

A StopReason is a reason why a tuner's network stream has stopped.

const (
	StopReasonNotStopped          StopReason = 0
	StopReasonIntentional         StopReason = 1
	StopReasonICMPReject          StopReason = 2
	StopReasonConnectionLoss      StopReason = 3
	StopReasonHTTPConnectionClose StopReason = 4
)

Possible StopReason values.

type Tag

type Tag struct {
	// Type specifies the type of payload this Tag carries.
	Type uint8

	// Data is an arbitrary byte payload.
	Data []byte
}

A Tag is an attribute carried by a Packet.

type TransportStreamStatus

type TransportStreamStatus struct {
	BitsPerSecond   int
	TransportErrors int
	CRCErrors       int
}

TransportStreamStatus is the status of an incoming video stream from the tuner.

type Tuner

type Tuner struct {
	Index int
	// contains filtered or unexported fields
}

A Tuner is an HDHomeRun TV tuner. The Index field specifies which tuner will be queried. Tuners should be constructed using the Tuner method of the Client type.

func (*Tuner) Debug

func (t *Tuner) Debug() (*TunerDebug, error)

Debug retrieves a variety of debugging information about the Tuner, specified by its index.

func (*Tuner) VChannel

func (t *Tuner) VChannel() (string, error)

VChannel retrieves the virtual channel the Tuner is tuned to.

type TunerDebug

type TunerDebug struct {
	Tuner           *TunerStatus
	Device          *DeviceStatus
	CableCARD       *CableCARDStatus
	TransportStream *TransportStreamStatus
	Network         *NetworkStatus
}

TunerDebug contains debugging information about an HDHomeRun TV tuner.

If information about a particular component is not available, the field's value will be nil.

Information about particular fields can be found in the HDHomeRun Development Guide: https://www.silicondust.com/hdhomerun/hdhomerun_development.pdf.

type TunerStatus

type TunerStatus struct {
	Channel              string
	Lock                 string
	SignalStrength       int
	SignalToNoiseQuality int
	SymbolErrorQuality   int
	Debug                string
}

TunerStatus is the status of an HDHomeRun tuner.