<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>qcwebcam - QuickCam-based webcam program for fhttpd</TITLE>
</HEAD>
<BODY>
<H1><CODE>qcwebcam</CODE> - QuickCam-based webcam program for fhttpd</H1>
<BLOCKQUOTE>
<B>Version 0.3.2</B>, <I>beta release</I>
by Alex Belits, <A HREF="mailto:abelits@phobos.illtel.denver.co.us">abelits@phobos.illtel.denver.co.us</A>.
</BLOCKQUOTE>
<H1>Disclamer</H1>
<DL>
<DD>
Author is not affiliated with <A HREF="http://www.connectix.com">Connectix Corporation</A>, Connectix
Corporation does not support or approve this software.
<BR></DD>
<DD>
All copyright notices and disclaimers in sources and documentations
are valid and assumed to be known by the user.
<BR></DD>
</DL>
<HR>
<DL>
<DT>Functionality:
<DD>
<UL>
<LI>JPEG still image by HTTP request.
<LI>Netscape MIME server-push video stream of JPEG images.
<LI>Local configuration by <CODE>/usr/local/etc/qcam.conf</CODE> and <CODE>/usr/local/etc/qcwebcam.<B><cameraname></B></CODE> files.
<LI>Remote configuration by HTML form.
</UL>
</DD>
<DT>Hardware supported:
<DD>
<UL>
<LI>Connectix B&W QuickCam for PC.
<LI>Connectix Color QuickCam for PC.
<LI>on unidirectional or bidirectional parallel ports.
</UL>
</DD>
<DT>Operating systems supported:
<DD>
<UL>
<LI>Linux.
<LI>FreeBSD.
</UL>
</DD>
<DT>Software required:
<DD>
<UL>
<LI><A HREF="http://phobos.illtel.denver.co.us/pub/qcread/README.html">cqc/qcread library</A> version 0.3 or later.
<LI><A HREF="ftp://ftp.uu.net/graphics/jpeg/">JPEG library</A> release 6a or later.
<LI><A HREF="http://phobos.illtel.denver.co.us/pub/fhttpd/">fhttpd FTP/HTTP
server</A> version 0.3.2 or later.
</UL>
</DD>
<DT>Copyright and license:
<DD>
<UL>
<LI>Berkeley-style, freeware.
</UL>
</DD>
</DL>
<P>
<H1>Description</H1>
<CODE>qcwebcam</CODE> is a webcam program written as a server process for
fhttpd HTTP server. It utilizes <A HREF="http://phobos.illtel.denver.co.us/pub/fhttpd/www/processes.html">user processes interface</A> which differs from CGI,
FastCGI or module interfaces used in other servers. <CODE>qcwebcam</CODE> does
not work as an additional HTTP server by itself, all data is sent through main
HTTP server which can be located on the same or different host. All camera
hardware handling, image preparation and user interface is done by
<CODE>qcwebcam</CODE> while buffering, HTTP protocol and security is handled
by HTTP server. Flow control (actually dropping frames for slow connections)
is done by <CODE>qcwebcam</CODE> using fhttpd flow control messages that are
part of protocol.
<P>
<CODE>qcwebcam</CODE> supports multiple clients at a time without creating
additional processes for every user by itself or HTTP server, although since
HTTP protocol is used, data is sent to every client individually.
<P>
Currently only Linux and FreeBSD versions exists, although the program
should work on other unices where fhttpd and cqc/qcread library will be ported.
No ports to non-unixlike systems are planned.
<P>
<CODE>qcwebcam</CODE> is used on constantly-running wbcam page at
<A HREF="http://phobos.illtel.denver.co.us/qcam-frame?update=serverpush">http://phobos.illtel.denver.co.us/qcam-frame?update=serverpush</A>;. It's 486dx2-80 box with 32M of RAM,
connected through 28.8kbs modem line.
<H1><A NAME="changes-0.3.2">Changes in version 0.3.2</A></H1>
<DL><DT>Bugfixes
<DD>
<DL>
<DT>Memory leak in self-updating frame support</DT>
<DD>
Every time parameters of the camera were changed without changing image
geometry (including changes made by auto-brightness) while some client was
connected with server-push image frame update enabled, response descriptor
structure was created and not deleted.
<DT>Server-push parameters updates</DT>
<DD>
If some client was connected with server-push image frame or control page
update, and its connection was too slow to receive all updates, it will not be notified about last change that happened while its buffer still was full even
after it will clear the buffer by receiving all preceding updates sent to it.
Now after the buffer is cleaned, and some updates are still not sent to the
client, last update is sent to synchronize that client's status.
<BR><BR></DD>
</DL>
</DD>
<DT>User interface changes</DT>
<DD>
<UL>
<LI>Link colors on the control page changed.
<LI>"Reload" button added to the control page.
</UL>
</DD>
</DL>
<H1><A NAME="changes-0.3.1">Changes in version 0.3.1</A></H1>
<DL><DT>Bugfix
<DD>Auto-brightness was able to set unusable value 255</DD>
</DL>
<H1><A NAME="changes-0.3">Changes in version 0.3</A></H1>
<DL>
<DT>Auto-brightness
<DD>Addidional keyword in <CODE>/usr/local/etc/qcwebcam.<B><programname></B></CODE>:
<BR><BR>
<DL>
<DT><CODE>autobrightness <B><value></B></CODE>
<DD>enables auto-brightness mode - brightness value is constantly
adjusted to keep brightness of the image around the
<CODE><B><value></B></CODE>. Default value is 128.
<BR><BR></DD>
</DL>
<BR><BR></DD>
<DT>"<CODE>-frame</CODE>" URL
<DD>
Base URL with "<CODE>-frame</CODE>" appended to it is mapped to the HTML with
<CODE><IMG></CODE> tag for the image. "<CODE>update=serverpush</CODE>"
parameter enables both server-push update of the HTML and server-push for
image in it.
<BR><BR></DD>
<DT>Color balance and priority controls added
<DD>
<BR><BR></DD>
<DT>Idle load decreased
<DD>When no clients are connected, frames are not taken or, if auto-brightness
is enabled, one frame is taken per minute.
<BR><BR></DD>
<DT>Auto-reset after camera hardware failures
<DD>
<BR><BR></DD>
<DT>Controls for parameters, not supported by the camera type detected, are
not shown
<DD>
<BR><BR></DD>
<DT>User interface improvements
<DD>Control page changed to include Netscape-specific and Javascript controls
while remaining compatible with standard HTML.
<BR><BR></DD>
</DL>
<H1><A NAME="changes-0.2">Changes in version 0.2</A></H1>
<DL>
<DT>URLs changes
<DD>URLs now can be configured, and "<CODE>img=jpeg</CODE>" parameter is
removed. Configuration form has the same URL as the image with
"<CODE>-config</CODE>" appended to the name (not parameters).
"<CODE>update=serverpush</CODE>" parameter remained the same. To accomodate
two different URLs for camera configuration and image fhttpd configuration file
<STRONG>SHOULD</STRONG> contain "<CODE>*</CODE>" appended to the base URL in
application definition. This change allows to set different access
restrictions for configuration and image URLs.
<BR><BR></DD>
<DT>Bugfixes in "never should happen" errors handling
<DD>
<BR><BR></DD>
<DT><CODE>/usr/local/etc/qcwebcam.<B><programname></B></CODE> configuration files support.
<DD>File <CODE>/usr/local/etc/qcwebcam.<B><programname></B></CODE>
(default is <CODE>/usr/local/etc/qcwebcam.qcwebcam</CODE>) may contain the
following keywords:
<BR><BR>
<DL>
<DT><CODE>url <B><custom-url></B></CODE>
<DD><CODE><B><custom-url></B></CODE> is the base URL for the camera.
(<STRONG>SHOULD</STRONG> be the same as defined in HTTP server configuration)
<BR><BR></DD>
<DT><CODE>camera <B><cameraname></B></CODE>
<DD><CODE><B><cameraname></B></CODE> is the camera name in
<CODE>/usr/local/etc/qcam.conf</CODE> file.
<BR><BR></DD>
<DT><CODE>framerate <B><fps></B></CODE>
<DD>
<CODE><B><fps></B></CODE> is the frame rate (should be between 0.001 and
100 to be accepted, but values >1 are impractical).
</DD>
</DL>
<BR><BR></DD>
<DT>User interface fixes
<DD>
<UL>
<LI>Fixed "lockup" on brightness value 255 (after setting this value qcwebcam
was unable to change it from the form).
<LI>In <CODE>qcwebcam</CODE> 0.1 if invalid value was entered in
non-self-updating form, and driver detected/fixed it, next form contained
entered, not fixed value. Now only values, checked by camera driver are
returned in non-self-updating form. Self-updating forms first are returned
with entered value, then updated with corrected values if entered values were
invalid.
<LI>Minor cleanups.
</UL>
<BR><BR></DD>
</DL>
<H1>Installing <CODE>qcwebcam</CODE></H1>
<H2>Compiling <CODE>qcwebcam</CODE></H2> To install <CODE>qcwebcam</CODE> on the host, already running fhttpd, with installed fhttpd and qcread sources, unpack <CODE>qcwebcam-0.3.2.tar.gz</CODE> file and compile source with <CODE>make</CODE>. You may need to edit <CODE>Makefile</CODE> if locations of libraries and include files differ from ones defined there - default ones are set for qcread, fhttpd and qcwebcam unpacked into directories under the same base directory.
<H2>Configuring <CODE>qcwebcam</CODE> as an application for fhttpd</H2>
<H3>Locally running process</H3>
Add line specifying <CODE>qcwebcam</CODE> as an application into
<CODE>/etc/fhttpd.conf</CODE> file:
<PRE>
Application qcam - root 1 64 /home/ftp/qcam* /usr/local/camera/bin/qcwebcam
</PRE>
where <CODE>/usr/local/camera/bin/qcwebcam</CODE> is the location of qcwebcam
binary, <CODE>/home/ftp/qcam</CODE> is the path resulted from URL-to-filename
translation on the server ("<CODE>*</CODE>" is added to match
"<CODE>/home/ftp/qcam-config</CODE>" pathname for configuration form and
"<CODE>/home/ftp/qcam-frame</CODE>" pathname for image "frame"),
<CODE>qcam</CODE> is the application name. 64 is the
limit of requests number in a queue, and 1 is the number of processes
allowed - it <STRONG>SHOULD</STRONG> be 1 because only one process can access
camera at a time. <CODE>root</CODE> is the user, whose userid will be used to
run <CODE>qcwebcam</CODE> - it <STRONG>SHOULD</STRONG> be root because
accessing parallel ports in this manner and setting proirity for process
requires that. "<CODE>Application</CODE>" line should be placed before the
default "<CODE>Application</CODE>" line that contains "<CODE>*</CODE>" as
the pathmask - otherwise the default application will override it.
<P>
<H3>Remotely running process</H3>
Add line specifying <CODE>qcwebcam</CODE> as an application into
<CODE>/etc/fhttpd.conf</CODE> file:
<PRE>
Application qcam - qcamuser 1 64 /home/ftp/qcam*
</PRE>
where <CODE>qcamuser</CODE> is the local username used by remotely running
<CODE>qcwebcam</CODE> to login into fhttpd, all other parameters are the same
as for local process.
<P>
On the remote host where <CODE>qcwebcam</CODE> will be running add into <CODE>/usr/local/etc/httpprocrc</CODE> file (or make one, it
should be owned by root and has permissions 600):
<PRE>
application qcam
user qcamuser
host hostname
password (wr$ql8^
port 8000
</PRE>
where <CODE>qcam</CODE> is the application name, <CODE>qcamuser</CODE> is the
user on the host <CODE>hostname</CODE>, where fhttpd is running, and
<CODE>(wr$ql8^</CODE> is the password of that user on that host (use something
as non-human-readable as this but <STRONG>DON'T</STRONG> use this password).
8000 is the port where fhttpd is accepting user processes logins.
<P>
<H2>Configuring <CODE>qcwebcam</CODE></H2>
Write configuration in <CODE>/usr/local/etc/qcam.conf</CODE> (see
<A HREF="http://phobos.illtel.denver.co.us/pub/qcread/README.html">cqc/qcread
documentation</A>). File
<CODE>/usr/local/etc/qwebcam.<B><programname></B></CODE> (where
<CODE><B><programname></B></CODE> is the basename of
<CODE>qcwebcam</CODE> executable, so by default it is
"<CODE>/usr/local/etc/qwebcam.qcwebcam</CODE>") can have additional options for
the camera (see "<A HREF="changes-0.2">Changes in version 0.2</A>" and
"<A HREF="changes-0.3">Changes in version 0.3</A>" sections).
<P>
Restart fhttpd by <CODE>kill -HUP</CODE> its proces.
<P>
If <CODE>qcwebcam</CODE> should run locally, fhttpd will start it, and if it
should be running on remote host, start it as root using the command line
<PRE>
qcwebcam qcam
</PRE>
where <CODE>qcam</CODE> is the application name.
<P>
<H1>Using <CODE>qcwebcam</CODE></H1>
Resulting URLs for <CODE>qcwebcam</CODE> will be:
<DL>
<DT>"<CODE>http://hostname/qcam-config</CODE>;"
<DD>configuration form.</DD>
<DT>"<CODE>http://hostname/qcam-frame</CODE>;"
<DD>HTML with <CODE><IMG></CODE> tag for the image.</DD>
<DT>"<CODE>http://hostname/qcam</CODE>;"
<DD>JPEG image.</DD>
<DT>"<CODE>http://hostname/qcam-config?update=serverpush</CODE>;"
<DD>configuration form with self-update through server push (Netscape).</DD>
<DT>"<CODE>http://hostname/qcam-frame?update=serverpush</CODE>;"
<DD>HTML with <CODE><IMG></CODE> tag for the JPEG image stream with self-update through server push (Netscape).</DD>
<DT>"<CODE>http://hostname/qcam?update=serverpush</CODE>;"
<DD>JPEG image stream through server push (Netscape).</DD>
</DL>
<P>
where <CODE>http://hostname/qcam</CODE>; is the base URL that maps into path
defined in the configuration.
<P>
Since Netscape requires that server-push image streams should be referenced
through <IMG> tags with height and width predefined, you will need
to use "<CODE>-frame</CODE>" URL or a file with somethung like:
<PRE>
<IMG SRC="/qcam?update=serverpush" WIDTH=320 HEIGHT=240>
</PRE>
for server-push streams.
<P>
<H1>Distribution site</H1>
<DL>
<DT>FTP:
<DD>
<A HREF="ftp://phobos.illtel.denver.co.us/pub/qcwebcam/">phobos.illtel.denver.co.us:/pub/qcwebcam </A>
</DD>
<DT>HTTP:
<DD>
<A HREF="http://phobos.illtel.denver.co.us/pub/qcwebcam/">http://phobos.illtel.denver.co.us/pub/qcwebcam/</A>;
</DD>
</DL>
</BODY>
</HTML>