sms1xxx: A C repository from martymac

About this driver :
*******************

--
WARNING: This driver implements DVB API v3 only and should be considered
deprecated, you should probably use Webcamd (multimedia/webcamd) instead.
--

Sms1xxx is a native FreeBSD driver for Siano-based DVB-T USB devices.
It should work on any version of FreeBSD >= 8.0 (see older versions
for FreeBSD 7.x).

It is a port of linux' sms1xxx driver (see drivers/media/dvb/siano
in the Linux source tree), initially from Linux kernel v.2.6.27.

The following web page presents an initial version of the Linux driver :

http://linuxtv.org/wiki/index.php/TerraTec_Cinergy_Piranha

The FreeBSD driver has been successfully tested with two devices :

- Terratec Cinergy Piranha
- Hauppauge WinTV MiniStick (HD)

Other devices should work, just give a try (you will need to edit the
sms1xxx.c file and add new VIDs/PIDs to make your device detected).

The FreeBSD version of the driver is based on the great dvbusb driver
written by Raaf :

http://raaf.atspace.org/dvbusb

with a few modifications to the demuxer (fixing issues with clones'
management).

License / availability :
************************

The sms1xxx driver is released under the GPL v2.0 license.

It is available on http://contribs.martymac.org and in the
FreeBSD ports tree (multimedia/sms1xxx-kmod).

This file explains how to install the driver from sources.

Getting firmware files :
************************

