Musings from kb8ojh.net

Identifying damaged parts

The most often-fingered culprits for the Death Wobble in a TJ Wrangler seem to be:

• Worn ball joints
• Damaged or worn steering dampener
• Worn track bar end or bushing
• Worn control arm bushings
• Poor wheel balance
• Bad alignment

I have had two sets of tires on my Jeep since it developed the Death Wobble (which, by the way, was during the warranty period, and Chrysler claimed they’d never heard of it — despite thousands of references to it on the Internet, videos of it in action, and my Jeep experiencing it, which, of course, they “couldn’t replicate”), and had it aligned twice, so I knew those weren’t the fundamental culprit. The most likely problems in my case were therefore ball joints or the track bar.

Getting under the Jeep to figure out what I might need to replace, I found that the lower driver’s side ball joint could be moved with a pry bar — not a good sign. The tie rod and drag link were also both obviously worn out (they could easily be moved/rotated with one hand). The track bar is not easy to check without removing it, nor are the control arm bushings or steering dampener.

In addition to the items I could tell were worn out, the sway bar links are often casualties of the Death Wobble, and the steering dampener was almost certainly bad after numerous Wobbles. So I put together a list of about $600 in front end components, and ordered them. I purchased mostly OEM-equivalent components, not off-road upgrades:

• Drag link assembly
• Tie rod ends
• Steering dampener
• Track bar
• Polyurethane track bar bushing
• Sway bar links
• Polyurethane sway bar bushings
• Upper and lower ball joints
• Upper and lower control arms
• Upper control arm axle bushings

Both the track bar and drag link have tie rod ends made onto the bar itself, so they had to be replaced even though only their ends were bad (or presumed so, in the case of the track bar). The track bar comes with a rubber bushing pressed in place, but I bought a polyurethane bushing to replace it. Furthermore, it took some doing to figure out the situation for the control arms; the lower control arm has two of the same bushing, and the upper control arm is sold with one bushing installed and requires the front bushing to be purchased separately, at least from Quadratec, where I was ordering. The lower control arm bushings can be bought separately or with a new control arm for very little more than the cost of the bushings, so I purchased the entire assembly.

Initial disassembly and steering linkage

When the parts started arriving, I put the Jeep up on jack stands (near the body mounts just behind the front tires, supporting the frame), took off the tires, and pulled apart the steering linkage. You’re going to want to take some measurements when you do this, so that you can get things together close enough to get to the alignment shop (or close enough to ease alignment, if you’re doing it yourself). Measure the distance from the end of the tie rod to the center of the bolt (or grease zerk) on each tie rod end, as well as the center-to-center of the two end bolts, then repeat for the movable end of the drag link. Write this all down, it’s going to be a while before you get to it again!

On my Jeep, all of the bolted parts came apart with comparative ease, nothing was substantially stuck (except some cotter pins), and nothing broke (except the aforementioned cotter pins). Your mileage might vary, there, depending on climate, storage conditions, and damage from off-road activity. My Jeep has lived in a garage for most of its life and its off road activity is limited to trail rides (no rock climbing or river fording here), so things weren’t in terrible shape down there.

With the steering linkage off, the steering knuckles (the bit the wheel hub mounts to) are free to rotate back and forth, making disassembly easier, so I removed the brake calipers and rotors. When you remove the calipers, set something by the frame to support them; I used some buckets and boards. They shouldn’t put tension on their brake lines, and they’re going to be there for some time. At this point I had to go buy my first “oops” part — a 1/2"/13 mm spline socket for the wheel hub bolts. They’re either 12 point or spline, but the spline socket worked great. Fortunately a friend had the 36mm axle nut socket, so I didn’t have to buy that. Once I had the tools, I got the wheel hubs off without difficulty. Miraculously those spline bolts were not siezed (they looked terrible), and came right out. siezed, and the

At this point the narrative order gets a bit muddied; I definitely took the passenger side wheel hub off one day and the driver’s side wheel hub off the next day, but I don’t remember what (if anything) I removed in between. I think nothing. Either way, it turned out that a) both wheel hub bearing seals were leaking, so I needed two new wheel hubs (it’s a sealed, non-repairable unit, about $63 each); and b) no local parts store had two wheel hubs. I bought one each at two different stores and called it good.

Ball joints, sway bar, and reassembly of steering

