BLINKENLIGHTS PROXY
-------------------
version 0.97 date 2005-12-29
Copyright (C) 2003-2005 Stefan Schuermans <1stein@schuermans.info>
Copyleft: GNU public license - http://www.gnu.org/copyleft/gpl.html

Blinkenlights Proxy is some kind of advanced proxy server for the blinkenlights
protocols. It supports the blinkenlights protocol (BLP) used at the original
Blinkenlights inststallation at the Haus des Lehrers in Berlin and the extended
version (EBLP) that has got additional support for greyscale values.
The microcontroller unit frame protocol (MCUF) that was used at the
Blinkenlights Arcade installation at the Bibliotheque Nationale de France in
Paris is also supported.
Besides these three static protocols, their dynamic extensions done by "Cavac"
<cavac@grumpfzotz.org> are a main feature of Blinkenlights Proxy (bl_proxy).
The specification of the Protocols is now maintained by the BlinkenArea
(http://www.blinkenarea.org/) and the specification can be found in the Wiki
under BlinkenProtocols (see sidebar).



CONTROLLING BLINKENLIGHTS PROXY
-------------------------------

There are three possibilities to control bl_proxy.
The first is some kind of configuration file that is read in and processed
at program start. The output of the commands is then written to an output
file. By default, the input and output files are named as the program binary
with the added extension ".in" and ".out", but this can be changed by the
command line option "-i" and "-o".

The second possibility to control bl_proxy is via a TCP connection at run-time.
On startup bl_proxy will listen on the TCP port "IN 127.0.0.1 2323" for
control connections. This port can be changed by the parameters "-f" for the
address familily, "-a" for the listen address and "-p" for the listen port.
All connections made to this port (e.g. via telnet or netcat) will allow to
execute b_proxy commands interactively.

The last possibility is to enable the local command input with the command
line option "-l". In this mode, bl_proxy will accept commands on standard
input. If this local session is closed by "end", "exit" or "quit", bl_proxy
will terminate.

If local command input is not active, bl_proxy kann be shut down by pressing
Ctrl-C at its standard input or by sending it a HUP, INT or TERM signal (e.g.
using "killall bl_proxy").



COMMAND LINE OPTIONS
--------------------

Here is an overview of the syntax of bl_proxy, which is also displayed when
called with invalid parameters (e.g. with "-h" or "--help"):

syntax: "./bl_proxy [options]"

options: "-i <input-file>" (defaults to "./bl_proxy.in")
         "-o <output-file>" (defaults to "./bl_proxy.out")
         "-f <listen-address-family>" ("in" or "in6", defaults to "in")
         "-a <listen-address>" (defaults to "127.0.0.1")
         "-p <listen-port>" (defaults to "4200")
         "-l" enable local command input
         "-q" quiet mode



BASIC CONCEPT
-------------

The basic concept of bl_proxy is best explained by describing the internal
structures.

INPUT PORTS

To receive Blinkenlights streams, there are so-called input ports. Each is
assigned a UDP address and port on which frames are recevied.

Every input port can have a number of dynamic sources to request streams
from other sources dynamically. By specifying the address and the port of
the source, bl_proxy will send request messages periodically to the source.
If the source complies with the dynamic blinkenlights protocol extensions
it will send a stream to the source address of the requests, i.e. the input
port.

If a frame is received on an input port, it will be passed along the input
filter list associated with every input port. This input filter lists
contains some rules that filter the frames by their source address, their
protocol and their format. Depending on these parameters, the frame can be
assigned to a single or multiple output ports or be ignored.

OUTPUT PORTS

The output ports are used to send outgoing streams. Every output port is
assigned an UDP address and port from which frames are sent.

Every output port has got a static destination list. In this list, the
addresses and ports of the static destinations are stored. Every frame
of the active stream is sent to every destination in this list.

There is also an output filter list for every output port. Similar to the
input filter list, incoming requests of dynamic destinations are filtered
and either accepted as new dynamic destination or rejected.
The accpeted dynamic destinations are stored in the dynamic destination
list of the output port until they request the end of the stream or a
timeout occurs. The current stream is also sent to the dynamic destinations
as it is to the static destinations.

An output port can optionally be assigned a timeout value. Whenever there
is a stream (see below) being output on this port and this tream does not
carry a frame for this time, the last frame is automatically repeated by
bl_proxy. This is done to show the receiver that this tream is still alive
and just the frame did not change.
If the timeout value is not specified, no automatical repetition of frames
is done.

STREAMS

There is still a problem left unclear until here. What happens if multiple
streams are forwarded to a single output port? One could expect that the
stream A sends a frame which is submitted to all output ports and then
stream B sends a frame of another movie which is also submitted to all
output ports. This would result in two ore more movies being mixed with each
other. But, of course, this is not done by bl_proxy.

Every frame that matches an input filter and is submitted to an output port
it is assigned a priority value and a timeout by the input filter rule.
Thus, every stream stored in the stream list of an output port has got a
priority value and a timeout.
If a stream with a higher priority arrives at the output port, the new stream
becomes the current one and is sent to the destinations. If a timeout of
a stream occurs (i.e. if no more frames of this stream were received for
the timeout time) it is removed from the stream list. If it was the current
stream, the stream with the highest priority still in the stream list will
become the active one.



FURTHER INFORMATION
-------------------

Further information is available by using the "help" command in a bl_proxy
session. "help" will display the commands with a short description while
"help <command>" will display a complete description of the command.



DISCLAIMER
----------

This software was tested to work well in all test cases. But because of the
limited number of blinkenlights sources and destinations it is possible that
there do exists problems and bugs within bl_proxy.
The author will take no responsibility for any damage, data loss or ... caused
by the program.
But, of course, you are welcome to send in bug reports, questions or feature
requests to 1stein <1stein@schuermans.info>. Your email might not be answered
immediately but most probybly it will be answered as soon as some free time
becomes available.



EOF
