| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
|
| 3 |
.. _frontend-properties: |
| 4 |
|
| 5 |
************** |
| 6 |
Property types |
| 7 |
************** |
| 8 |
|
| 9 |
Tuning into a Digital TV physical channel and starting decoding it |
| 10 |
requires changing a set of parameters, in order to control the tuner, |
| 11 |
the demodulator, the Linear Low-noise Amplifier (LNA) and to set the |
| 12 |
antenna subsystem via Satellite Equipment Control - SEC (on satellite |
| 13 |
systems). The actual parameters are specific to each particular digital |
| 14 |
TV standards, and may change as the digital TV specs evolves. |
| 15 |
|
| 16 |
In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a |
| 17 |
union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and |
| 18 |
ATSC delivery systems grouped there. The problem is that, as the second |
| 19 |
generation standards appeared, the size of such union was not big |
| 20 |
enough to group the structs that would be required for those new |
| 21 |
standards. Also, extending it would break userspace. |
| 22 |
|
| 23 |
So, the legacy union/struct based approach was deprecated, in favor |
| 24 |
of a properties set approach. On such approach, |
| 25 |
:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used |
| 26 |
to setup the frontend and read its status. |
| 27 |
|
| 28 |
The actual action is determined by a set of dtv_property cmd/data pairs. |
| 29 |
With one single ioctl, is possible to get/set up to 64 properties. |
| 30 |
|
| 31 |
This section describes the new and recommended way to set the frontend, |
| 32 |
with supports all digital TV delivery systems. |
| 33 |
|
| 34 |
.. note:: |
| 35 |
|
| 36 |
1. On Linux DVB API version 3, setting a frontend was done via |
| 37 |
struct :c:type:`dvb_frontend_parameters`. |
| 38 |
|
| 39 |
2. Don't use DVB API version 3 calls on hardware with supports |
| 40 |
newer standards. Such API provides no support or a very limited |
| 41 |
support to new standards and/or new hardware. |
| 42 |
|
| 43 |
3. Nowadays, most frontends support multiple delivery systems. |
| 44 |
Only with DVB API version 5 calls it is possible to switch between |
| 45 |
the multiple delivery systems supported by a frontend. |
| 46 |
|
| 47 |
4. DVB API version 5 is also called *S2API*, as the first |
| 48 |
new standard added to it was DVB-S2. |
| 49 |
|
| 50 |
**Example**: in order to set the hardware to tune into a DVB-C channel |
| 51 |
at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217 |
| 52 |
Mbauds, those properties should be sent to |
| 53 |
:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl: |
| 54 |
|
| 55 |
:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A |
| 56 |
|
| 57 |
:ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000 |
| 58 |
|
| 59 |
:ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256 |
| 60 |
|
| 61 |
:ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO |
| 62 |
|
| 63 |
:ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000 |
| 64 |
|
| 65 |
:ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4 |
| 66 |
|
| 67 |
:ref:`DTV_TUNE <DTV-TUNE>` |
| 68 |
|
| 69 |
The code that would that would do the above is show in |
| 70 |
:ref:`dtv-prop-example`. |
| 71 |
|
| 72 |
.. code-block:: c |
| 73 |
:caption: Example: Setting digital TV frontend properties |
| 74 |
:name: dtv-prop-example |
| 75 |
|
| 76 |
#include <stdio.h> |
| 77 |
#include <fcntl.h> |
| 78 |
#include <sys/ioctl.h> |
| 79 |
#include <linux/dvb/frontend.h> |
| 80 |
|
| 81 |
static struct dtv_property props[] = { |
| 82 |
{ .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, |
| 83 |
{ .cmd = DTV_FREQUENCY, .u.data = 651000000 }, |
| 84 |
{ .cmd = DTV_MODULATION, .u.data = QAM_256 }, |
| 85 |
{ .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, |
| 86 |
{ .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, |
| 87 |
{ .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, |
| 88 |
{ .cmd = DTV_TUNE } |
| 89 |
}; |
| 90 |
|
| 91 |
static struct dtv_properties dtv_prop = { |
| 92 |
.num = 6, .props = props |
| 93 |
}; |
| 94 |
|
| 95 |
int main(void) |
| 96 |
{ |
| 97 |
int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); |
| 98 |
|
| 99 |
if (!fd) { |
| 100 |
perror ("open"); |
| 101 |
return -1; |
| 102 |
} |
| 103 |
if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { |
| 104 |
perror("ioctl"); |
| 105 |
return -1; |
| 106 |
} |
| 107 |
printf("Frontend set\\n"); |
| 108 |
return 0; |
| 109 |
} |
| 110 |
|
| 111 |
.. attention:: While it is possible to directly call the Kernel code like the |
| 112 |
above example, it is strongly recommended to use |
| 113 |
`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it |
| 114 |
provides abstraction to work with the supported digital TV standards and |
| 115 |
provides methods for usual operations like program scanning and to |
| 116 |
read/write channel descriptor files. |
| 117 |
|
| 118 |
.. toctree:: |
| 119 |
:maxdepth: 1 |
| 120 |
|
| 121 |
fe_property_parameters |
| 122 |
frontend-stat-properties |
| 123 |
frontend-property-terrestrial-systems |
| 124 |
frontend-property-cable-systems |
| 125 |
frontend-property-satellite-systems |
| 126 |
frontend-header |