With the wheel hubs off, the U-joints and half axles literally pull right out. My U-joints seemed to be in good shape, so I just set those aside. This leaves the steering knuckle mounted on the ball joints and ready to be removed by removing the ball joint castle nuts. A few swift raps with a 3 lbs drilling hammer (the best hammer ever: Estwing B3-3LB Drilling Hammer) knocked each knuckle off the ball joint tapers. At this point the ball joints can be inspected properly; both of my lower ball joints were completely destroyed, and flopped around in their housings like a ball-in-socket. The upper ball joints were still pretty stiff, but I elected to replace them anyway. The amount of play in the lower ball joints when prying them with the frame lifted but everything assembled versus the amount of play in the disassembled joint was shockingly (to me) misleading; I would not have guessed they were so bad, from the assembled movement.

Removing the ball joints with a rented ball joint press was somewhat complicated, as the receiver rings supplied with the press were not quite appropriate sizes and the press was not deep enough to place a ring on both sides of the bracket (which would have been required for replacement of the lower ball joint and both removal and replacement of the upper). This required some jury-rigging. The lower ball joints were relatively easy to push out, except that the press had to be mounted a bit crooked. The upper ball joints I then pushed out by the stud; the passenger side ball joint separated (and the stud came out entirely) by this method, allowing me to push directly on the ball joint body without a ring. The driver side joint pushed out by the stud!

Replacing the ball joints was more difficult than removing them, for the same reasons. We put the lower ball joints in first, which may have been a mistake; it’s not clear which order would have been easier. They could be pushed most of the way in without a receiving ring on the back, which allowed enough throat in the press to put a large socket on the back to receive them. The press plates and rings would not have fit. The upper ball joints took a lot of head-scratching and fiddling, but ultimately we were able to get them in by placing the smallest ring available for the press directly on one side of the press (which was OD sized almost exactly the same as the ID of the ring, so separating them after the fact was rather … enjoyable), saving the depth of an end plate, and shimming the other side with a piece of metal plate and a screwdriver tip to get everything straight. It took four hands.

Installing the ball joints was the second most difficult part of the whole job; it took maybe two or two and a half hours. Once they were in, re-installing the (cleaned, primed, and painted) steering knuckle was easy. Before re-installing the steering linkage, however, it seemed prudent to do the sway bar links and sway bar bushings; both were trivial. My only note here is that I couldn’t find any torque numbers for the poly sway bar links; a call to the manufacturer (Crown) confirmed that they require OEM torque (70 ft-lbs for the lower bushing and 40 ft-lbs for the upper joint). The steering linkage was not difficult. The steering dampener did require rocking the wheel back and forth a bit, as the bolt (installed to the drag link) was not precisely at 90 degrees to the bushing in the dampener.

Track bar

Removing the track bar was not difficult. Re-installing it did require pulling the axle toward the driver side of the vehicle, which we accomplished by way of a ratcheting tie-down strap. Removing the factory bushing was straightforward with the ball joint press, and the polyurethane replacement bushing can be inserted by hand.

Wheel hubs and brakes

With the steering knuckles and linkage back in place, the wheel hubs could be re-installed. As previously mentioned, I had to replace both hubs. I elected to clean and paint the shields that mount behind the hubs to protect the back side of the brake rotors before re-installing the hubs over them, as well. Bolting the hubs on was as easy as taking them off, with the most difficult part being putting 175 ft-lbs on the axle nut.

At this point, it did become obvious that the grease zerks supplied with the lower ball joints are unusable. They were tall 45 degree affairs that interfered with the U-joint. The passenger side sheared without any commotion (I didn’t even notice), but the driver side stopped the wheel from rotating and I briefly thought there was a problem in the half-axle or differential. Once the offending zerk was located and both sides were replaced with simple caps, the problem went away.

Control arms

In order to keep the axle in place as much as possible, I elected to replace the control arms one at a time. Because I was replacing the arms along with the bushings, I didn’t have to push out the lower arm bushings or the upper arm frame bushings, and the new arms came with these bushings pre-installed. Removing and replacing each lower control arm in turn was straightforward, although re-installing the bolts required jacking up the axle on the installation side and pulling it to the rear with a ratcheting tie-down.

