CHAPTER 7 ■ CONTROL HUBS 223 localhost dev /dev/ttyS0 - - You will see how this is able to communicate with other machines in the “Marple” section later in this chapter. Additionally, all Bearskin commands support init as a command argument so that it can prepare temporary log files, adjust ownership permissions, and launch any daemons as necessary. Typical Application Abstractions The currently supported abstractions are held in $MINBASE/bin and include all the necessary functionality. I’ll cover these briefly, pointing out the subtleties as necessary: x10control: This is a simple abstraction that invokes heyu to switch lamps and appliances on and off and dim lights. Because the arguments are unified between all Bearskin commands, the invocation of this looks reversed to heyu, making a typical call look like x10control default on bedroom_light. cdplayer: For those still in love with those shiny plastic discs, this controls the CD player (with cdcd) and retrieves its track listing using the cddb-tool package. Because the retrieval of this data can be quite slow, the track data is temporarily stored in /var/log/minerva so that it can be queried instantly with commands such as cdplayer default currentname. mp3player: This is a general-purpose media player that also processes the ID3 tags inside the MP3 to report the current artist and album with mp3player default artist, for example. It uses /var/log/minerva to store this information, along with the current process ID, which allows you to move through the tracks with mp3player default next. It abstracts mplayer, while making use of mp3info to parse the ID3 tags. wavplayer: This is a simpler, primarily synchronous, audio player used for general house alerts using play. mixer: This adjusts the relative volumes of each channel in the audio mixer, the names of which have also been abstracted so that user-friendly words such as master, cd, and recording can be used. It allows you to set the volumes as either a relative or absolute value between 0 and 100 percent, even when the underlying mixer application doesn’t. The current implementation uses aumix. say: This is the most interesting abstraction, despite being the simplest, because this queries the default voice (stored as a name in $MINBASE/etc/defaults/festvox, if present) and invokes festival. When called on behalf of a specific user, it uses their customized voice settings. There is also a sayfile variant for longer phrases using Festival’s more efficient tss argument. announce: This is an important extension since its context is different. Namely, it’s used for announcements to the house that something (important) is happening. It wraps the call to say by playing a chime sound and lowers the volume of any music that might be playing, before making the announcement and returning the volume levels to normal. Because of the importance of such CHAPTER 7 ■ CONTROL HUBS 224 messages, the device should generally be different from that of mp3player to prevent audio device conflicts in some systems. 3 In the worst cases, this can require using a second sound card or making use of the sound card in an external machine that generally has no use for audio, such as a wall panel. The wavplayer is often configured to use this same device. tweet: This is a way of publishing an announcement via microblogging site Twitter. This can be used by multiple users in the house, since it queries a set of stored credentials for each user in $MINBASE/etc/users/[username]/external/twitter. irsend: This is a means to send predetermined infrared remote-control codes to the connected IR transmitter. It will then be picked up by any sensor in range. For this reason, most IR-enabled equipment is held in Node0 where a single transmitter can service them all. It takes two arguments, the name of the equipment and the message that needs to be sent, and retrieves the code from a file held in $MINBASE/etc/ir/[equipment]/codes/[command]. The format of the data in this file is governed by the name in $MINBASE/etc/ir/[equipment]/method. The <device> in each case will generally be default to indicate the default output stream, which is the set of devices attached to the server machine, mentioned earlier. ■ Note Most Bearskin commands are controlled by killing and restarting the Linux process. This means that in many cases you cannot amend the mp3player process from a user who didn’t initiate it. That is, if you began MP3 playback using the web interface, you can’t stop the music using Cosmic or the command line, unless the governing user has the user privileges to do so. Monexec Monexec is a script that is called manually by the various Bearskin commands mentioned earlier to log each action. When the CD player is started, for example, the cdplayer script calls the following: $MINBASE/bin/monexec cdplayer play That in turn invokes a script: $MINBASE/conf/exec/cdplayer/play 3 Always determine whether your sound card (and its drivers) allow you to play audio from several applications at once. CHAPTER 7 ■ CONTROL HUBS 225 This play script can then perform any imaginable task, such as tweeting the currently playing track or using another command (like say) to announce “Good night” when the bedroom light is turned out. It is for these reasons that a simple log file is not enough. Although, naturally, monexec can also log commands too. TODO: A Worked Example To cement these ideas, you are going to be the brand new writer of a brand new module! It will be the TODO application and will be a fully worked example consisting of a Bearskin command, output conduit, messaging system, and web applet. The design is such that when someone performs the following: todo add steev "Take out the rubbish" the message will be added to the list of tasks in steev’s area and will be available for review on a web page or at the command line, with this: todo list steev This output could even be piped through Festival as part of the alarm call in the morning! So to begin, you need to create a file such as $MINBASE/bin/todo and process the basic arguments: #!/bin/bash MINBASE=/usr/local/minerva CMD=$1; shift USER=$1; shift MSG=$* TODOFILE=$MINBASE/etc/users/$USER/todolist if [ "$CMD" == "add" ]; then date +"%Y-%m-%d $MSG" >> $TODOFILE fi if [ -f $TODOFILE ]; then if [ "$CMD" == "list" ]; then cat $TODOFILE elif [ "$CMD" == "clear" ]; then rm $TODOFILE fi fi You then need to ensure the script is executable with this and test it for a little while: chmod ugo+x todo (It’s OK—I’ve done the testing step for you!) That’s your first step done; once you’ve understood conduits, you’ll see how to add entries into your to-do list from elsewhere. CHAPTER 7 ■ CONTROL HUBS 226 Conduits All communication is two-way, so naturally there are both input and output message conduits. The concept of which part is input and which is output depends on the direction of communication, so you consider them from the point of view of the Linux server, meaning an output conduit is the one that sends messages to devices, primarily for reports and error messages, and an input conduit is one that the server receives from a human to tempt it into action. The current version supports the following conduits, retrievable from the command msgconduit list: • echo (output only) • email (in/out) • ir (output only) • log (output only) • sms (in/out) • twitter (output only) • vox (in/out) • weblog (output only) • winalert (output only) Each conduit has a directory hierarchy afforded to it, existing underneath $MINBASE/etc/msg. Each is identical in structure and may contain none or more of the following directories: addr: This contains two flat files formatted in the same way. The first is alias, which is a list of Minerva-oriented usernames and a conduit-specific address. This would be a mobile phone number in the case of the SMS conduit, for example. The second is contacts, which is a list of address for people you might want to contact but who are not Minerva users. This latter file is available only when sending messages to the output, thereby allowing you to send text messages to your friends but not permit them to query or change the state of your home appliances in any way. auth: This is reserved for future expansion, although it’s rarely used since most authentication is currently done through the $MINBASE/etc/user/[username] hierarchy. cmd: This directory contains a list of command aliases used with input conduits. In this way you can send short messages to the conduit, such as “wakeup,” which in turn runs a cmd/wakeup script, allowing it to perform several commands at once, without you having to explicitly specify them all. Additionally, the script could perform smart contextual operations, so commands such as lightson would determine your location and control the most applicable light. I’ll cover location deduction later in this chapter. xmit: This contains a file called cmd that is usually a symlink to an abstracted Bearksin command that processes the argument list whenever this conduit is used as an output. CHAPTER 7 ■ CONTROL HUBS 227 I’ll now cover the method by which each of these functions so you know how to add new ones in the future and utilize them to best effect. Echo Output only. This is the simplest to understand since it merely reflects all the input parameters to the current console. It is used primarily for debugging the conduits and address book. Email Input/output. Like most of the conduits that support input and output methods, the two are separated by a large expanse of code. For the input side of the conduit, procmail is triggered automatically from the mail server after parsing the incoming mail to determine whether it’s originated from someone who is able to send messages. This is covered fully in Chapter 5. The output conduit uses the standard mail program directly. Infrared Remote Control Output only. This calls the irsend code to determine the device and protocol necessary. Logging Output only. This writes all messages into /var/log/minerva/msglog and is also used primarily for debugging. SMS Input/output. The output conduit works through mxsms, which is symlinked to one of three possible driver scripts, mxsms-gnokii, mxsms-intelli, or mxsms-txtlocal, depending on who is providing the current output service. If adopting the ideas of Chapter 5, you can make mxsms a script in its own right to consider the priority of the transmitting user and determine which service to use. For input, you will have Apache triggering the code when a specific web page is downloaded from a remote SMS-PC gateway or from a custom script checking message through Gnokii (courtesy of crontab). Twitter Output only. . CHAPTER 7 ■ CONTROL HUBS 223 localhost dev /dev/ttyS0 - - You will see how this is able to communicate with other machines in the “Marple” section later in this chapter. Additionally,. bedroom_light. cdplayer: For those still in love with those shiny plastic discs, this controls the CD player (with cdcd) and retrieves its track listing using the cddb-tool package. Because the retrieval. album with mp3player default artist, for example. It uses /var/log/minerva to store this information, along with the current process ID, which allows you to move through the tracks with mp3player