Table of Contents
FE_GET_PROPERTY/FE_SET_PROPERTY
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.
For historical reasons, frontend types are named by the type of modulation used in transmission. The fontend types are given by fe_type_t type, defined as:
Table 9.1. Frontend types
fe_type | Description | DTV_DELIVERY_SYSTEM equivalent type |
---|---|---|
FE_QPSK | For DVB-S standard | SYS_DVBS |
FE_QAM | For DVB-C annex A standard | SYS_DVBC_ANNEX_A |
FE_OFDM | For DVB-T standard | SYS_DVBT |
FE_ATSC | For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US. | SYS_ATSC (terrestrial) or SYS_DVBC_ANNEX_B (cable) |
Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're supported via the new FE_GET_PROPERTY/FE_GET_SET_PROPERTY ioctl's, using the DTV_DELIVERY_SYSTEM parameter.
The usage of this field is deprecated, as it doesn't report all supported standards, and will provide an incomplete information for frontends that support multiple delivery systems. Please use DTV_ENUM_DELSYS instead.
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_MULTISTREAM = 0x4000000, 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;
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; };
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 ⋆/ };
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 ⋆/
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;
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;
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;
Several functions of the frontend device use the fe_status data type defined by
typedef enum fe_status { FE_HAS_SIGNAL = 0x01, FE_HAS_CARRIER = 0x02, FE_HAS_VITERBI = 0x04, FE_HAS_SYNC = 0x08, FE_HAS_LOCK = 0x10, FE_TIMEDOUT = 0x20, FE_REINIT = 0x40, } fe_status_t;
to indicate the current state and/or state changes of the frontend hardware:
FE_HAS_SIGNAL | The frontend has found something above the noise level |
FE_HAS_CARRIER | The frontend has found a DVB signal |
FE_HAS_VITERBI | The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable |
FE_HAS_SYNC | Synchronization bytes was found |
FE_HAS_LOCK | The DVB were locked and everything is working |
FE_TIMEDOUT | no lock within the last about 2 seconds |
FE_REINIT | The frontend was reinitialized, application is recommended to reset DiSEqC, tone and parameters |
The kind of parameters passed to the frontend device for tuning depend on the kind of hardware you are using.
The struct dvb_frontend_parameters
uses an
union with specific per-system parameters. However, as newer delivery systems
required more data, the structure size weren't enough to fit, and just
extending its size would break the existing applications. So, those parameters
were replaced by the usage of
FE_GET_PROPERTY/FE_SET_PROPERTY
ioctl's. The
new API is flexible enough to add new parameters to existing delivery systems,
and to add newer delivery systems.
So, newer applications should use
FE_GET_PROPERTY/FE_SET_PROPERTY
instead, in
order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
DVB-C2, ISDB, etc.
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; struct dvb_vsb_parameters vsb; } u; };
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.
For satellite QPSK frontends you have to use the dvb_qpsk_parameters
structure:
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 dvb_qam_parameters
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) ⋆/ };
ATSC frontends are supported by the dvb_vsb_parameters
structure:
struct dvb_vsb_parameters { fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ };
DVB-T frontends are supported by the dvb_ofdm_parameters
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; };
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 used on
struct dvb_qpsk_parameters
and
struct dvb_qam_parameters
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, FEC_3_5, FEC_9_10, } 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, e. g. for
struct dvb_qpsk_parameters
,
struct dvb_qam_parameters
and
struct dvb_qam_parameters
,
it needs 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, VSB_8, VSB_16, PSK_8, APSK_16, APSK_32, DQPSK, } fe_modulation_t;
typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, TRANSMISSION_MODE_AUTO, TRANSMISSION_MODE_4K, TRANSMISSION_MODE_1K, TRANSMISSION_MODE_16K, TRANSMISSION_MODE_32K, } fe_transmit_mode_t;
typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, BANDWIDTH_7_MHZ, BANDWIDTH_6_MHZ, BANDWIDTH_AUTO, BANDWIDTH_5_MHZ, BANDWIDTH_10_MHZ, BANDWIDTH_1_712_MHZ, } 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, GUARD_INTERVAL_1_128, GUARD_INTERVAL_19_128, GUARD_INTERVAL_19_256, } fe_guard_interval_t;