Removing each upper control arm was similarly straightforward. Removing and replacing the upper control arm bushings (specifically the driver side upper control arm axle bushing) was the most difficult part of the whole job. This was due to a combination of the unsuitability of the ball joint press for the job and the difficulty of reaching the driver side ball joint due to interfering parts (such as the coil spring, pitman arm, and drag link; in retrospect, replacing this bushing before installing the steering linkage would have been somewhat easier). The passenger side bushing was easier than the driver side bushing due to the construction and geometry of its bracket (it’s a U-shaped sheet metal bracket, versus the driver side bracket which is cast into the differential housing, and the bushing presses almost all the way through it, allowing the control arm to be used for final seating). However, I did bend the bushing bracket slightly removing the bushing; I’m not sure how one would press it out without doing so, actually. It did not bend far, and straightening it was not difficult, and I do not believe it to be worse for the wear.

The passenger side bushing was pushed back in with a combination of the ball joint press to get it started and the control arm itself with large washers and some light blows against the bracket to do final seating. I wouldn’t recommend this method, necessarily, but it worked and it was easier than the other side.

The driver side bushing couldn’t be pushed out because there was no way to get the press on it square enough to move it substantially. Removing it was therefore a combination of burning the rubber (with a propane torch), pushing out the center metal bushing, then cutting, crushing, pulling, twisting, and otherwise brutalizing the outer metal shell until it came free. This was the single most time consuming task of the entire job; it took approximately two and a half hours. Re-installing it likewise could not be done with the press, so we employed the press receiving rings, a large socket, a number of washers and nuts, and a long piece of threaded rod to press it into place. Getting it started square with the hole was tricky (for one thing, the hole in the bracket appears to be neither square with the ground nor parallel to the front-back axis of the vehicle), but by witnessing it both from the front through the steering linkage and from the top past the steering fluid reservoir and employing judicious blows from the 3 lbs hammer (another two-person job), we got it started. Once it was started, it was simply a matter of cranking down on the threaded rod until it broke (we could get neither grade 5 nor grade 8 rod on short notice) and then finding a fresh part of the rod where the nuts would thread on and starting again. All told, it was much easier than removal, but still time-consuming.

I found that re-installing the upper control arms was easier if the axle end bolt was pushed in first, as the front of the control arm itself has more play in it than the rear (as the rear has a bushing pressed into it holding it rigid, while the front is a loose U until bolted in), allowing the rear bolt to be jimmied into place by bearing on the control arm. I believe the driver side upper control arm also required some ratchet strap treatment, although I do not fully recall.

Final assembly and alignment

With the steering linkage assembled and the control arms replaced, the tires can be remounted and the Jeep set back on the ground. I tightened the sway bar bushing bolts after setting it back down, then checked the various fasteners that do not have a cotter pin (sway bar links, control arms, steering dampener, etc.).

I had alignment done by a professional shop. The driver’s side wheel was not toed in quite far enough, but other than that everything checked out. Getting to the alignment shop was not an issue. Measuring the tie rod ends and reproducing those measurements worked great; my suspicion is that the remaining alignment problems were from the previous alignment correcting for destroyed lower ball joints (as it was last aligned after the Death Wobble had taken hold). Measurement error is of course also a possibility.

Lessons learned

It took about four days for this job. I started on Friday afternoon and finished late on Monday, skipping only Saturday morning due to other commitments. I think if we did it again this coming weekend, it would take about two days. It’s a big job no matter how you slice it, and it’s going to be a lot easier with two people; in particular, getting the ball joints and upper control arm bushings pressed in will be easier with an extra pair of hands. Most of the other operations can be done solo with a minimum amount of difficulty, but not having someone to “hold the other end” or hand you tools will slow you down.

The biggest non-equipment lesson taken out of this is order of operations. I wanted to get the steering linkage completely in place before doing the control arms in order to minimize the possibility of anything coming too far out of alignment, but in retrospect it would have been much easier to deal with the upper control arm bushings (particularly on the driver side) with the steering linkage removed. I don’t think there’s any reason not to do this. The steering linkages are all flexible anyway, and the track bar and remaining control arms (assuming they’re replaced one at a time) will keep things where they belong.

