Gensys USB 2.0 Video Camera  "PC Camera4"
=========================================

*	Note : The Genesys USB 2.0 video camera driver for GL860 is currently being developed
*	on Linux. This driver can do damages.
*	Use this driver only if you know what you are doing.
----------------------
<	Note : Le pilote pour les webcam USB 2.0 Genesys avec le chip gl860 est développé 
<	sous Linux. Ce pilote peut causer des dommages.
<	N'utilisez ce pilote que si vous savez ce que vous faites.

*******************************************************************************************
*                 WHEN YOU CHANGE THE IMAGE SIZE FROM >=1280x960 TO LOWER,                *
*                           THERE IS A RISK OF SYSTEM FREEZE                              *
*									maybe it is resolved, once again... 									*
*		----------------------																					*
<	         EN CAS DE PASSAGE D'UNE TAILLE >=1280X960 À UNE TAILLE PLUS BASSE,            *
<                           IL Y A UN RISQUE DE GEL DU SYSTÈME.                           *
<								c'est peut-être (encore une fois...)  résolu								*
*******************************************************************************************


Table of contents :

1. Requirements
2. Compilation
3. Test experimental
4. Installation
5. Usage
6. Status of project
7. Debug & developpment
8. Licence
9. Thanks / Remerciements
---------------------------------------------------------------------------------------------------

1. Requirements

	Kernel 2.6.18 or higher

---------------------------------------------------------------------------------------------------

2. Compilation

*	No "./configure" or "make" !
*	Type "./install" and choose your version according to your laptop.
*
*	It seems that there's a driver for each laptop model.
*	This is why there's several declinations of that driver for this model.
*	The "ms" (MalmoStoso) is for Asus Z37E, S37E laptop
*  The "a" is for barebones, Asus S37S and Asus Z37sp.
*  The "c" is for Asus C90s.
*  The "sim" (Simon) is for Medion laptops
*
*	The driver is compiled against the kernel you are using. 
*	In case of kernel change, you have to make a new compilation and installation of the driver.
	----------------------
<	Pas de "./configure" ou de "make" !
<	Taper "./install" et choisir sa version de pilote selon le modèle de portable.
<
<	Il semble bien qu'il y ait un pilote par modèle de portable.
<	C'est la raison pour laquelle il y a plusieurs versions de pilote pour ce modèle.
<	La seule version en fonction connue est la "ms" (MalmoStoso )avec un Asus Z37E.
<
<	Le pilote est compilé par rapport au noyau présentement utilisé.
<	En cas de changement de version, vous devez recompiler le pilote et refaire son installation.

---------------------------------------------------------------------------------------------------

3. Test experimental

To test the driver with the V4L v1 :

$ xsane 		[Choisir "couleur" dans les options de xsane]
				[Choose "color" in the xsane options]

$ camorama -D --width=640 --height=480			[map mode]
$ camorama -D -R --width=640 --height=480		[read mode] 

*	NE MARCHE PAS AVEC VLC 0.8.6
<	DON'T WORK WITH VLC 0.8.6 ( vlc v4l:// :v4l-vdev="/dev/video0" )


To test the driver with the V4L v2 :

$ xawtv

$ ekiga		*	in the configuration assistant, choose V4L2 driver
 				<	Paramétrer l'utilisation de V4L2 dans l'assistant de configuration

$ amsn		*	Set up "Hue" to 0 and "Colour" to the max in the video settings
				<	Mettre "Tonalité" à 0 et "Couleur" au max dans les réglages vidéos

$ mplayer tv:// -tv driver=v4l2:width=640:height=480:fps=10:outfmt=rgb24:device=/dev/video0
				*	"fps" value isn't managed by the driver
				*  To take screenshot, add "vf-add=screenshot" to the ~/.mplayer/conf file, just type "s" to grab the image (Thx Hulkie).
				<	la valeur de "fps" n'est pas gérée par le pilote

$ mencoder tv:// -tv driver=v4l2:width=640:height=480:fps=10:outfmt=rgb24:device=/dev/video0 -nosound -ovc lavc -o out.avi

---------------------------------------------------------------------------------------------------

4. Installation

*	Run "./install" and choose your version when you are prompted for that.
*	If you have a F191, there will be no prompt as there is only one driver.
*	The driver is install as a kenrel module.
*
*	Add  gl860  at the end of  /etc/modules   (or the file with modules to add at boottime)
*	Restart the computer
*	Verify the module is loaded with:  lsmod | grep gl860
*	If OK the webcam is ready
	----------------------
