1.. SPDX-License-Identifier: GPL-2.0
2
3==============================
4Using the Digital TV Framework
5==============================
6
7Introduction
8~~~~~~~~~~~~
9
10One significant difference between Digital TV and Analogue TV that the
11unwary (like myself) should consider is that, although the component
12structure of DVB-T cards are substantially similar to Analogue TV cards,
13they function in substantially different ways.
14
15The purpose of an Analogue TV is to receive and display an Analogue
16Television signal. An Analogue TV signal (otherwise known as composite
17video) is an analogue encoding of a sequence of image frames (25 frames
18per second in Europe) rasterised using an interlacing technique.
19Interlacing takes two fields to represent one frame. Therefore, an
20Analogue TV card for a PC has the following purpose:
21
22* Tune the receiver to receive a broadcast signal
23* demodulate the broadcast signal
24* demultiplex the analogue video signal and analogue audio
25  signal.
26
27  .. note::
28
29     some countries employ a digital audio signal
30     embedded within the modulated composite analogue signal -
31     using NICAM signaling.)
32
33* digitize the analogue video signal and make the resulting datastream
34  available to the data bus.
35
36The digital datastream from an Analogue TV card is generated by
37circuitry on the card and is often presented uncompressed. For a PAL TV
38signal encoded at a resolution of 768x576 24-bit color pixels over 25
39frames per second - a fair amount of data is generated and must be
40processed by the PC before it can be displayed on the video monitor
41screen. Some Analogue TV cards for PCs have onboard MPEG2 encoders which
42permit the raw digital data stream to be presented to the PC in an
43encoded and compressed form - similar to the form that is used in
44Digital TV.
45
46The purpose of a simple budget digital TV card (DVB-T,C or S) is to
47simply:
48
49* Tune the received to receive a broadcast signal. * Extract the encoded
50  digital datastream from the broadcast signal.
51* Make the encoded digital datastream (MPEG2) available to the data bus.
52
53The significant difference between the two is that the tuner on the
54analogue TV card spits out an Analogue signal, whereas the tuner on the
55digital TV card spits out a compressed encoded digital datastream. As
56the signal is already digitised, it is trivial to pass this datastream
57to the PC databus with minimal additional processing and then extract
58the digital video and audio datastreams passing them to the appropriate
59software or hardware for decoding and viewing.
60
61Getting the card going
62~~~~~~~~~~~~~~~~~~~~~~
63
64The Device Driver API for DVB under Linux will the following
65device nodes via the devfs filesystem:
66
67* /dev/dvb/adapter0/demux0
68* /dev/dvb/adapter0/dvr0
69* /dev/dvb/adapter0/frontend0
70
71The ``/dev/dvb/adapter0/dvr0`` device node is used to read the MPEG2
72Data Stream and the ``/dev/dvb/adapter0/frontend0`` device node is used
73to tune the frontend tuner module. The ``/dev/dvb/adapter0/demux0`` is
74used to control what programs will be received.
75
76Depending on the card's feature set, the Device Driver API could also
77expose other device nodes:
78
79* /dev/dvb/adapter0/ca0
80* /dev/dvb/adapter0/audio0
81* /dev/dvb/adapter0/net0
82* /dev/dvb/adapter0/osd0
83* /dev/dvb/adapter0/video0
84
85The ``/dev/dvb/adapter0/ca0`` is used to decode encrypted channels. The
86other device nodes are found only on devices that use the av7110
87driver, with is now obsoleted, together with the extra API whose such
88devices use.
89
90Receiving a digital TV channel
91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93This section attempts to explain how it works and how this affects the
94configuration of a Digital TV card.
95
96On this example, we're considering tuning into DVB-T channels in
97Australia, at the Melbourne region.
98
99The frequencies broadcast by Mount Dandenong transmitters are,
100currently:
101
102Table 1. Transponder Frequencies Mount Dandenong, Vic, Aus.
103
104===========	===========
105Broadcaster	Frequency
106===========	===========
107Seven		177.500 Mhz
108SBS		184.500 Mhz
109Nine		191.625 Mhz
110Ten		219.500 Mhz
111ABC		226.500 Mhz
112Channel 31	557.625 Mhz
113===========	===========
114
115The digital TV Scan utilities (like dvbv5-scan) have use a set of
116compiled-in defaults for various countries and regions. Those are
117currently provided as a separate package, called dtv-scan-tables. It's
118git tree is located at LinuxTV.org:
119
120    https://git.linuxtv.org/dtv-scan-tables.git/
121
122If none of the tables there suit, you can specify a data file on the
123command line which contains the transponder frequencies. Here is a
124sample file for the above channel transponders, in the old "channel"
125format::
126
127	# Data file for DVB scan program
128	#
129	# C Frequency SymbolRate FEC QAM
130	# S Frequency Polarisation SymbolRate FEC
131	# T Frequency Bandwidth FEC FEC2 QAM Mode Guard Hier
132
133	T 177500000 7MHz AUTO AUTO QAM64 8k 1/16 NONE
134	T 184500000 7MHz AUTO AUTO QAM64 8k 1/8 NONE
135	T 191625000 7MHz AUTO AUTO QAM64 8k 1/16 NONE
136	T 219500000 7MHz AUTO AUTO QAM64 8k 1/16 NONE
137	T 226500000 7MHz AUTO AUTO QAM64 8k 1/16 NONE
138	T 557625000 7MHz AUTO AUTO QPSK 8k 1/16 NONE
139
140Nowadays, we prefer to use a newer format, with is more verbose and easier
141to understand. With the new format, the "Seven" channel transponder's
142data is represented by::
143
144	[Seven]
145		DELIVERY_SYSTEM = DVBT
146		FREQUENCY = 177500000
147		BANDWIDTH_HZ = 7000000
148		CODE_RATE_HP = AUTO
149		CODE_RATE_LP = AUTO
150		MODULATION = QAM/64
151		TRANSMISSION_MODE = 8K
152		GUARD_INTERVAL = 1/16
153		HIERARCHY = NONE
154		INVERSION = AUTO
155
156For an updated version of the complete table, please see:
157
158    https://git.linuxtv.org/dtv-scan-tables.git/tree/dvb-t/au-Melbourne
159
160When the Digital TV scanning utility runs, it will output a file
161containing the information for all the audio and video programs that
162exists into each channel's transponders which the card's frontend can
163lock onto. (i.e. any whose signal is strong enough at your antenna).
164
165Here's the output of the dvbv5 tools from a channel scan took from
166Melburne::
167
168    [ABC HDTV]
169	    SERVICE_ID = 560
170	    VIDEO_PID = 2307
171	    AUDIO_PID = 0
172	    DELIVERY_SYSTEM = DVBT
173	    FREQUENCY = 226500000
174	    INVERSION = OFF
175	    BANDWIDTH_HZ = 7000000
176	    CODE_RATE_HP = 3/4
177	    CODE_RATE_LP = 3/4
178	    MODULATION = QAM/64
179	    TRANSMISSION_MODE = 8K
180	    GUARD_INTERVAL = 1/16
181	    HIERARCHY = NONE
182
183    [ABC TV Melbourne]
184	    SERVICE_ID = 561
185	    VIDEO_PID = 512
186	    AUDIO_PID = 650
187	    DELIVERY_SYSTEM = DVBT
188	    FREQUENCY = 226500000
189	    INVERSION = OFF
190	    BANDWIDTH_HZ = 7000000
191	    CODE_RATE_HP = 3/4
192	    CODE_RATE_LP = 3/4
193	    MODULATION = QAM/64
194	    TRANSMISSION_MODE = 8K
195	    GUARD_INTERVAL = 1/16
196	    HIERARCHY = NONE
197
198    [ABC TV 2]
199	    SERVICE_ID = 562
200	    VIDEO_PID = 512
201	    AUDIO_PID = 650
202	    DELIVERY_SYSTEM = DVBT
203	    FREQUENCY = 226500000
204	    INVERSION = OFF
205	    BANDWIDTH_HZ = 7000000
206	    CODE_RATE_HP = 3/4
207	    CODE_RATE_LP = 3/4
208	    MODULATION = QAM/64
209	    TRANSMISSION_MODE = 8K
210	    GUARD_INTERVAL = 1/16
211	    HIERARCHY = NONE
212
213    [ABC TV 3]
214	    SERVICE_ID = 563
215	    VIDEO_PID = 512
216	    AUDIO_PID = 650
217	    DELIVERY_SYSTEM = DVBT
218	    FREQUENCY = 226500000
219	    INVERSION = OFF
220	    BANDWIDTH_HZ = 7000000
221	    CODE_RATE_HP = 3/4
222	    CODE_RATE_LP = 3/4
223	    MODULATION = QAM/64
224	    TRANSMISSION_MODE = 8K
225	    GUARD_INTERVAL = 1/16
226	    HIERARCHY = NONE
227
228    [ABC TV 4]
229	    SERVICE_ID = 564
230	    VIDEO_PID = 512
231	    AUDIO_PID = 650
232	    DELIVERY_SYSTEM = DVBT
233	    FREQUENCY = 226500000
234	    INVERSION = OFF
235	    BANDWIDTH_HZ = 7000000
236	    CODE_RATE_HP = 3/4
237	    CODE_RATE_LP = 3/4
238	    MODULATION = QAM/64
239	    TRANSMISSION_MODE = 8K
240	    GUARD_INTERVAL = 1/16
241	    HIERARCHY = NONE
242
243    [ABC DiG Radio]
244	    SERVICE_ID = 566
245	    VIDEO_PID = 0
246	    AUDIO_PID = 2311
247	    DELIVERY_SYSTEM = DVBT
248	    FREQUENCY = 226500000
249	    INVERSION = OFF
250	    BANDWIDTH_HZ = 7000000
251	    CODE_RATE_HP = 3/4
252	    CODE_RATE_LP = 3/4
253	    MODULATION = QAM/64
254	    TRANSMISSION_MODE = 8K
255	    GUARD_INTERVAL = 1/16
256	    HIERARCHY = NONE
257
258    [TEN Digital]
259	    SERVICE_ID = 1585
260	    VIDEO_PID = 512
261	    AUDIO_PID = 650
262	    DELIVERY_SYSTEM = DVBT
263	    FREQUENCY = 219500000
264	    INVERSION = OFF
265	    BANDWIDTH_HZ = 7000000
266	    CODE_RATE_HP = 3/4
267	    CODE_RATE_LP = 1/2
268	    MODULATION = QAM/64
269	    TRANSMISSION_MODE = 8K
270	    GUARD_INTERVAL = 1/16
271	    HIERARCHY = NONE
272
273    [TEN Digital 1]
274	    SERVICE_ID = 1586
275	    VIDEO_PID = 512
276	    AUDIO_PID = 650
277	    DELIVERY_SYSTEM = DVBT
278	    FREQUENCY = 219500000
279	    INVERSION = OFF
280	    BANDWIDTH_HZ = 7000000
281	    CODE_RATE_HP = 3/4
282	    CODE_RATE_LP = 1/2
283	    MODULATION = QAM/64
284	    TRANSMISSION_MODE = 8K
285	    GUARD_INTERVAL = 1/16
286	    HIERARCHY = NONE
287
288    [TEN Digital 2]
289	    SERVICE_ID = 1587
290	    VIDEO_PID = 512
291	    AUDIO_PID = 650
292	    DELIVERY_SYSTEM = DVBT
293	    FREQUENCY = 219500000
294	    INVERSION = OFF
295	    BANDWIDTH_HZ = 7000000
296	    CODE_RATE_HP = 3/4
297	    CODE_RATE_LP = 1/2
298	    MODULATION = QAM/64
299	    TRANSMISSION_MODE = 8K
300	    GUARD_INTERVAL = 1/16
301	    HIERARCHY = NONE
302
303    [TEN Digital 3]
304	    SERVICE_ID = 1588
305	    VIDEO_PID = 512
306	    AUDIO_PID = 650
307	    DELIVERY_SYSTEM = DVBT
308	    FREQUENCY = 219500000
309	    INVERSION = OFF
310	    BANDWIDTH_HZ = 7000000
311	    CODE_RATE_HP = 3/4
312	    CODE_RATE_LP = 1/2
313	    MODULATION = QAM/64
314	    TRANSMISSION_MODE = 8K
315	    GUARD_INTERVAL = 1/16
316	    HIERARCHY = NONE
317
318    [TEN Digital]
319	    SERVICE_ID = 1589
320	    VIDEO_PID = 512
321	    AUDIO_PID = 650
322	    DELIVERY_SYSTEM = DVBT
323	    FREQUENCY = 219500000
324	    INVERSION = OFF
325	    BANDWIDTH_HZ = 7000000
326	    CODE_RATE_HP = 3/4
327	    CODE_RATE_LP = 1/2
328	    MODULATION = QAM/64
329	    TRANSMISSION_MODE = 8K
330	    GUARD_INTERVAL = 1/16
331	    HIERARCHY = NONE
332
333    [TEN Digital 4]
334	    SERVICE_ID = 1590
335	    VIDEO_PID = 512
336	    AUDIO_PID = 650
337	    DELIVERY_SYSTEM = DVBT
338	    FREQUENCY = 219500000
339	    INVERSION = OFF
340	    BANDWIDTH_HZ = 7000000
341	    CODE_RATE_HP = 3/4
342	    CODE_RATE_LP = 1/2
343	    MODULATION = QAM/64
344	    TRANSMISSION_MODE = 8K
345	    GUARD_INTERVAL = 1/16
346	    HIERARCHY = NONE
347
348    [TEN Digital]
349	    SERVICE_ID = 1591
350	    VIDEO_PID = 512
351	    AUDIO_PID = 650
352	    DELIVERY_SYSTEM = DVBT
353	    FREQUENCY = 219500000
354	    INVERSION = OFF
355	    BANDWIDTH_HZ = 7000000
356	    CODE_RATE_HP = 3/4
357	    CODE_RATE_LP = 1/2
358	    MODULATION = QAM/64
359	    TRANSMISSION_MODE = 8K
360	    GUARD_INTERVAL = 1/16
361	    HIERARCHY = NONE
362
363    [TEN HD]
364	    SERVICE_ID = 1592
365	    VIDEO_PID = 514
366	    AUDIO_PID = 0
367	    DELIVERY_SYSTEM = DVBT
368	    FREQUENCY = 219500000
369	    INVERSION = OFF
370	    BANDWIDTH_HZ = 7000000
371	    CODE_RATE_HP = 3/4
372	    CODE_RATE_LP = 1/2
373	    MODULATION = QAM/64
374	    TRANSMISSION_MODE = 8K
375	    GUARD_INTERVAL = 1/16
376	    HIERARCHY = NONE
377
378    [TEN Digital]
379	    SERVICE_ID = 1593
380	    VIDEO_PID = 512
381	    AUDIO_PID = 650
382	    DELIVERY_SYSTEM = DVBT
383	    FREQUENCY = 219500000
384	    INVERSION = OFF
385	    BANDWIDTH_HZ = 7000000
386	    CODE_RATE_HP = 3/4
387	    CODE_RATE_LP = 1/2
388	    MODULATION = QAM/64
389	    TRANSMISSION_MODE = 8K
390	    GUARD_INTERVAL = 1/16
391	    HIERARCHY = NONE
392
393    [Nine Digital]
394	    SERVICE_ID = 1072
395	    VIDEO_PID = 513
396	    AUDIO_PID = 660
397	    DELIVERY_SYSTEM = DVBT
398	    FREQUENCY = 191625000
399	    INVERSION = OFF
400	    BANDWIDTH_HZ = 7000000
401	    CODE_RATE_HP = 3/4
402	    CODE_RATE_LP = 1/2
403	    MODULATION = QAM/64
404	    TRANSMISSION_MODE = 8K
405	    GUARD_INTERVAL = 1/16
406	    HIERARCHY = NONE
407
408    [Nine Digital HD]
409	    SERVICE_ID = 1073
410	    VIDEO_PID = 512
411	    AUDIO_PID = 0
412	    DELIVERY_SYSTEM = DVBT
413	    FREQUENCY = 191625000
414	    INVERSION = OFF
415	    BANDWIDTH_HZ = 7000000
416	    CODE_RATE_HP = 3/4
417	    CODE_RATE_LP = 1/2
418	    MODULATION = QAM/64
419	    TRANSMISSION_MODE = 8K
420	    GUARD_INTERVAL = 1/16
421	    HIERARCHY = NONE
422
423    [Nine Guide]
424	    SERVICE_ID = 1074
425	    VIDEO_PID = 514
426	    AUDIO_PID = 670
427	    DELIVERY_SYSTEM = DVBT
428	    FREQUENCY = 191625000
429	    INVERSION = OFF
430	    BANDWIDTH_HZ = 7000000
431	    CODE_RATE_HP = 3/4
432	    CODE_RATE_LP = 1/2
433	    MODULATION = QAM/64
434	    TRANSMISSION_MODE = 8K
435	    GUARD_INTERVAL = 1/16
436	    HIERARCHY = NONE
437
438    [7 Digital]
439	    SERVICE_ID = 1328
440	    VIDEO_PID = 769
441	    AUDIO_PID = 770
442	    DELIVERY_SYSTEM = DVBT
443	    FREQUENCY = 177500000
444	    INVERSION = OFF
445	    BANDWIDTH_HZ = 7000000
446	    CODE_RATE_HP = 2/3
447	    CODE_RATE_LP = 2/3
448	    MODULATION = QAM/64
449	    TRANSMISSION_MODE = 8K
450	    GUARD_INTERVAL = 1/8
451	    HIERARCHY = NONE
452
453    [7 Digital 1]
454	    SERVICE_ID = 1329
455	    VIDEO_PID = 769
456	    AUDIO_PID = 770
457	    DELIVERY_SYSTEM = DVBT
458	    FREQUENCY = 177500000
459	    INVERSION = OFF
460	    BANDWIDTH_HZ = 7000000
461	    CODE_RATE_HP = 2/3
462	    CODE_RATE_LP = 2/3
463	    MODULATION = QAM/64
464	    TRANSMISSION_MODE = 8K
465	    GUARD_INTERVAL = 1/8
466	    HIERARCHY = NONE
467
468    [7 Digital 2]
469	    SERVICE_ID = 1330
470	    VIDEO_PID = 769
471	    AUDIO_PID = 770
472	    DELIVERY_SYSTEM = DVBT
473	    FREQUENCY = 177500000
474	    INVERSION = OFF
475	    BANDWIDTH_HZ = 7000000
476	    CODE_RATE_HP = 2/3
477	    CODE_RATE_LP = 2/3
478	    MODULATION = QAM/64
479	    TRANSMISSION_MODE = 8K
480	    GUARD_INTERVAL = 1/8
481	    HIERARCHY = NONE
482
483    [7 Digital 3]
484	    SERVICE_ID = 1331
485	    VIDEO_PID = 769
486	    AUDIO_PID = 770
487	    DELIVERY_SYSTEM = DVBT
488	    FREQUENCY = 177500000
489	    INVERSION = OFF
490	    BANDWIDTH_HZ = 7000000
491	    CODE_RATE_HP = 2/3
492	    CODE_RATE_LP = 2/3
493	    MODULATION = QAM/64
494	    TRANSMISSION_MODE = 8K
495	    GUARD_INTERVAL = 1/8
496	    HIERARCHY = NONE
497
498    [7 HD Digital]
499	    SERVICE_ID = 1332
500	    VIDEO_PID = 833
501	    AUDIO_PID = 834
502	    DELIVERY_SYSTEM = DVBT
503	    FREQUENCY = 177500000
504	    INVERSION = OFF
505	    BANDWIDTH_HZ = 7000000
506	    CODE_RATE_HP = 2/3
507	    CODE_RATE_LP = 2/3
508	    MODULATION = QAM/64
509	    TRANSMISSION_MODE = 8K
510	    GUARD_INTERVAL = 1/8
511	    HIERARCHY = NONE
512
513    [7 Program Guide]
514	    SERVICE_ID = 1334
515	    VIDEO_PID = 865
516	    AUDIO_PID = 866
517	    DELIVERY_SYSTEM = DVBT
518	    FREQUENCY = 177500000
519	    INVERSION = OFF
520	    BANDWIDTH_HZ = 7000000
521	    CODE_RATE_HP = 2/3
522	    CODE_RATE_LP = 2/3
523	    MODULATION = QAM/64
524	    TRANSMISSION_MODE = 8K
525	    GUARD_INTERVAL = 1/8
526	    HIERARCHY = NONE
527
528    [SBS HD]
529	    SERVICE_ID = 784
530	    VIDEO_PID = 102
531	    AUDIO_PID = 103
532	    DELIVERY_SYSTEM = DVBT
533	    FREQUENCY = 536500000
534	    INVERSION = OFF
535	    BANDWIDTH_HZ = 7000000
536	    CODE_RATE_HP = 2/3
537	    CODE_RATE_LP = 2/3
538	    MODULATION = QAM/64
539	    TRANSMISSION_MODE = 8K
540	    GUARD_INTERVAL = 1/8
541	    HIERARCHY = NONE
542
543    [SBS DIGITAL 1]
544	    SERVICE_ID = 785
545	    VIDEO_PID = 161
546	    AUDIO_PID = 81
547	    DELIVERY_SYSTEM = DVBT
548	    FREQUENCY = 536500000
549	    INVERSION = OFF
550	    BANDWIDTH_HZ = 7000000
551	    CODE_RATE_HP = 2/3
552	    CODE_RATE_LP = 2/3
553	    MODULATION = QAM/64
554	    TRANSMISSION_MODE = 8K
555	    GUARD_INTERVAL = 1/8
556	    HIERARCHY = NONE
557
558    [SBS DIGITAL 2]
559	    SERVICE_ID = 786
560	    VIDEO_PID = 162
561	    AUDIO_PID = 83
562	    DELIVERY_SYSTEM = DVBT
563	    FREQUENCY = 536500000
564	    INVERSION = OFF
565	    BANDWIDTH_HZ = 7000000
566	    CODE_RATE_HP = 2/3
567	    CODE_RATE_LP = 2/3
568	    MODULATION = QAM/64
569	    TRANSMISSION_MODE = 8K
570	    GUARD_INTERVAL = 1/8
571	    HIERARCHY = NONE
572
573    [SBS EPG]
574	    SERVICE_ID = 787
575	    VIDEO_PID = 163
576	    AUDIO_PID = 85
577	    DELIVERY_SYSTEM = DVBT
578	    FREQUENCY = 536500000
579	    INVERSION = OFF
580	    BANDWIDTH_HZ = 7000000
581	    CODE_RATE_HP = 2/3
582	    CODE_RATE_LP = 2/3
583	    MODULATION = QAM/64
584	    TRANSMISSION_MODE = 8K
585	    GUARD_INTERVAL = 1/8
586	    HIERARCHY = NONE
587
588    [SBS RADIO 1]
589	    SERVICE_ID = 798
590	    VIDEO_PID = 0
591	    AUDIO_PID = 201
592	    DELIVERY_SYSTEM = DVBT
593	    FREQUENCY = 536500000
594	    INVERSION = OFF
595	    BANDWIDTH_HZ = 7000000
596	    CODE_RATE_HP = 2/3
597	    CODE_RATE_LP = 2/3
598	    MODULATION = QAM/64
599	    TRANSMISSION_MODE = 8K
600	    GUARD_INTERVAL = 1/8
601	    HIERARCHY = NONE
602
603    [SBS RADIO 2]
604	    SERVICE_ID = 799
605	    VIDEO_PID = 0
606	    AUDIO_PID = 202
607	    DELIVERY_SYSTEM = DVBT
608	    FREQUENCY = 536500000
609	    INVERSION = OFF
610	    BANDWIDTH_HZ = 7000000
611	    CODE_RATE_HP = 2/3
612	    CODE_RATE_LP = 2/3
613	    MODULATION = QAM/64
614	    TRANSMISSION_MODE = 8K
615	    GUARD_INTERVAL = 1/8
616	    HIERARCHY = NONE
617