As far as equipment, I had seen several comments that the typical ball joint press that can be rented at local auto shops doesn’t really have the right fittings for a TJ Wrangler. There are kits available to adapt those presses for Jeeps, and there are presses for Jeeps. They are relatively expensive; I am not sure I would purchase one, but I might call around to local shops and see if I could find one to rent. The shop I rented the press from did have adapter kits for some vehicles (mostly imports), but not Jeeps.

Total costs

The total costs were as follows:

Several of these parts are available cheaper, but I wound up paying more either to get them in time or to consolidate orders, or because I didn’t trust some sources (e.g., the entire steering linkage is available for just a few dollars more than I paid for the drag link … and possibly made of cheese?). In particular, I bought the tie rod ends locally, which cost me about $20 more than ordering them with the majority of the rest of the parts, but Quadratec didn’t have them in stock.

While I did preorder most of the parts without knowing if they were absolutely required, when all is said and done I don’t think I replaced a lot of things that didn’t need to be replaced. The upper ball joints may have been OK, as may have been the control arms themselves (but the bushing rubber wasn’t in great shape). However, I don’t think I would change the lower ball joints without the upper, and the upper control arms were sold as a unit with the rear bushings; I might have been able to save $30 or so by buying lower control arm bushings instead of lower control arms. I could of course have aligned everything myself, but I was more comfortable leaving that to a professional. I don’t think I could have reduced the above cost by more than about $100 in practicality, except maybe by vetting some of the cheaper parts suppliers for legitimacy and ordering from multiple sources.

Results

So far, it seems to have worked. I’ve driven several problem roads with nary a Wobble, and no pre-Wobble vibrations. The steering is much stiffer and more responsive; I attribute this to three things: 1) the old parts were worn, 2) the new parts haven’t yet broken in, and 3) replacing rubber bushings with polyurethane in several places. All in all I like the feel much better than what I’d grown used to!

Acknowledgments

I had a lot of help on this one. One friend spent about 2 1/2 of the four days here working in my driveway, and my dad dispensed a fair amount of advice over the phone (he has an XJ, which has a very similar front end).

I’m fairly picky about software that I use a lot. I tend to find something that I like, or that comes very close to what I want, tweak it into place as best I can and then use it for a very long time. Good examples of this are mutt and FVWM, which I have been using since the early-to-mid-90s, and rxvt-unicode, which I have been using for a decade or more, since rxvt started showing its age with respect to multi-byte encodings. The primary thing I ask out of such software is that it gets out of my way … if I have to fiddle with it a often, and I use it a lot, that’s a lot of fiddling. Recently, changes in my usage habits have caused my window manager (FVWM, which is on this list) to require some fiddling. That means it’s time to explore some alternatives, which I have done, and I’ll talk about here.

Some Background

First of all, some X11 history for those who might not be aware — which includes those who have grown up on these new-fangled “desktop environments” — or might not have thought about its consequences. Early on, X11 adopted the motto “mechanism, not policy,“ and sought to provide a way to draw a GUI without really dictating how that GUI should look, function, or feel. This was largely because, in the 80s, it wasn’t at all clear what a GUI should be like, and there were several competing paradigms.

This mechanism-not-policy design had both upsides and downsides (enough to fill a book, really), but the one that is most interesting here is the idea of window management. While most GUI systems provide their applications with a drawing area that is managed by the GUI system, by which we mean that size and placement of the window, functions like iconifying and hiding, and similar actions are sort of baked into the system, X11 does no such thing. This means that the management of windows is up to just another application, which we call (logically) a window manager. There have been dozens or hundreds of window managers over the years, often embodying essentially the same principles but with slightly different implementations and feature sets that vary around the edges. For many years these window managers were primarily of the familiar floating window type, which means that application windows are movable, resizeable rectangles that can be stacked atop one another with some sort of border and title bar enabling their identification and manipulation. This is the only kind of user interface that desktop operating systems such as Mac OS X and Microsoft Windows provided for many years, although recent incarnations of both are breaking this mold (primarily in the form of full-screen applications).