<	Lancer "./install" et choisissez votre version de pilote. 
<	Si vous avez un F191, il n'y a pas de choix car il n'y a qu'un seul pilote.
<	Le pilote est installé comme un module du noyau.
<
<	Ajouter  gl860  à la fin de  /etc/modules  (ou le fichier avec les modules à charger au boot)
<	Redémarrer l'ordinateur
<	Vérifier la présence du module chargé avec :  lsmod | grep gl860
<	Si c'est bon, la webcam est prête à l'utilisation
---------------------------------------------------------------------------------------------------

5. Usage

	5.1 Options booléennes "hflip", "vflip" et "freq50" du module
 
		The Genesys module waits the options "hflip", "vflip" and "freq50" (values are 0 or 1):
		$ modprobe gl860 hflip=0 vflip=1

		hflip=1 => effet de miroir horizontal
		vflip=1 => effet de miroir vertical
		freq50=1 => alimentation en 50Hz		/	 freq50=0 => en 60Hz

		By default, the "hflip" and "vflip" are set to '0', "freq50" à '1'.


	5.2 Options "srclum", "colour", "brightness", "saturation", "nettete", "contrej"
 
 		F191 (NOT WITH 0503) :
		srclum=0 / 0x7F00 / 0xFF00   ["Normal light" / "Low light" / "Back light"]
		colour=0 0x3300 0x6600 0x9900 0xCC00 0xFF00  [normal / N&B (BW) / sépia / négatif / autre (other) I / autre II]
		brightness=0 0x2400 0x4800 0x6D00 0x9100 0xB600 0xDA00 0xFF00 (luminosité) [min ... max]
		saturation=0 0x2400 0x4800 0x6D00 0x9100 0xB600 0xDA00 0xFF00 [min ... max]
		nettete=0 0x2A00 0x5500 0x7F00 0xAA00 0xD400 0xFF00 (sharpness) [min ... max]
		contrej=0 / 0x7F00 / 0xFF00   [Contre-jour (backlight)]

		By default, the value of these options is 0 / 0 / 0 / 0xFF00 / 0xFF00 / 0.

		0503 :
		Values range from 0 to 0xFF00.

	5.3 Usage of the options

		$ modprobe gl860 saturation=0xFF00 colour=0


	5.4 Use the "sysfs"

*		In the directory : /sys/class/video4linux/videoX (by example video0), you
*		can read and write some parameters :
	   $ cat hflip
   	$ echo 0 > hflip
	   $ echo "0x7F00" > saturation
*		You can list the parameters :
		$ ls

*		To display informations about driver :
	   $ cat informations

---------------------------------------------------------------------------------------------------

6. Status

	The kernel module is currently being developped.
	The 05e3:f191 model is quite well supported, the 05e3:0503 is to test and develop

	The driver supports several webcam models :
	- 0x05E3:0xF191

	To increase the support, I need some help... Or somebody gives me the webcam !

---------------------------------------------------------------------------------------------------

7. Debug & developpment

	7.1. 'lsusb' output

	   ol@portabol[root@Dahlia driver]$ lsusb
		Bus 002 Device 001: ID 0000:0000  
		Bus 001 Device 007: ID 0b05:1712 ASUSTek Computer, Inc. 
		Bus 001 Device 006: ID 046d:c019 Logitech, Inc. 
		Bus 001 Device 001: ID 0000:0000  
		Bus 006 Device 005: ID 05e3:f191 Genesys Logic, Inc.			<== webcam 
		Bus 006 Device 004: ID 0bda:0116 Realtek Semiconductor Corp. 
		Bus 006 Device 001: ID 0000:0000  
		Bus 005 Device 001: ID 0000:0000  
		Bus 003 Device 001: ID 0000:0000  
		Bus 004 Device 001: ID 0000:0000  

		lsusb -d 05e3:f191 -vvv > lsusb.txt

 7.2. USB logs from Windows

*	Download SniffUSB at http://www.pcausa.com/Utilities/UsbSnoop/default.htm .
*	There is 3 USB logs useful :
*	- Log 1 : when you plug your webcam. 
*	- Log 2 : when you run any tools to see your webcam (with the default settings). 
*				Start the log, start a webcam viewer, wait for the apparition of an image, 
*				stop the viewer, stop the log. We log the driver while asking for images, 
*				receiving the video stream and stopping the stream.
*	- Log 3 : when you change parameters of your webcam
	----------------------
