Chapter 9. DVB Frontend API

Table of Contents

Frontend Data Types
frontend type
frontend capabilities
frontend information
diseqc master command
diseqc slave reply
diseqc slave reply
SEC continuous tone
SEC tone burst
frontend status
frontend parameters
frontend events
Frontend Function Calls
open()
close()
FE_READ_STATUS
FE_READ_BER
FE_READ_SNR
FE_READ_SIGNAL_STRENGTH
FE_READ_UNCORRECTED_BLOCKS
FE_SET_FRONTEND
FE_GET_FRONTEND
FE_GET_EVENT
FE_GET_INFO
FE_DISEQC_RESET_OVERLOAD
FE_DISEQC_SEND_MASTER_CMD
FE_DISEQC_RECV_SLAVE_REPLY
FE_DISEQC_SEND_BURST
FE_SET_TONE
FE_SET_VOLTAGE
FE_ENABLE_HIGH_LNB_VOLTAGE
FE_SET_FRONTEND_TUNE_MODE
FE_DISHNETWORK_SEND_LEGACY_CMD
FE_GET_PROPERTY/FE_SET_PROPERTY
FE_GET_PROPERTY
FE_SET_PROPERTY
Property types
Parameters that are common to all Digital TV standards
ISDB-T frontend

The DVB frontend device controls the tuner and DVB demodulator hardware. It can be accessed through /dev/dvb/adapter0/frontend0. Data types and and ioctl definitions can be accessed by including linux/dvb/frontend.h in your application.

DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is not yet handled by this API but a future extension is possible. For DVB-S the frontend device also supports satellite equipment control (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification is available from Eutelsat.

Note that the DVB API may also be used for MPEG decoder-only PCI cards, in which case there exists no frontend device.

Frontend Data Types

frontend type

For historical reasons frontend types are named after the type of modulation used in transmission.

	typedef enum fe_type {
	FE_QPSK,   /⋆ DVB-S ⋆/
	FE_QAM,    /⋆ DVB-C ⋆/
	FE_OFDM    /⋆ DVB-T ⋆/
	} fe_type_t;

frontend capabilities

Capabilities describe what a frontend can do. Some capabilities can only be supported for a specific frontend type.

	typedef enum fe_caps {
	FE_IS_STUPID                  = 0,
	FE_CAN_INVERSION_AUTO         = 0x1,
	FE_CAN_FEC_1_2                = 0x2,
	FE_CAN_FEC_2_3                = 0x4,
	FE_CAN_FEC_3_4                = 0x8,
	FE_CAN_FEC_4_5                = 0x10,
	FE_CAN_FEC_5_6                = 0x20,
	FE_CAN_FEC_6_7                = 0x40,
	FE_CAN_FEC_7_8                = 0x80,
	FE_CAN_FEC_8_9                = 0x100,
	FE_CAN_FEC_AUTO               = 0x200,
	FE_CAN_QPSK                   = 0x400,
	FE_CAN_QAM_16                 = 0x800,
	FE_CAN_QAM_32                 = 0x1000,
	FE_CAN_QAM_64                 = 0x2000,
	FE_CAN_QAM_128                = 0x4000,
	FE_CAN_QAM_256                = 0x8000,
	FE_CAN_QAM_AUTO               = 0x10000,
	FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
	FE_CAN_BANDWIDTH_AUTO         = 0x40000,
	FE_CAN_GUARD_INTERVAL_AUTO    = 0x80000,
	FE_CAN_HIERARCHY_AUTO         = 0x100000,
	FE_CAN_8VSB                   = 0x200000,
	FE_CAN_16VSB                  = 0x400000,
	FE_HAS_EXTENDED_CAPS          = 0x800000,
	FE_CAN_TURBO_FEC              = 0x8000000,
	FE_CAN_2G_MODULATION          = 0x10000000,
	FE_NEEDS_BENDING              = 0x20000000,
	FE_CAN_RECOVER                = 0x40000000,
	FE_CAN_MUTE_TS                = 0x80000000
	} fe_caps_t;

frontend information

Information about the frontend ca be queried with FE_GET_INFO.

	struct dvb_frontend_info {
	char       name[128];
	fe_type_t  type;
	uint32_t   frequency_min;
	uint32_t   frequency_max;
	uint32_t   frequency_stepsize;
	uint32_t   frequency_tolerance;
	uint32_t   symbol_rate_min;
	uint32_t   symbol_rate_max;
	uint32_t   symbol_rate_tolerance;     /⋆ ppm ⋆/
	uint32_t   notifier_delay;            /⋆ ms ⋆/
	fe_caps_t  caps;
	};

diseqc master command

A message sent from the frontend to DiSEqC capable equipment.

	struct dvb_diseqc_master_cmd {
	uint8_t msg [6]; /⋆  { framing, address, command, data[3] } ⋆/
	uint8_t msg_len; /⋆  valid values are 3...6  ⋆/
	};

diseqc slave reply

A reply to the frontend from DiSEqC 2.0 capable equipment.

	struct dvb_diseqc_slave_reply {
	uint8_t msg [4]; /⋆  { framing, data [3] } ⋆/
	uint8_t msg_len; /⋆  valid values are 0...4, 0 means no msg  ⋆/
	int     timeout; /⋆  return from ioctl after timeout ms with ⋆/
	};                       /⋆  errorcode when no message was received  ⋆/

diseqc slave reply

The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation (horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec.

	typedef enum fe_sec_voltage {
	SEC_VOLTAGE_13,
	SEC_VOLTAGE_18
	} fe_sec_voltage_t;

SEC continuous tone

The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec.

	typedef enum fe_sec_tone_mode {
	SEC_TONE_ON,
	SEC_TONE_OFF
	} fe_sec_tone_mode_t;

SEC tone burst

The 22KHz tone burst is usually used with non-DiSEqC capable switches to select between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec.

	typedef enum fe_sec_mini_cmd {
	SEC_MINI_A,
	SEC_MINI_B
	} fe_sec_mini_cmd_t;

frontend status

Several functions of the frontend device use the fe_status data type defined by

 typedef enum fe_status {
	 FE_HAS_SIGNAL     = 0x01,   /⋆  found something above the noise level ⋆/
	 FE_HAS_CARRIER    = 0x02,   /⋆  found a DVB signal  ⋆/
	 FE_HAS_VITERBI    = 0x04,   /⋆  FEC is stable  ⋆/
	 FE_HAS_SYNC       = 0x08,   /⋆  found sync bytes  ⋆/
	 FE_HAS_LOCK       = 0x10,   /⋆  everything's working... ⋆/
	 FE_TIMEDOUT       = 0x20,   /⋆  no lock within the last ~2 seconds ⋆/
	 FE_REINIT         = 0x40    /⋆  frontend was reinitialized,  ⋆/
 } fe_status_t;                      /⋆  application is recommned to reset ⋆/

to indicate the current state and/or state changes of the frontend hardware.

frontend parameters

The kind of parameters passed to the frontend device for tuning depend on the kind of hardware you are using. All kinds of parameters are combined as an union in the FrontendParameters structure:

 struct dvb_frontend_parameters {
	 uint32_t frequency;       /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/
				   /⋆ intermediate frequency in kHz for QPSK ⋆/
	 fe_spectral_inversion_t inversion;
	 union {
		 struct dvb_qpsk_parameters qpsk;
		 struct dvb_qam_parameters  qam;
		 struct dvb_ofdm_parameters ofdm;
	 } u;
 };

For satellite QPSK frontends you have to use the QPSKParameters member defined by

 struct dvb_qpsk_parameters {
	 uint32_t        symbol_rate;  /⋆ symbol rate in Symbols per second ⋆/
	 fe_code_rate_t  fec_inner;    /⋆ forward error correction (see above) ⋆/
 };

for cable QAM frontend you use the QAMParameters structure

 struct dvb_qam_parameters {
	 uint32_t         symbol_rate; /⋆ symbol rate in Symbols per second ⋆/
	 fe_code_rate_t   fec_inner;   /⋆ forward error correction (see above) ⋆/
	 fe_modulation_t  modulation;  /⋆ modulation type (see above) ⋆/
 };

DVB-T frontends are supported by the OFDMParamters structure

 struct dvb_ofdm_parameters {
	 fe_bandwidth_t      bandwidth;
	 fe_code_rate_t      code_rate_HP;  /⋆ high priority stream code rate ⋆/
	 fe_code_rate_t      code_rate_LP;  /⋆ low priority stream code rate ⋆/
	 fe_modulation_t     constellation; /⋆ modulation type (see above) ⋆/
	 fe_transmit_mode_t  transmission_mode;
	 fe_guard_interval_t guard_interval;
	 fe_hierarchy_t      hierarchy_information;
 };

In the case of QPSK frontends the Frequency field specifies the intermediate frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and OFDM frontends the Frequency specifies the absolute frequency and is given in Hz.

The Inversion field can take one of these values:

 typedef enum fe_spectral_inversion {
	 INVERSION_OFF,
	 INVERSION_ON,
	 INVERSION_AUTO
 } fe_spectral_inversion_t;

It indicates if spectral inversion should be presumed or not. In the automatic setting (INVERSION_AUTO) the hardware will try to figure out the correct setting by itself.

The possible values for the FEC_inner field are

 typedef enum fe_code_rate {
	 FEC_NONE = 0,
	 FEC_1_2,
	 FEC_2_3,
	 FEC_3_4,
	 FEC_4_5,
	 FEC_5_6,
	 FEC_6_7,
	 FEC_7_8,
	 FEC_8_9,
	 FEC_AUTO
 } fe_code_rate_t;

which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto detection.

For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature modulation mode which can be one of the following:

 typedef enum fe_modulation {
 QPSK,
	 QAM_16,
	 QAM_32,
	 QAM_64,
	 QAM_128,
	 QAM_256,
	 QAM_AUTO
 } fe_modulation_t;

Finally, there are several more parameters for OFDM:

 typedef enum fe_transmit_mode {
	 TRANSMISSION_MODE_2K,
	 TRANSMISSION_MODE_8K,
	 TRANSMISSION_MODE_AUTO
 } fe_transmit_mode_t;
 typedef enum fe_bandwidth {
	 BANDWIDTH_8_MHZ,
	 BANDWIDTH_7_MHZ,
	 BANDWIDTH_6_MHZ,
	 BANDWIDTH_AUTO
 } fe_bandwidth_t;
 typedef enum fe_guard_interval {
	 GUARD_INTERVAL_1_32,
	 GUARD_INTERVAL_1_16,
	 GUARD_INTERVAL_1_8,
	 GUARD_INTERVAL_1_4,
	 GUARD_INTERVAL_AUTO
 } fe_guard_interval_t;
 typedef enum fe_hierarchy {
	 HIERARCHY_NONE,
	 HIERARCHY_1,
	 HIERARCHY_2,
	 HIERARCHY_4,
	 HIERARCHY_AUTO
 } fe_hierarchy_t;

frontend events

 struct dvb_frontend_event {
	 fe_status_t status;
	 struct dvb_frontend_parameters parameters;
 };