One such floating-window window manager is FVWM, which came about in the adolescence of X11 as an improvement on TWM, the default(ish) window manager of the day, bundled with a terminal application from the same author. It was designed to be more featureful than TWM while being smaller and faster than the more capable competitors, so as to run it on a PC of the era with its relatively wimpy processor and RAM and low-resolution display (in comparison to Unix workstations). I picked up FVWM when it was relatively young (some time in the Spring of 1994), and have been using it ever since, with brief excursions in the late 90s and early 2000s (to Enlightenment and then Sawfish) that ultimately left me back on FVWM. FVWM is a relatively mature and featureful implementation of a classic floating-windows window manager, having a lot of features that are familiar to old-time Unix users (and increasingly familiar to Mac OS X users, over the past few years, such as multiple desktops or pages) and providing a mousing-friendly interface that does its best to keep manual window interaction to a minimum. It’s good at placing windows so that they don’t interfere with each other, handles focus in a sane manner, and has a number of useful and robust tools such as toolbars and pagers associated with it.

Changing habits

One thing that FVWM has always handled with only moderate capability (in my opinion) is X11 displays with multiple monitors. X11 can be configured to manage multiple monitors in several ways, which basically boil down to either a) stitching them all together at the edges in some sort of non-overlapping rectangle-bounded layout, such that windows can extend off one edge of one display and onto the edge of another, logically adjacent, display; or b) placing them in a similar logically adjacent pattern, but treating them as separate displays with their own windows and window management, such that windows are wholly constrained to one monitor [1] and cannot be simply moved between them, but the mouse pointer can.

In the first case, where the monitors basically form one large contiguous desktop, FVWM cannot treat the individual monitors separately when it comes to changing pages. (Pages are sort of, but not quite, like Spaces on OS X; they are logically adjacent areas that windows can overlap, but can be switched between to rapidly change the set of windows currently visible on the screen.) This means that changing pages on one monitor necessarily changes pages on the other monitor, which is often undesirable. For example, if I have my editor visible more-or-less full screen on the right-hand monitor, I may want to alternate displaying a PDF viewer or web browser for documentation on the left-hand monitor with some terminals for compilation and file management without messing with the editor.

In the second case, where the monitors are basically distinct windowing environments that happen to lie adjacent to one another, FVWM can switch pages independently but windows cannot be moved from one monitor to the other. This is the tradeoff I used for a long time, and in fact it turns out that I very seldom actually want to move a window from one monitor to the other. It does occur, however, and this scenario typically requires exiting the application entirely and restarting it on the other monitor.

Another thing that FVWM doesn’t handle very well (and indeed most floating window managers do not) is creating and destroying a lot of windows in arbitrary sequence. This is because once a window is created, placed, and sized, FVWM doesn’t mess with it unless you manually adjust it. It does a fairly good job of placing and sizing newly-created windows, but without adjusting the existing windows this is constrained by the currently-visible applications and their disposition. For a very long time I didn’t chafe at this restriction, for whatever reason, due to my workflow. Most of my pages had several non-overlapping terminal windows (typically four), while the remaining pages had a web browser (that I had to fiddle with occasionally, but not a huge amount) or my editor (which pretty much just has its own dedicated place and never has to be messed with).

Lately, however, this has changed; I can’t say exactly why, but I’m spending more time creating and destroying windows for various document viewers and graphics-editing applications. These windows tend to require some fiddling — and, given that my pages are typically tiled with terminals already, figuring out where I should put them so as to minimally disrupt those terminals is tricky. In addition, I use multiple browser profiles to separate concerns (and increase privacy), which entails juggling a number of large windows that each occupy more than half of the physical screen at a time.

Couple that with the re-addition of a second monitor to my primary laptop display and the implications thereof (non-ideal handling by FVWM, divergent FVWM configuration between my desktop and laptop, etc.), and it was time to go window manager shopping again.

Finding a replacement

In looking for a replacement WM, I had a definite desiderata:

• Gracefully multi-monitor: Since this was a pain point for FVWM, I certainly wanted to address it with a new WM. In particular, I would like to be able to stitch my monitors together as a single X11 screen while coherently managing windows between the screens with a minimum of fuss — including page-flipping on a single monitor. Handling the addition and removal of external displays (such as when performing a presentation on a laptop, for example) with alacrity would be a big bonus.
• Programmable: I am a huge fan of programmability; my editors have always been programmable, my IRC and IM applications are programmable, etc., and I had a rather pleasant experience with the programmable Sawfish a decade or so ago. I don’t recall precisely why I stopped using Sawfish (I think it was actually multi-monitor support), but I do recall that I developed a number of lines of lisp to manage my windows for me, and found it useful to do so. (Sawfish was extensible in some dialect or another of lisp, or maybe Scheme.)
• Not too rigid: I’ve never gotten along well with the default window managers of the various desktop environments out there, because they are invariably too rigid for me. I have habits that have been developed and deeply ingrained over twenty years or so, and often they fail to be configurable in some particular point that is a deal-breaker for me. Programmability likely meets this criteria in most cases, but it’s surprising what people bake into software at times.
• Supports a community: This is probably the weakest of my requirements; however, I have found over the years that a software project with a supporting community is much more likely to meet my needs over the long run. It can even evaporate in five or ten years and I’ll probably be fine, because by then I’ll have things hammered into shape. However, continued progress ensures that things like distro-provided packages will be available when I want them, and generally reduces my need to babysit the software.

