chiark ledctrl bot

The ledctrl bot exists to allow users to have activity on channels they're interested in reported on LEDs via the LED control protocol.

Privacy

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.

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.

If you want to know who is being told information about IRC activity, say

/msg ledctrl who

and it will report something like this

-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

In this example, the channels #starcraft and #test are being monitored on behalf of ijackson, who has chosen to name the monitoring functions ijackson:sc and ijackson:#test. 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.

Usage

If you want to use this facility:

Make sure that your LED server is operating properly, and that you can use remoteleds on chiark to manipulate the relevant LEDs.
If you're using a nonzero password (which is recommended, as otherwise any other chiark user could interfere with your LEDs), copy the .led-client-pass that you're using to ~/.userv/irc-ledcontrol-passwords (taking care to make sure it's not world-readable).
Write the configuration file saying which channels to monitor and where to send the answers. Put it in ~/.userv/irc-ledcontrol-config. See below for the file format.
Join #ledctrl. 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 /msg ledctrl reload username where username is your own username. If all is well it should just say <ledctrl> reloaded username and shortly afterwards your LEDs should be set.
If you still can't get it to work, say /msg ledctrl debug username 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.
If you decide you don't want to use ledctrl any more, delete your config file and say /msg ledctrl reload username, which will cause ledctrl to forget about your configuration (and any stored passwords).

Configuration model

The file ~/.userv/irc-ledcontrol-config 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.

The file may contain definitions of two kinds of objects:

Monitors: 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.
Monitors have names of the form username:suffix where suffix is chosen by the user who defines the monitor.
devicesets: 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.

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:

ijackson:#chiark
ijackson:#starcraft

Consult ~ijackson/.userv/irc-ledcontrol-config for exact details. To suggest changes to this configuration, consult ircop@chiark.

If you define a deviceset which refers to a nonexistent monitor, it will be silently ignored.

Configuration syntax

The configuration file is line-based. Leading and trailing whitespace on each line is ignored. Comment lines (starting with #) and blank lines are ignored. Lines (including comment lines) may be continued using \.

Configuration directives

monitor monname #chan [#chan ...]

Defines a monitor named monname which monitors the specified channel(s). monname must start with username: where username is the username whose file the directive occurs in.

nick ignore [glob-pattern ...]

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.

Affects all monitors defined, until the next nick ignore.

nick nopresence [glob-pattern ...]

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.

Affects all monitors defined, until the next nick nopresence.

nick prefer [glob-pattern ...]

Defines a list of nick patterns to be extra interested in, when they talk on channel. See the preftalk and preftalknow monitor state conditions in the leds directive, below.

Affects all monitors defined, until the next nick noprefer.

Important: Use of this directive can amount to fairly intrusive monitoring of the activity of the affected nicks. Ask permission from the target before using this directive on a real person. ledctrl will inform the target of the surveillance.

times talk-now-time talk-time

Specifies the times, in seconds, for which someone speaking in channel will satisfy the talknow and talk conditions, respectively. talk-now-time should be no more than talk-time.

Affects all monitors defined, until the next times. The initial values are 120 and 450.

leds led-group monname state=value ...

Defines an LED group, driven by monname. 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.

The state conditions are:

talk: Someone has spoken on channel since talk-time ago.
talknow: Someone has spoken on channel since talk-now-time ago.
preftalk: Someone matching nick prefer has spoken on channel since talk-time ago.
preftalknow: Someone matching nick prefer has spoken on channel since talk-now-time ago.
present: Someone (not matching nick nopresence) is present on channel. ledctrl itself does not count.
default: Always true. Put this at the end of the state list.

led-group and each value 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.

userv

Actually, the configuration is all done with userv. The system supplies default implementations of the two services

irc-ledcontrol-config
irc-ledcontrol-passwords

which simply spit out the relevant files.

The irc-ledcontrol-config service must succeed; if you do not want ledctrl configuration it should exit zero without printing any output at all.

If irc-ledcontrol-config produces any output (even just whitespace or comments) then irc-ledcontrol-passwords must succeed, and produce a standard format LED password file. (See the LED specification documents.)

$Id$ ircop@chiark