DVB TOOLS
=========

This is a series of tools written to help testing and working with DVB,
using its latest V5 API. The tools can also work with the DVBv3 API.

The current tools are:

dvb-fe-tool - a simple test application, that reads from the frontend.
	      it also allows to change the default delivery system.
	      In the future, it may be used to change any property
	      via command line.

dvb-format-convert - converts from zap and scan "initial-tuning-data-file"
	      into the new format defined to work with DVBv5;

dvbv5-scan - a DVBv5 scan tool;

dvbv5-zap - a DVBv5 zap tool. It allow to tune into a DVB channel, and
	    to watch to a DVB service (e. g. receiving the video and audio
	    streams, via another application using the dvr device).

Each application code is very small, as most of the code are on some
generic code that will become a library in the future.

CONTENTS OF THE TREE
====================

parse_string.c/parse_string.h: MPEG-TS string decoder with charset translator

Used to decode NIT/SDT service name, network provider and provider name.
It parses the charsets according with the DVB specs, converting them into
UTF-8 (or other charset), using iconv library.

descriptors.c/descriptors.h:  MPEG-TS descriptors parser

The code there is generig enough to decode the MPEG-TS descriptors,
with the DVB and other Digital TV extensions.

libscan.c/libscan/h: DVBv5 scanning library

This library is used to retrieve DVB information from the MPEG TS
headers, discovering the services associated to each DVB channel or
transponder. The services information is the basic info that most
DVB tools need to tune into a channel.

dvb-file.c/dvb-file.h: DVB file read/write library.

Allows parsing a DVB file (legacy or not) and to write data into a
DVB file (new format only).

dvb-fe.c/dvb-fe.h: DVB frontend library.

Allows talking with a DVB frontend via DVBv5 or DVBv3 API.

dvb-zap-format.c/dvb-legacy-channel-format.c:

Contains the data structures required in order to read from the legacy
formats (zap or scan "initial-tuning-data-file").

dvb_frontend.h: DVBv5 frontend API.

This is just a copy of the newest linux/dvb/frontend.h header.
I opted to keep a copy there, in order to allow working with the tools
without needing to copy the latest header into /usr/include.

dvb-v5.h/dvb-v5-std.h:

Ancillary files linked into dvb-fe code, used to parse DVB tables. The
dvbv5.h is generated by a small perl util, from the DVB FE API file.

dvb-demux.c/dvb-demux.h: DVB demux library.

Used by the dvbv5-zap utility.

dvb-fe-tool.c, dvb-format-convert.c, dvbv5-zap.c, dvbv5-scan.c: tools code.

Basically, parses the options from userspace and calls the other code
to do what was requested by the user.

CHANNEL/SERVICE FILE FORMAT
===========================

Instead of having two different files, one for services, and another for
channels/transponders, I opted to use just one format for both. The
format is:

[channel]
key1=value1
key2=value2
key3=value3
...
keyn=valuen


lines with # are discarted by the parsers. Also, whitespaces/tabs before
the keys and before/after the equal sign.

Be careful: whitespace in the middle of the value are not discarded.

A typical service would be like:

[TV Brasil HD]
	VCHANNEL = 2.2
	SERVICE_ID = 16160
	VIDEO_PID = 770
	AUDIO_PID = 514 614
	FREQUENCY = 479142857
	MODULATION = QAM/AUTO
	BANDWIDTH_HZ = 6000000
	INVERSION = AUTO
	CODE_RATE_HP = AUTO
	CODE_RATE_LP = NONE
	GUARD_INTERVAL = AUTO
	TRANSMISSION_MODE = AUTO
	HIERARCHY = NONE
	ISDBT_LAYER_ENABLED = 7
	ISDBT_PARTIAL_RECEPTION = 0
	ISDBT_SOUND_BROADCASTING = 0
	ISDBT_SB_SUBCHANNEL_ID = 0
	ISDBT_SB_SEGMENT_IDX = 0
	ISDBT_SB_SEGMENT_COUNT = 0
	ISDBT_LAYERA_FEC = AUTO
	ISDBT_LAYERA_MODULATION = QAM/AUTO
	ISDBT_LAYERA_SEGMENT_COUNT = 0
	ISDBT_LAYERA_TIME_INTERLEAVING = 0
	ISDBT_LAYERB_FEC = AUTO
	ISDBT_LAYERB_MODULATION = QAM/AUTO
	ISDBT_LAYERB_SEGMENT_COUNT = 0
	ISDBT_LAYERB_TIME_INTERLEAVING = 0
	ISDBT_LAYERC_FEC = AUTO
	ISDBT_LAYERC_MODULATION = QAM/AUTO
	ISDBT_LAYERC_SEGMENT_COUNT = 0
	ISDBT_LAYERC_TIME_INTERLEAVING = 0
	DELIVERY_SYSTEM = ISDBT