With these things in mind, I went out and looked at the window managers that people are using today. Tiling window managers (as opposed to floating-window window managers, tiling WMs automatically place and size windows on your screen in some sort of minimally-overlapping configuration that is rearranged as windows are created and destroyed) have become quite popular in the past few years, while they were really in their infancy the last time I looked around. In particular, several hybrid tiling window managers that allow some windows to be tiled while others are floated have received quite a lot of attention. Additionally, a return-to-minimalism sentiment (perhaps driven by the ever-increasing complexity of desktop environments) has spawned several projects of a design style that I quite approve of — a small, compiled core with basic functionality fleshed out by an interpreted configuration and extension language.

I was first introduced to this application design strategy in editors (via Jed, which I still use for some limited purposes), but I first saw it codified in a way that I could really identify with in John Ousterhout’sUSENIX paper Tcl: An Embeddable Command Language (PDF link), which describes a simple command-based language for extending native-code applications in programmable ways. When I read this article, it clicked for me that not only is this a reasonable way to design GUI frontends for utility libraries (the major thrust of the article, though it certainly describes the use I found compelling), but that it is generally a good way to design all large programs. In fact, we’ve seen that paradigm increasingly adopted, with web browsers largely implemented as core native code glued together by JavaScript possibly being the most obvious example.

Several new-ish window managers immediately stood out as embodying the principles I was looking for in one way or another. In particular, the family of window managers derived from or inspired by dwm, including xmonad and awesome, and the ultimate form of the Ion (now defunct) window manager, Notion. (There are a lot of other possible WMs out there, some of which I looked at, but each of them either failed to meet a point of my desiderata or simply did not impress me for some reason. If your favorite WM isn’t here, that doesn’t mean I didn’t look at it. In particular, several interesting candidates were not as pervasively programmable as these three.) To make a long story short, I ultimately decided (based on perusing documentation, recommendations from people I trust, and not being written in Haskell [2]) to invest some time into awesome.

The awesome window manager

The awesome window manager is a hybrid tiling/floating WM, allowing windows to be either tiled or floated on an individual basis. It has a small core implemented in C using the (more) modern XCB X11 libraries and essentially all of its behavior is defined in Lua configuration files — to the extent that it does nothing at all if you do not provide it with a Lua configuration. It actively manages new and existing windows using a set of rules implemented in Lua that can move, resize, hide, etc. windows as required by the current circumstances.

For my purposes, it meets all four points of my desiderata; it has multi-monitor support as a primary development goal, it is not only programmable in but largely implemented in Lua, it provides relatively little policy on its own and is extremely flexible, and it has an active and interested community. It has a quite usable panel API that can provide a window list, system tray, clock, and other useful tools. It also provides some interesting features I haven’t gotten around to investigating, such as D-bus connectivity.

I was never particularly drawn to “true” tiling window managers when they first came around, as there are certain windows that I prefer to have a particular size and position and that my window manager not mess that up. For example, the window in which I read email is an 80×24 terminal, and I expect it to stay that way. However, modern hybrid tiling/floating window managers can handle this just fine — such windows simply float, perhaps even on a page co-located with tiled windows. Awesome lets me conveniently handle this on either a per-page or per-window (or both) basis. For example, my preferred layout (for now; it’s a port of the FVWM configuration I’ve been using for the past seven or ten years) is six pages, logically arranged in a 2×3 grid. Of those pages, three are fair tiling (for development terminals), one is floating (for my mail and other communication software), one is a tiling rule set I modified myself (for web browsing), and one is full-screen (for my editor).