Before using the driver, you have to get the official firmwares for your
hardware, unpack and move them to each firmwares/* subdirectory.

Each firmware will then be used to build a corresponding firmware module
that will have to be loaded with the main kernel module.

For your convenience, a 'distinfo' file is present in each firmware directory,
allowing you to check if your firmware files match the firmwares I used for
development.

* Terratec Cinergy Piranha :

For the Terratec Cinergy Piranha USB key, get the following file :

ftp://ftp.terratec.net/Receiver/Cinergy_Piranha/Update/Cinergy_Piranha_Drv_Vista_XP_3.09.02.00.exe

Unpack the 3 firmware files :

unzip -j Cinergy_Piranha_Drv_Vista_XP_3.09.02.00.exe \
Cinergy\ Piranha/BDA\ Driver\ 3.09.02.00/Windos\ XP\ \(32Bit\)/SMS100x_Dvbt.inp \
Cinergy\ Piranha/BDA\ Driver\ 3.09.02.00/Windos\ XP\ \(32Bit\)/SMS100x_Dvbh.inp \
Cinergy\ Piranha/BDA\ Driver\ 3.09.02.00/Windos\ XP\ \(32Bit\)/SMS100x_DabTdmb.inp

And move each file to its own directory :

mv SMS100x_Dvbt.inp firmwares/stellar_dvbt/stellar_dvbt.fw
mv SMS100x_Dvbh.inp firmwares/stellar_dvbh/stellar_dvbh.fw
mv SMS100x_DabTdmb.inp firmwares/stellar_dabtdmb/stellar_dabtdmb.fw

* Hauppauge WinTV MiniStick

Get the following file :

http://www.wintvcd.co.uk/drivers/WinTV-MiniStick_4_2_26_28027_WHQL.zip

Unpack the 2 firmware files :

unzip -j WinTV-MiniStick_4_2_26_28027_WHQL.zip \
driver17/hcw17dvb.1b0 \
driver17/hcw17isd.1b0

And move them to their own directories :

mv hcw17dvb.1b0 firmwares/novab0_dvbbda/novab0_dvbbda.fw
mv hcw17isd.1b0 firmwares/novab0_isdbtbda/novab0_isdbtbda.fw

Building and installing everything :
************************************

First, if you do not want to build every single firmware file,
you may want to change the SUBDIR variable in firmwares/Makefile
to remove firmwares you do not need.

Then, just do :

make && make install

The main kernel module (sms1xxx.ko) and additional firmware modules
will be built and installed to /boot/modules.

Loading and using the driver :
******************************

Run :
kldload <your firmware module(s)>
e.g. :
kldload stellar_dvbt.ko
kldload stellar_dvbh.ko
[...]
Depending on the mode(s) you wish to run.

Then, run :
kldload sms1xxx

Finally, it might be necessary to tune a few sysctls :
* hw.usb.sms1xxx.freq_offset: Global frequency offset (Hz)
This sysctl will apply a global offset each time a tuning is performed.
166000 is necessary for Paris (France). It may or may not be necessary to
change that value, depending on where you live and the kind of hardware
you use.
* hw.usb.sms1xxx.requested_mode: Requested mode
(0=DVB-T, 1=DVB-H, 2=DAB/T-DMB, 4=DVB-T/BDA, 5=ISDBT, 6=ISDBT/BDA)
This sysctl is the mode that will be requested when plugging the next device.
You must have loaded the corresponding firmware in the previous step.
Please note that currently, only DVB-T (mode 4) is supported (this is the
default mode).

Testing the driver :
********************

First, plug the device (or it won't work :p). You can have a look at
/var/log/messages and see what happens.

If your device is detected and the firmware successfully loaded, two
device nodes should appear :

/dev/dvb/adapter0/dvr0
/dev/dvb/adapter0/frontend0

They will be used by applications to interact with your device.

While using the device, you will also see other nodes appear and disappear :

/dev/dvb/adapter0/demux0.n

They are dynamically created and destroyed when you have successfully tuned
the device to a specific frequency and when a PID filter has been set.

Once everything works, you will have to scan for channels. See the following
paragraph to build the w_scan and the scan utilities.

(if nothing works, you can try to build the module using 'make debug' and
tune the 'debug' sysctl to set the desired log level).

Building applications :
***********************

The driver is provided with a few applications :
w_scan : searches for channels (initial or full search)
scan-dvb-apps : searches for channels (using an initial frequency list)
tzap-dvb-apps : tunes to a specific channel
dvbtools : various DVB tools (dvbstream, dvbtune, dvbdate)
rc5watch : displays IR codes sent by the remote controller (see below)

There is also a conf/ directory which contains my configuration files. They
are suitable for France (Paris) and need a freq_offset set to 166000.

To build an utility, go into its directory and use 'gmake'.

See apps/README for more details.

Using your device :
*******************

First, perform an initial search using w_scan. It will generate a file
containing frequencies airing on your location :

w_scan -x > xx-MyCity
(e.g. for me : w_scan -x > fr-Paris)

Then, scan for channels using the previous file and the scan utility :

scan xx-MyCity > channels.conf

channels.conf now contains a list of channels you can watch.

Then, tune the device to a specific channel :
tzap -rc channels.conf "MYCHANNEL"

Finally, you can view (or record) streamed data using the dvr0 device :
mplayer /dev/dvb/adapter0/dvr0
or :
dd if=/dev/dvb/adapter0/dvr0 of=mystream.ts

Other applications :
********************

* ffplay (multimedia/ffmpeg)

* xine (multimedia/xine) can be used to watch TV directly (without
having to use tzap) : xine 'dvb://MYCHANNEL'.

* vlc (multimedia/vlc) natively supports DVB : just check the V4L option
before building the port.

Then, you should be able to watch TV by launching it this way :

vlc dtv://frequency=562000000:bandwidth=8

or by selecting the "open capture device" entry in the "media' menu.

* mplayer (multimedia/mplayer) can also handle DVB devices.
Build the port with V4L support, then copy your channels.conf file to
/usr/local/etc/mplayer/. Now, launch Mplayer using the channel name
as URL, e.g. :

mplayer "dvb://ARTE"

IR (infrared) support :
***********************

If IR is supported by your device, an 'ir0' device will appear in your
DVB adapter's device directory (/dev/dvb/adapter0/ir0).

Reading this device will give you access to raw IR data received by the
adapter (use the provided remote control, if any).

If the IR module is sucessfully started, the 'ir_module_started' sysctl
of your device's node will also be set to 1.

For your convenience, an utility that decodes and prints received
events in a human-friendly format is available in the apps/rc5watch
directory.

Type 'make' to build it, then, once your device is plugged, run :

./rc5watch

Each received event will appear on stdout in the following form :

toggle:address:command

It is then possible to use this utility in a script that will perform
various actions given received key codes (see rc5exec.sh.sample).

It might also be possible to use the 'ir0' device with LIRC, but it has not
been tested. If you manage to make it work, please tell me :)

GPIO support :
**************

GPIO (General purpose Inpout Output) brings LEDs handling as well as LNA
(Low Noise Amplifier) support to some devices.

* If LEDs handling is supported by your device, LED colors will indicate
reception quality and device activity.

You can check if your device supports LEDs handling by buildind the driver
with debug support and check if the sysctl 'dev.sms1xxx.n.led_status' appears
once the device is plugged in. This sysctl can be used to test LEDs by setting
it to special values. See the sysctl's description for more details.

* If LNA handling is supported by your device, the sysctl 'dev.sms1xxx.n.use_lna'
will appear. Setting it to 1 will make the driver turn LNA on before each tuning
request. See the sysctl's description for more details.

martymac/sms1xxx