<	Télécharger SniffUSB sur http://www.pcausa.com/Utilities/UsbSnoop/default.htm .
<
<	Il y a 3 types de capture intéressants pour faire progresser le développement d'un pilote :
<
<	1. la connexion de la caméra USB. Pour une caméra intégrée dans un portable, désactiver 
<		la caméra dans "Gestion des périphériques" de Windows. ARRÊTER (et non redémarrer) le portable, 
<		attendre quelques secondes, démarrer le portable, capturer, réactiver la caméra dans la 
<		"Gestion des périphériques", attendre quelques secondes, arrêter la capture.
<		[capture de l'initialisation de la caméra]
<
<	2. l'utilisation de la webcam : démarrer la capture, lancer l'outil de visionnage de la caméra, 
<		attendre qu'une image apparaisse, arrêter le logiciel de visionnage et arrêter la capture.
<		[capture de la demande d'images, de la transmission d'images et de l'arrêt des images]
<
<	3. la changement de paramètres. Démarrer le visionnage de la caméra, ATTENDRE 4-5 SECONDES, 
<		démarrer la capture, changer UN paramètre en l'arrêtant sur plusieurs valeurs, arrêter la capture.
<		Associer au fichier de la capture la description du paramètre modifié : 
<						nom, valeur par défaut, valeur(s) testée(s) et plage de valeurs. 
<		* Pour tester un booléen (case à cocher) : décocher, capturer, cocher, décocher, arrêter la capture.
<		* Pour tester qqch avec N(<17) positions possibles (boutons radio ou curseur) : 
<		  se mettre sur la position 2, démarrer la capture, aller sur la position 1, temps d'arrêt, position 2, 
<		  temps d'arrêt, ..., position N, arrêter la capture.
<		* Pour tester qqch avec N(>=17) positions (curseur) : se mettre pas loin du début, 
<		  démarrer la capture, aller d'un coup au début, se déplacer jusqu'à une autre valeur, noter cette valeur, 
<		  se déplacer à un autre endroit et noter la nouvelle valeur, le faire encore 
<		  une fois, aller à la fin, arrêter la capture.
<
<	Pour simplifier le développement des fonctionnalités de la webcam, cette archive contient 
<	la source d'un programme nommé "relog" (relog.c, compiler avec "g++ relog.c -o relog"). 
<	L'utilisation de "relog" sur un log donne au moins deux fichiers : 
<		$ relog unFichier.log
<		Il en résulte "unFichier.loglog", "unFichier.log.c" plus éventuellement des images 
<		s'il y en a dans le log de la capture.
<	Joindre le fichier en ".c" en y écrivant à son début les informations citées plus haut à propos 
<	du paramètre manipulé. Mon email est dans relog.c. Pour faire encore mieux, utiliser plutôt :
<		$ relog unFichier.log machin
<	si c'est une capture avec changement du paramètre "machin".

 7.3. USB logs from Linux
*   Use the kernel module usbmon (enable option debugfs in the kernel)

 7.4. Enable module traces
*	You can enable : CONFIG_GL860_DEBUG and CONFIG_GL860_DEBUG_STREAM
	----------------------
<	Activer : CONFIG_GL860_DEBUG et/ou CONFIG_GL860_DEBUG_STREAM

---------------------------------------------------------------------------------------------------

8. Licence

	The kernel module is distributed under the licence GPL.

---------------------------------------------------------------------------------------------------

9. Thanks/Remerciements

*	Many thanks to Daniel Drake for his try to make a driver and his explanation for the USB logs. 
*  Many thanks to loggers : Daniel, Simon, Almighurt, Malmostoso, Tricid, Iceman, Fret_saw, Hulkie
*    and all testers.
*	Thanks also to Nicolas Vivien for the driver his Syntek webcam driver basis.
*	Thanks to Dr Malmostoso for his help.
	----------------------
<	Merci à Daniel Drake pour son début de pilote et ses explications sur la capture USB. 
<  Merci à ceux qui ont fait des captures : Daniel, Simon, Almighurt, Malmostoso, Tricid, 
<    Iceman, Fret_saw, Hulkie et tous les testeurs.
<	Merci également à Nicolas Vivien pour sa base de pilote avec son pilote pour la Syntek.
<  Enfin  merci au Docteur Malmostoso pour son aide à gérer ce projet.