One advantage of a programmatically-defined configuration is the ability to make configuration decisions based on the machine on which you are running or its properties. For example, I want a battery state indicator to be displayed at the top of the screen on my laptop, which has a battery, but not on my desktop, which does not. In awesome, it turns out that that is simple:

bat = io.open("/sys/class/power_supply/BAT0/status")
if bat then
    -- Create battery widget here
end

This takes advantage of information available to the kernel and presented in the /sys filesystem to determine whether a battery is present or not, and act accordingly. This sort of configurability was possible with FVWM, too, but in practice it rapidly became painful and I handled it by having somewhat divergent configurations on various machines — a practice that I cannot recommend!

Similarly, configuration decisions can be made depending on the display properties, such as the number of attached monitors (which awesome calls screens, though more than one awesome screen may actually be present on a single X11 screen). In the aforementioned 2×3 grid, on a single monitor, I place all six pages on that monitor. On a dual-monitor setup, the left column is on the left monitor while the right column is on the right monitor. This allows my keybindings and navigation to remain the same regardless of physical monitor layout. In practice I do use a single monitor somewhat differently from a dual-monitor workstation, of course, but keeping things as parallel as possible is comfortable for me.

Probably the most broadly useful programmable feature of awesome is the layout engine. This engine controls not only how windows are initially disposed (to which monitor, at what size and location, floating or tiled, etc.), but also how they are affected by the creation and destruction of subsequent windows. For example, the most basic tiling window layout, awful.layout.suit.tile, places one or more master windows on the left side of the screen, with a configurable width and heights that occupy the entire height of the display in a non-overlapping fashion, with the remaining windows in a configurable number of columns to the right.

The tile layout managing three windows.

This is great for managing windows that a) can be readily resized without greatly affecting their functionality, and b) can happily coexist while using less than the full screen. If the master window column width is set very wide, then one of the windows can occupy most of the screen while you’re working with it, while other windows are shoved off to the side out of the way. If it is somewhat narrower, than multiple usefully-sized windows can be present at the same time. I find it handy to have a single terminal about 1/2 of the width of the screen as the master window, with several terminals stacked in the other column. (Indeed, this is a classic use for the tile manager.)

It’s not so great for windows that you don’t want to occupy the full width of the screen, however, and that may not be sharing the screen with any other windows at any given point in time. If only a single window is tiled, it takes up the full screen. For a web browser or terminal, for example, this may make columns of text much wider than is comfortable to scan. In the case of a terminal (if you’re like me, anyway), you probably don’t have only one on screen at any given time. A web browser, you might.

Which brings us back around to programmability. Wouldn’t it be nice if the tiling window manager could limit a window to the master column width even if only one window were present? Sounds good, let’s bust out some Lua. It turns out that accomplishing this was a matter of opening up the tile layout, changing approximately four lines of code and some names, and dropping it into the awesome config directory. In fact, you can find that code here.

Presto, a single web browser window has a configurable width, but adding additional windows to the screen (for example, other profiles in the browser, which is my typical use case) tiles unused windows nicely off to the side where they can be seen but they are not in the way.

It’s not just layouts and the menu/window bar at the top of the screen that can be customized this way … it’s everything. Keys can be bound to arbitrary Lua functions, as can mouse buttons. Incoming D-bus events can cause the WM to respond. New windows obviously get a callback, and that one has a fair amount of infrastructure around it. Arbitrary properties (as well as properties that have meaning to the awesome internals) can be applied to windows based on their characteristics (such as the application they belong to, their title, etc.), and those properties can be queried by functions that deal with the window later on down the line — or those functions can add properties, themselves.

I reserve the right to flee back to FVWM if something surprises me in a bad way, but I’ve been using (and modifying) awesome for about a week now and I think it’s a keeper. My workflow isn’t quite what it was on FVWM, but … isn’t that the point? There are some features I miss, such as edge flip (FVWM can change pages when the mouse passes the logical edge of the screen), but I’m finding comfortable alternatives to most of them. If any of them remain pain points, a little bit of Lua will probably fix the majority; some of them (again, edge flip) may require recourse to C, but the advantages of awesome may make that practical. Or at least not so impractical.

Then again, I also reserve the right to plunge even farther down the rabbit hole, and mix and match my tags instead of treating them like pages, or abandon the pretense that my pages are laid out on a grid, or … but let’s not get too wild, yet.