Just the channel description for it would be:

[CHANNEL]
	FREQUENCY = 479142857
	MODULATION = QAM/AUTO
	BANDWIDTH_HZ = 6000000
	INVERSION = AUTO
	CODE_RATE_HP = AUTO
	CODE_RATE_LP = NONE
	GUARD_INTERVAL = AUTO
	TRANSMISSION_MODE = AUTO
	HIERARCHY = NONE
	ISDBT_LAYER_ENABLED = 7
	ISDBT_PARTIAL_RECEPTION = 0
	ISDBT_SOUND_BROADCASTING = 0
	ISDBT_SB_SUBCHANNEL_ID = 0
	ISDBT_SB_SEGMENT_IDX = 0
	ISDBT_SB_SEGMENT_COUNT = 0
	ISDBT_LAYERA_FEC = AUTO
	ISDBT_LAYERA_MODULATION = QAM/AUTO
	ISDBT_LAYERA_SEGMENT_COUNT = 0
	ISDBT_LAYERA_TIME_INTERLEAVING = 0
	ISDBT_LAYERB_FEC = AUTO
	ISDBT_LAYERB_MODULATION = QAM/AUTO
	ISDBT_LAYERB_SEGMENT_COUNT = 0
	ISDBT_LAYERB_TIME_INTERLEAVING = 0
	ISDBT_LAYERC_FEC = AUTO
	ISDBT_LAYERC_MODULATION = QAM/AUTO
	ISDBT_LAYERC_SEGMENT_COUNT = 0
	ISDBT_LAYERC_TIME_INTERLEAVING = 0
	DELIVERY_SYSTEM = ISDBT

USAGE WITH SATELLITE DELIVERY SYSTEMS
=====================================

The dvbv5-zap and dvbv5-scan can now work with DVB-S/DVB-S2
systems. A new code, yet to be tested, has the following
features:
	- support for common types of LNBf;
	- DISEqC switching (SMATV);
	- Bandstacking;
	- Unicable/SRC.

Additional parameters for satellite delivery systems are needed:

	- l <lnbf>

selects the LNBf type. Using an invalid value like "help" shows
what's currently supported.

	- S <sat_number>

Selects satellite number, between 0 to 3, for SMATV, or between
0 to 15 for SCR/Unicable. The highest bit is used to select between
position A and position B.

If not specified, disables DISEqC and Unicable/SCR.

For SMATV, this actually changes the DISEqC "option"
and "position" parameter. According with the specs, for
position B, tone should be off, and tone burst should
be miniA.

	-U <freq_bpf>

Selects the band-pass filter frequency used by the Unicable device. Currently,
only the mandatory DISEqC commands were implemented. It means that
the library is currently not able to use bi-directional DISEqC commands
to detect the available frequencies.

	-W <extra time in ms>

The DISEqC logic will wait for 15 ms. If this parameter is
specified, it will add  the extra time to the 15ms delay.

For LNBf devices that use bandstacking (e. g. the ones that use
different LO frequrencies for V and H polarization), the code will
always use 13 Volts and will disable tone/tone burst.

Currently, C-Band multi and DishPro bandstacking LNBf's are
supported.

Tests are welcome!

Note: Currently, the implementation uses DISEqC only uses the
command [E0 10 38 xx], where xx selects the DISEqC input.
Additional support could be needed for more sophisticated
arrangements.

CURRENT ISSUES
==============

The dvb-fe-tool and the dvb-format-convert are generic enough to work
with all delivery systems. However, the other two tools need to do
some diferent things, depending on the delivery system, as other
tables and descriptors may be needed.

Currently, the tools were tested with DVB-C, ISDB-T, DVB-T and
DVB-T2.

If someone wants to patch the code to improve the tool, the descriptors
parser is inside descriptors.c file. The scan code that uses it is
at libscan.c. Finally, the data structure used by the scan parsing
is at libscan.h. The procedure is basicallt to add a new data field inside
the libscan.h structures, and then change the descriptors.c file
to fill it.

The main structure is this one:

struct dvb_descriptors {
	int verbose;

	struct pat_table pat_table;
	struct nit_table nit_table;
	struct sdt_table sdt_table;

	/* Used by descriptors to know where to update a PMT/Service/TS */
	unsigned cur_pmt;
	unsigned cur_service;
	unsigned cur_ts;
};

While parsing each table, the current item being parsed is pointed by
one of those unsigned values: cur_pmt, cur_service, cur_ts. Use this
to fill the data structure.

The dvb-file will likely need changes too, in order to write the
parsed information inside the channels file.

Patches are welcome!

Regards,
Mauro Carvalho Chehab
2012-January-15