--- /dev/null
+<html>
+ <head>
+ <title>chiark ledctrl bot</title>
+ <link rev="made" href="mailto:ircop@chiark.greenend.org.uk">
+ </head>
+ <body>
+ <h1>chiark ledctrl bot</h1>
+
+The ledctrl bot exists to allow users to have activity on channels
+they're interested in reported on LEDs via the <a
+href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED control
+protocol</a>.
+
+<h2>Privacy</h2>
+
+ledctrl does not make any information about content of IRC sessions
+available to anyone, not even its operator (ijackson, acting as
+ircop). It does look for activity on the channels it sits on and
+report to its users whether there is activity, but the information
+made available is not very much.
+
+<p>
+
+It can watch preferentially for individual users, but this facility
+should not be used without the prior consent of the target. ledctrl
+will notify the target that they are being watched.
+
+<p>
+
+If you want to know who is being told information about IRC activity,
+say
+<pre>
+/msg ledctrl who
+</pre>
+and it will report something like this
+<pre>
+-ledctrl- monitoring #starcraft for ijackson:sc
+-ledctrl- monitoring #test for ijackson:#test
+-ledctrl- sending ijackson:sc to ijackson, davenant.relativity.greenend.org.uk:1447
+-ledctrl- sending ijackson:#test to ijackson, davenant.relativity.greenend.org.uk:1447
+</pre>
+In this example, the channels <code>sc</code> and <code>#test</code>
+are being monitored on behalf of ijackson, who has chosen to name the
+monitoring functions <code>ijackson:sc</code> and
+<code>ijackson:#test</code>. The results are being sent only to the
+LED server on port 1447 of davenant.relativity.greenend.org.uk:1447,
+also on behalf of ijackson.
+
+<h2>Usage</h2>
+
+If you want to use this facility:
+
+<ol>
+
+<li> Make sure that your LED server is operating properly, and that you
+can use <code>remoteleds</code> on chiark to manipulate the relevant LEDs.
+
+<li> If you're using a nonzero password (which is recommended, as
+otherwise any other chiark user could interfere with your LEDs), copy
+the <code>.led-client-pass</code> that you're using to
+<code>~/.userv/irc-ledcontrol-passwords</code> (taking care to make
+sure it's not world-readable).
+
+<li> Write the configuration file saying which channels to monitor and
+where to send the answers. Put it in
+<code>~/.userv/irc-ledcontrol-config</code>. See below for the file
+format.
+
+<li> Join <code>#ledctrl</code>. This is where the debug and
+diagnostic output goes. You should also look here if it seems not to
+be working at some later point. When you think everything is right, say
+<code>/msg ledctrl reload <var>username</var></code>
+where <var>username</var> is your own username. If all is well it
+should just say
+<samp><ledctrl> reloaded <var>username</var></samp>
+and shortly afterwards your LEDs should be set.
+
+<li> If you still can't get it to work, say
+<code>/msg ledctrl debug <var>username</var></code>
+and see if you can make any sense of the output. NB that this
+produces lots of output in the channel, which will disrupt other
+people's use of it, and cause ledctrl to become lagged, so please
+don't leave the debug enabled. It will turn itself off after a while
+anyway.
+
+<li> If you decide you don't want to use ledctrl any more, delete
+your config file and say <kbd>/msg ledctrl reload
+<var>username</var></kbd>, which will cause ledctrl to forget about
+your configuration (and any stored passwords).
+
+</ol>
+
+<h2>Configuration model</h2>
+
+The file <code>~/.userv/irc-ledcontrol-config</code> contains the
+configuration file for your ledctrl settings. If this file doesn't
+exist, ledctrl will assume you don't want it to run on your behalf.
+
+<p>
+
+The file may contain definitions of two kinds of objects:
+
+<dl>
+
+<dt>Monitors
+
+<dd>These are specifications of channels to monitor, activity
+timeouts, and nicks to ignore, etc. Each monitor at any particular
+time has a particular result state which depends only on its
+configuration and activity on the channel.
+
+<p>
+
+Monitors have names of the form
+<code><var>username</var>:<var>suffix</var></code> where suffix is
+chosen by the user who defines the monitor.
+
+<dt>devicesets
+
+<dd>These are LED groups; each deviceset must be tied to exactly one
+monitor; the configuration specifies a mapping from monitor result
+states to LED values.
+
+Devicesets are not explicitly named, but when ledctrl needs to refer
+to them it may do so by the username who defined them and the line
+number in their configuration, or sometimes by the destination host(s)
+and port(s) in the specified LED group.
+
+</dl>
+
+Note that you can refer in your configuration to another users'
+monitors. This allows you to share monitor configuration. There are
+two monitors provided as a general service by the system
+administration, currently via the user ijackson:
+
+<ul>
+<li><code>ijackson:#chiark</code>
+<li><code>ijackson:#starcraft</code>
+</ul>
+
+Consult <code>~ijackson/.userv/irc-ledcontrol-config</code> for exact
+details. To suggest changes to this configuration, consult
+ircop@chiark.
+
+<p>
+
+If you define a deviceset which refers to a nonexistent monitor, it
+will be silently ignored.
+
+<h2>Configuration syntax</h2>
+
+The configuration file is line-based. Leading and trailing whitespace
+on each line is ignored. Comment lines (starting with <code>#</code>)
+and blank lines are ignored. Lines (including comment lines) may be
+continued using <code>\</code>.
+
+<p>
+
+<h3>Configuration directives</h3>
+
+<dl>
+<dt>
+<code>monitor <var>monname</var> <var>#chan</var> [<var>#chan ...</var>]</code>
+<dd><p>
+Defines a monitor named <var>monname</var> which monitors the
+specified channel(s). <var>monname</var> must start with
+<code><var>username</var>:</code> where <var>username</var> is the
+username whose file the directive occurs in.
+
+<dt>
+<code>nick ignore [<var>glob-pattern</var> ...]</code>
+<dd><p>
+Defines a list of nick patterns to completely ignore. No activity on
+the part of nicks matching any of the patterns will have any effect.
+<p>
+Affects all monitors defined, until the next <code>nick ignore</code>.
+
+<dt>
+<code>nick nopresence [<var>glob-pattern</var> ...]</code>
+<dd><p>
+Defines a list of nick patterns to ignore when deciding whether anyone
+is present. If the affected nicks speak in channel they will still
+count.
+<p>
+Affects all monitors defined, until the next <code>nick nopresence</code>.
+
+<dt>
+<code>nick prefer [<var>glob-pattern</var> ...]</code>
+<dd><p>
+Defines a list of nick patterns to be extra interested in, when they
+talk on channel. See the <code>preftalk</code> and
+<code>preftalknow</code> monitor state conditions in the
+<code>leds</code> directive, below.
+
+<p>
+Affects all monitors defined, until the next <code>nick nopresence</code>.
+
+<p>
+
+<strong>Important</strong>: Use of this directive can amount to fairly
+intrusive monitoring of the activity of the affected nicks.
+<strong>Ask permission</strong> from the target before using this
+directive on a real person. ledctrl will inform the target of the
+surveillance.
+
+<dt>
+<code>times <var>talk-now-time</var> <var>talk-time</var></code>
+<dd><p>
+Specifies the times, in seconds, for which someone speaking in channel
+will satisfy the <code>talknow</code> and <code>talk</code>
+conditions, respectively. <var>talk-now-time</var> should be no more
+than <var>talk-time</var>.
+
+<p> Affects all monitors defined, until the next <code>times</code>.
+The initial values are 120 and 450.
+
+<dt>
+<code>leds <var>led-group</var> <var>monname</var> <var>state</var>=<var>value</var> ...</code>
+<dd><p>
+Defines an LED group, driven by <var>monname</var>. Each time the
+monitor's state changes, the list of states will be searched, and the
+first which is true for the monitor's new state will take effect. If
+none of the states apply then the LEDs are left unchanged.
+<p>
+
+The state conditions are:
+<dl>
+<dt><code>talk</code>
+<dd>Someone has spoken on channel since <var>talk-time</var> ago.
+
+<dt><code>talknow</code>
+<dd>Someone has spoken on channel since <var>talk-now-time</var> ago.
+
+<dt><code>preftalk</code>
+<dd>Someone matching <code>nick prefer</code> has spoken on channel
+since <var>talk-time</var> ago.
+
+<dt><code>preftalknow</code>
+<dd>Someone matching <code>nick prefer</code> has spoken on channel
+since <var>talk-now-time</var> ago.
+
+<dt><code>present</code>
+<dd>Someone (not matching <code>nick nopresence</code>) is present on
+channel. ledctrl itself does not count.
+
+<dt><code>default</code>
+<dd>Always true. Put this at the end of the state list.
+
+</dl>
+
+<p>
+<var>led-group</var> and each <var>value</var>
+should be as specified in the LED protocol document. The LED group
+will be accessed in an exclusive manner and should not be accessed by
+any other LED clients.
+
+<h2>userv</h2>
+
+Actually, the configuration is all done with userv. The system
+supplies default implementations of the two services
+<pre>
+irc-ledcontrol-config
+irc-ledcontrol-passwords
+</pre>
+which simply spit out the relevant files.
+
+<p>
+
+The <code>irc-ledcontrol-config</code> service <em>must</em> succeed;
+if you do not want ledctrl configuration it should exit zero without
+printing any output at all.
+
+<p>
+
+If <code>irc-ledcontrol-config</code> produces any output (even just
+whitespace or comments) then <code>irc-ledcontrol-passwords</code>
+must succeed, and produce a standard format LED password file.
+(See the
+<a
+href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED
+specification documents</a>.)
+
+</dl>
+
+ <hr>
+ <address>
+ $Id: ledbot.html,v 1.1 2002-06-10 02:35:07 ijackson Exp $
+ <A href="mailto:ircop@chiark.greenend.org.uk">ircop@chiark</A>
+ </address>
+ </body>
+</html>
~mdw / ircbot / commitdiff