Wednesday, December 31, 2008

More Fuzzy Logic


Ok, so it may have been hard to follow my previous post, especially with no graphics. Well fear not, I just dug up some old materials from my senior project and there is a nice graphical explanation of fuzzy logic. It's a little big because it was meant as my poster for the final competition, but it should be followable.

Monday, December 29, 2008

Fuzzy Logic

We all have our little pet methods that we like to use. I for instance will try to use microprocessors (specifically Atmel or PIC) to solve a problem I encounter. You may use FPGAs or CPLDs. Some crazy people will use .NET and embedded WinCE or somesuch. Everyone has different tools and methods that they are familiar and comfortable with.

One of the tools that I use to solve problems is fuzzy logic. I want to say it's not very well known, at least, I don't get many appreciative nods when I mention it to colleagues. I plan to talk about it as a solution to various problems so it will be useful for you listening (Hello? Anyone out there yet?) if I were to explain it and its use.

Where to start? It might be best to start mathematically. In a mathy sense, fuzzy logic is a method to map m-dimensional input space to n-dimensional output space in a continuous nonlinear fashion. The output may or may not be 'smooth' (ie, differentiable at all valid points in both directions), but my gut feeling is that it is. Don't ask me to prove it, I won't. I'm sure it's proved in some paper somewhere. If math is really your thing then I'm sure this will matter to you, so by all means, look it up.

So what does that mean? Fuzzy logic is basically a function. It can take any number of inputs and produce any number of outputs. The output can depend on one or many of the input variables. So if we have a fuzzy logic function that takes two inputs and produce two outputs: [a,b]=fuzzy(c,d) The inputs and outputs are usually limited to a certain range (If you're mathy, it's called input space and output space. Non-mathy types: you too can feel important and smart by saying things like My fuzzy logic function maps a three-dimensional input space to a two-dimensional output space. And I always drink my tea with my pinky sticking out - I'm distinguished that way.). An input may be limited to values from 0 to 20, and for values outside that range you'd either cut it off to the limit value (ie, 0 or 20 depending on where you go outside the range) or extrapolate somehow. I generally choose to cut the values off. Outputs are also limited as a result of the limitations to the input - since the input space is limited so is the output space.

Now there are all kinds of multi-dimensional nonlinear functions. Usually they're defined something like this:

z=f(x,y)

x varies from 0 to infinity
y varies from 0 to infinity

for x=0 and y=0, z=0
for x>0 and y=0, z=0
for x>0 and y>0, z=x*y


This scheme covers all values, is nonlinear, and if you're careful enough in the definition produces a continuous function. The beauty of fuzzy logic isn't the fact that it IS a nonlinear mapping of multi-dimensional input space to multi-dimensional output space (say THAT five times fast!), but the HOW of how it accomplishes that mapping.

This is where the 'fuzzy' part of fuzzy logic comes in. In the above example we have some logic and it's very precise. Inputs have precise values, EXACT values even. And we have logic: If x IS 1 AND y IS 1 THEN z IS 1. What if I don't want to be so exact? What if I want to say IF x is BIG and y is SMALL THEN z IS MEDIUM?

You might be asking yourself 'Why would I want to create a function to express such a concept?' If you're starting off from a mathy 'multi-dimensional input space' type of position then you probably don't see the need for such a statement, or a means to evaluate it. If you're mathy then you like numbers and variables and ranges - oh my! But if you're an actual person (the jury is still out on whether mathy 'people' are actually human) then fuzzy logic is for you. Take the example of tipping at a restaurant.

At a restaurant you usually have to give a tip which is some percentage of your total bill. I evaluate this percentage based on the level of service I receive and the quality of the food. We'll score them both based on a ten-point scale with 0 being the worst, 10 the best. I will generally tip between 0 and 33% of a bill. Let's functionize that:

0 < Tip% < .33
0 < Food < 10
0 < Service < 10

Tip% = f(Service,Food)

Ok, so how much should I tip? Fuzzy logic has the answer.

The first step in fuzzy logic is to 'fuzzify' the inputs. We do this with what are called 'input membership functions'. That's just a mathy way of expressing a concept like: '0 is definitely (100%) awful service while 2.5 is definitely not (0%). All values in between that vary linearly'. If you graph it, that would be a triangle with your peak at the 'definitely' point and then a straight line drawn to your 'definitely not point/points' Since 'awful service' was at the low end of our range for service it only has one 'definitely not' point. For 'OK' service we might place the peak at 5 and the low points at 10 and 0. It will be a triangle that spans the whole range with its peak at 5.

For both Service and Food we'll define 'Awful','OK', and 'Great' levels. Awful peaks at 0 and bottoms out at 5, OK peaks at 5 and bottoms out at 0 and 10, and Great peaks at 10 and bottoms out at 5. Now for any numeric input value from 0 to 10 we can describe how accurately the service is 'Awful', 'OK', and 'Great'. For instance:

Service = 5
0 = Awful(Service) %The service is not at all Awful
1 = OK(Service) %The service is definitely OK
0 = Great(Service) %The service is not at all Great

Service = 7.5
0 = Awful(Service) %The service is not at all awful
.5 = OK(Service) %The service is somewhat OK
.5 = Great(Service)%The service is somewhat Great

It is worth noting that these membership functions don't have to look like triangles - they can look like squares or gaussian functions or trapezoids. The complexity of the calculations to determine value of the membership function increases, but not the general idea.

Now that we know to what extent the level of Service or Food matches our descriptions (Awful,OK,Great), we can create the output with rules. This requires output membership functions. These work pretty much like the input membership functions but in reverse. Each output membership function has an output number associated with it as well as the degree to which it is asserted. For tipping I'll say that the tip is 'Small' if it's 0%, it's 'Normal' if it's 16.5% and it's 'Big' if it's 33%. These membership functions also have shapes associated with them but for an expedited example it only matters where their nominal output values (or center points if you're thinking with shapes) are on the output axis. The output number is determined by doing a weighted sum of each nominal output value times the degree to which it is asserted. Thus we can say that the tip should be 33% Low, 50% Normal and 75% Big, and if we do a weighted sum we get:

0*.33+16.5*.5+.75*33 = ~8.5% tip (roughly)

So once we know how much each output membership function is 'asserted' we can tell how much we should tip. How do we tell how much each output membership function is asserted?

That's where rules come in. To determine the level of assertion we make rules that read like:

1) IF SERVICE IS GOOD AND FOOD IS GOOD THEN TIP IS NORMAL
2) IF SERVICE IS BAD AND FOOD IS GOOD THEN TIP IS NORMAL
3) IF SERVICE IS GREAT AND FOOD IS BAD THEN TIP IS LOW
etc...

You'd probably make a lot of these rules for a tipping system, and depending on how much you value food versus service your rules would be different than everyone elses. So in the above example if the degree to which the Service is Good is .5, and the degree to which Food is Good, how do we evaluate the AND? There are several ways. You can multiply the two .5's and get .25 for the level of the tip being Normal or we could choose the maximum of the two values. There are other ways, but it has to make some sense. You can also have OR's as logical operations (the OR operation is usually a minimum of the two) and NOT (usually 1-value). How the operations are evaluated changes based on the type of system you are putting together, so don't be too shy about the 'right' way. My AND's are usually the product and my OR's are usually minimum.

So using these operations you assign some weight to each output (Normal, Big, Low). As seen above, multiple rules produce weight for Normal. When this happens, you either add all of the weights together or select the highest. When you've gone through each rule you'll have a weight for each output:

Low = 0
Normal = .5
High = .5

Then you go back two steps above and perform the weighted average of the output values. In this case you'd get:

0*0+.5*16.5+.5*33 = 24.75% tip

That must have been some good service (or maybe food)!

So, if you've followed me this far, you can see that fuzzy logic excels at creating nonlinear multidimensional functions in a way that humans can relate to (ie, in a way that matches our decision-making process). It produces real number outputs from real-number inputs, and it has a firm mathematical basis (that you can look up if you want, I'm satisfied that it works). I hope you can see all of the potential uses for this, because my hands are getting tired from typing so I'm signing off. Tune in later for some practical controls-related uses of fuzzy logic.

Sunday, December 28, 2008

Timekeeping Cont'd

As the idea has been rolling around in my head I've thought up some logical extensions. Both timekeeping units - master and slave - could be implemented in programmable logic, probably a CPLD. The slaves could have an internal delay oscillator (several inverters in a row) which would be the basis of measurement of the incoming clock signal. The slaves could also do clock doubling or tripling of the incoming clock signal to provide a fast clock to whatever programmable logic or microcontroller is their client. That would be accomplished by use of the internal timer/counter in the timekeeping slave unit - determine how many ticks the external period is in your internal clock, then divide by 2,4,8,16, whatever and get a faster clock that OUGHT to be fairly correct compared to the incoming clock signal. The unit could also provide the bare external clock signal (suitably buffered) for use with an RTC timer/counter on the client device.

I was also thinking that due to all of that transmission line stuff that I try to ignore it might be better to transmit the clock signal as a sine wave. Doing that with programmable logic would be harder, but it might be required in certain circumstances. Certainly a differential signal is probably necessary in most environments. I would say that repeaters might be necessary, but repeaters will introduce delay. It might not be too much but it wouldn't be consistent. You may hook one slave up after a single repeater, and hook another up after 10 repeaters, and the signal will be more delay for the second slave.

I'm beginning to wonder if this is patentable. In my miniscule experience (<2 years in the controls field) I haven't seen anyone use this system, nor have I seen anyone attempt to synchronize different subsystems to this degree. Usually if you want everything to be on the same clock you put it in the same unit - programmable logic, microcontroller, whatever. For hard real time applications that's pretty necessary. The question is whether people have thought of this but ignored it, not thought of it, or not thought it practical?

Saturday, December 20, 2008

Timekeeping

Recently I've been designing an embedded hard real-time environment for controls purposes in my head. I've gotten somewhat detailed with it and you can see some of the plans I've made here: http://steves-wiki.wikispaces.com/ Look at the microcontroller architecture headings (and look at everything else while you're there). It's not finished yet but I think I have some good ideas down there. One of the major issues in a hard real-time system is timekeeping. If you have two or more chips of any type (microcontrollers, programmable logic, RTC, etc) that need to keep or be aware of time then you have a problem.

Ideally there is a 'time' right now. December 20, 2008 7:22:33.44 PM. We humans need to coordinate times on the level of minutes usually. Our clocks are always minutes off of each other and we still function well enough, but control systems need to keep accurate timing on the order of hundredths of a second if not less. As my mentor likes to say "In a real-time system if it's late, it's wrong." We have accurate timekeeping hardware for embedded chips. Crystals are very accurate if used correctly, so just attach it to your controller chip and go. There's only a problem when your system consists of multiple chips with multiple clocks. Even if they all have accurate crystals still all have to be accurate to each other. One chip is doing the controlling and if it needs data from different chips or systems then it MUST be there before it has to send out its next control update or at the very least you'll have degraded performance. Not only must each part have an accurate clock, they all must have the SAME clock.

How do you do this? Off the top of my head I envision a timekeeper, maybe a small microcontroller with an RTC. It will keep accurate time and transmit the current time to each subsystem that needs it. Great! Except not. Serial messages take time to create and send, that's delay. That means when you send your message with the 'time' in it, it's not the real time anymore. If you can characterize this delay and you know that it's insignificant compared to your timekeeping rate then you might be OK. But then you need to have a dedicated serial port for the timekeeper, or use a bus (but then you have to deal with bus contention, possibly delayed time messages, etc). Further, what happens if your messages don't get through? You'd need some kind of ACK response from each sub system, then your timekeeper has to process those. Even then if you don't get an ACK what do you do? Resend and hope for the best. Throw a fault to your superior if you consistently don't get a response.

Alright, let's go a little deeper into this serial idea - I like it. Let's assume that the time is represented with a 16-bit value that is the count of milliseconds since the system started keeping track of time. Our control system's sample time is 10ms, so we'll send time updates every .5ms. With a message structure of 8 bits, no parity and one stop bit, that will be 10 bits total for every data byte, and two bytes of data equals 20 bits. 20 bits times 2 is 40 bits every millisecond, and then multiply that by 1000 for the number of bits per second, and it's 40kbits. That's doable, but we need some overhead and some time in between messages to respond and process, so at least double and probably triple it, find the nearest baud rate and you've probably got 115.2Kbits. Still doable.

Of course every subsystem still has to have a crystal to support serial communication, you use up a serial port, and generally I just don't like this solution too much. Too kludgy, too imprecise, too wasteful. So naturally I'm about to propose a more wasteful but not kludgy and imprecise method (and it will be somewhat more robust).

My method involves a unit that is the timekeeper unit. It has a very accurate crystal and RTC. It will be especially protected from temperature variations. It keeps accurate time and generates a clock signal of say 100KHz. It will be a square wave, probably made differential or somesuch to improve transmission characteristics. Each subsystem will use this signal as the clock into a timer which it will use to keep track of the current timestamp. The timekeeper will have a control line with a pullup that the timekeeper holds low. Each subsystem monitors this line and keep count with the clock signal as long as it's low. Each subsystem is also tied to an open-collector ACK line. Whenever they lose the clock signal they pull it low and the timekeeper signals a fault or does something to correct the situation. If the timekeeper goes away then the control line will go high and let all of the subsystems know. At this point the subsystems go independent: they've been measuring the clock signal with respect to their own internal clocks and can keep fairly accurate time now without the timekeeper (for a while anyhow). When the timekeeper comes back it sends a special signal on the control line and the subsystems know to reset their timestamps to 0 and pick the clock signal up again.

Is this a great system? No. It only works in specific situations - if you have multiple subsystems in a control system that are all actively involved in the process of creating a control signal, you need to know absolute time and not just absolute time differences, and all of the subsystems are far removed enough from each other to make this worthwhile (probably not on the same PCB). Otherwise this could be a cute four-wire timekeeping system.

Thursday, December 11, 2008

Finally some anger

I'd like to share with you something that makes me angry. I'm sure all of you who are engineers have some specific talent or area that you excel in. My specialty is control systems. For those of you who don't know what control systems are let me explain. You know what cruise control is right? Set a speed and your car presses the gas or depresses it to make the car go the right speed. That's a control system: desired output, error, correction. Designing a control system can be easy or hard. For cruise control it's probably not too hard. Heck you can probably get away with something like 'IF CAR IS GOING TOO FAST DON'T PRESS DOWN ON THE GAS. IF IT'S GOING TOO SLOW PRESS DOWN ON THE GAS'. That's a fairly dumb control system, and any engineer could conceive of it and implement it fairly easily.

But if it gets any more complex, or things don't work out like you planned (ie, your car wildly revs and slows your car) you have to retreat and use MATH. That's control theory: how to use math to figure out how to make systems (anything that can be described as a differential equation, this includes physical, electrical - in fact almost anything even if you have to dumb it down) behave exactly how you want them to. The key in that last sentence is math. If something goes wrong with your cruise control system you could 'use math' to change your system to be something like 'IF CAR ISN'T GOING THE RIGHT SPEED PRESS DOWN ON THE GAS BY A*ERROR'. This WILL work better. But you don't know why. The reason is control theory, and until you understand what it is and how it works your cruise control just won't work right.
That is what controls engineers do - they use some tough math to make things behave correctly. It's not easy, it takes a long time to learn and a longer time to perfect. I have a master's degree in controls engineering, so trust me. Trust me also, that job postings like this make me angry:

An aluminum manufacturing company is seeking an ELECTRONIC CONTROLS ENGINEER. Candidates must have 2 - 5 years experience with Allen Bradley PLC's in a manufacturing environment. Job responsibilities include programming process control systems, calibrating, repair and troubleshooting plant instrument, electrical and control systems. A Bachelor's Degree in Electrical Engineering is required. Excellent benefits package available including matched 401k, company-shared health/dental, and paid life insurance. Salary is commensurate with experience.
What's a PLC? I never heard of that in my controls classes. Processes? Plant instrumentation? What are the inputs to my system? What am I controlling? Temperature? Shaft position?

Oh that's right. This job posting is abusing terms. They want an electronic controls engineer, but what they mean is a process controls engineer or manufacturing engineer. Their goal is process control: if I have a conveyor belt I need to know how fast it should go, where things on it are, what actions I have to perform now, etc. That's automation, and it's cool. PLC's are microcontroller systems with some nifty serial interfaces and analog components such as relays, TTL drivers, etc all built-in. Sometimes they use C for programming, sometimes they use BASIC. I know, ew, but it gets the job done. And it's a job that needs doing. But it's not controls engineering!

You couldn't take the person that automates that factory and put him in my chair. I've designed antenna control systems that can point to within an accuracy of .7 degrees using an embedded processor. I've modeled an entire dish antenna system (including mechanical, electrical and software components) in Simulink. These two things are NOT the same job. I'm not blaming anyone or saying anyone's at fault, but it's very frustrating. Ya'll feel me?

Monday, December 8, 2008

Wire Lists, Revisited

More wirelist fun at work today. I just got introduced to an even more complex and unwieldy and hard to understand wirelist format. It's very daunting - especially concerning the sheer amount of information I have to absorb to create such a list effectively. To give you an idea, I have at least 15 connectors on my testing unit with probably an average of 25 contacts each. these are brought straight through to eight larger more populated connectors that range from high-current connectors wil 20 contacts to low-current low-voltage connectors with a max of 192 contacts. Most of these are utilized. Then, the doohickey that plugs into THAT eight-connector monstrosity has several complications: wiring on its inside to connect signals, and multiple cables and connectors coming off of one plug doohickey. Then it's finally the unit under test with its 15+ connectors. And in between the doohickey and the UUT I have to keep track of which wires are twisted, gauges, colors, etc. Furthermore, this process embodies the problem I stated in the original wire list post: The same information is stored in different methods in different files. Very much ripe for errors.

Of course this is a good thing. I need to know that my XML scheme can entirely define all the information I need to reproduce all of the wirelist files I have at my disposal. This is a very complicated system and if I could represent it I'd be happy. Already I've made several changes based on what I've seen so this should be good experience.

Sunday, December 7, 2008

Printers

My wife and I just got done writing, printing folding, stuffing, posting and addressing about 60 holiday letters to various friends and family, some of them rather distant ('Janet? Ok, so if Arnie is my great-uncle, that's my grandfather's brother, Janet is the wife of one of his kids. Yeah they get a letter). I am continually amazed by my printer's (HP Photosmart C4280) ability to stop working reliably when I have a large task for it to perform. Sometimes it doesn't pick up paper, sometimes it doesn't print straight. Sometimes there's roller marks on it. But ONLY when I ask it to do something significant.

It's a good printer. I got it to replace my old Deskjet 932C which broke horribly when I asked it to do my wedding programs. Maybe it's just that I put odd paper into it at these times. Or maybe it's a conspiracy. I'm voting for conspiracy - after all printer ink is a conspiracy isn't it? (Although this printer's ink is actually cheaper than the last printer's) I just spent $75 in printer ink to prepare for this Christmas letter, and sure enough, it needed both cartridges changed.

What do you do to combat this evil? Buy in bulk? No dice, ecause then your printer will break and you'll have to get print cartridge #80 instead of print cartridge #75 (both manufactured by HP of course, why is there a whole WALL of different types of cartridges?). Then you'll be let with a lot of useless cartridges. Could you perhaps buy online to find a lower price? It's probably lower online, sure, but can you wait a week to get it? I usually buy ink when I run out and I need it for a big job, like today. So waiting isn't an option. Get a laser printer? Cost, and B&W only. Color laser printers are awfully expensive, and let's face it - you don't print that much at home. If you do, like you have a business, yeah, buy a laser printer and write it off. But for a home user? Naw, I rarely print until I print a lot. Then I spend a lot of money.

So what should I do? Nothing. HP and the other print companies have our number. They've planned this ink-debacle perfectly. And quite frankly I don't care. They've structured their whole business around the way I buy and use ink. So they made it expensive. Money isn't the only thing I have to optimize. The printer by and large works, and it has a scanner/copier in it! Score! I have simple needs. When I print large jobs I waste a bit of paper and have to buy new ink. It happens so infrequently that I honestly dont' care. I could more profitably care about beer. What if I'm out of beer? That matters more to me than ink, and HP knows it. They ought to include a coupon for a 24 pack of Miller with every ink cartridge. Hey, two birds with one stone.

Thursday, December 4, 2008

Oh wire lists!

As an electrical engineer, wire lists are the bane of my existence. Let me give you an example:

Suppose that you have a DB9 connector (that's an old serial port connector for those of you not in the know) and connected to it are several LEDs: LED1, LED2, LED3, etc. We seek to organize and list the various pins, connectors, and wires that are associated with this scheme. So, the first list we make is a pinout of the DB9:
Pin,Signal

  1. +5V

  2. LED2

  3. LED3

  4. LED6

  5. LED1

  6. LED4

  7. LED5

  8. GND



Just like in real life, this list is not simple. Wouldn't it be great if, for instance, LED1 was on pin 1, LED2 was on pin 2, etc? Not only is that not the case, I didn't even put the LEDs in numerical order! Woe is me! Why am I being so mean to myself? Because that's the way real life is sadly, plus it will all turn out in the end if I have my way anyhow.
So there's my pinout, I'll stick it in an Excel pinout file. But now I want to view this information by LED number, so I make another file that looks like this:
LED #,pin

  1. 5

  2. 2

  3. 4

  4. 6

  5. 7

  6. 9


Great! Now I'm organized. So if I want to make a diagram of the connector I'll just head to the file that's ordered by pin number and draw that out. Then when I'm going to write my code to turn the LEDs on I'll refer to the list ordered by LED number and use that to determine what value I have to shift to an output register to turn that LED on. Then everything will work perfectly and my documentation will match reality AND my code.

Except, oops, it doesn't. Look at LED6. In the list ordered by pin number I put it on pin 4, but in the list ordered by LED number I put it on pin 9. Maybe it was my handwriting - after all 4's look like 9's if you're sloppy. Now I have a diagram that shows LED6 on pin 4, but in my code I assume it's on 9. That LED will not light and I get to spend hours trying to figure out why.

What's the fundamental problem here? We have what should be the same information represented two different ways. But instead we have two separate sets of information each represented different ways. When you split the two lists up with nothing to keep them synchronized and nothing to provide a sanity check between them you're setting yourself up for headaches.

People do this every day. It doesn't always lead to tragedy but it sure does lead to aggravation. What can be done about it? You could use a database. I'm not such a huge fan of databases. I'm sure that that all of my reasons are susceptible to 'yes but's and 'not really's but I've always found them overcomplicated, slow, too confining and difficult to use. Plus if I told people to use databases they might accidentally use Access. And let me tell you: in my experience the only thing worse than misusing Excel as a database is using Access as a database instead.

My preferred method is XML. However XML is so big and vague and useless that it's just not worth it. There are no schemas that define how to write out wire lists and there are no programs to view the resulting XML. That is why I'm writing them.

What I've figured out so far is to use the following organization:

  • Signal list - this details the names of all the signals present in the wire list (like LED1 above). Each signal will be name and you will be able to attach voltages, currents and other electrical properties to them

  • Connector - this will define the type of connector, part number, pin type, gender, refdes, etc. It will have a pinlist under which each pin is assigned a signal from the signals list, or N/C

  • Cable - this will define the wires and connectors. It will reference two or more connectors from the connector list and will have a wirelist section. Inside the wirelist there will be wires, each of a specific type (twisted shielded pair, solid conductor, etc), color, part number, etc. Inside the wires are conductors which are linked to signals from the signal list

Got it? Connectors->pins->signals. Cables->wires->conductors->signals. Signals->electrical characteristics. Everything links together. Let me give an example of a signal list:

<signallist>
<signal>
<name>Odd_AC_Signal</name>
<voltage type="AC" waveform="sine">
<name>AC Portion</name>
<amplitude value="115" tolerance="1" unit="V" measurement="RMS" reference="GND"/>
<frequency value="60" tolerance=".1" unit="Hz"/>
<phase value="0" tolerance="0" unit="degrees"/>
<voltage type="DC">
<name>Offset</name>
<magnitude value=" 200=" tolerance="10" units="V" reference="GND">
</voltage>
</signal>
</signallist>


And here's the connector:


<connector>
<refdes>J4</refdes>
<name>LED Connector</name>
<type>DB9</type>
<partnum>M24-09</partnum>
<gender>M</gender>
<pinlist>
<pin pos="5" signal="LED1">
<pin pos="1" signal="LED2">
...
</pinlist>
</connector>

And then the cable:

<cable>
<name>LED Cable</name>
<refdes>K4</refdes>
<partnum>32345</partnum>
<connector>J4</connector>
<wirelist>
<wire type="SC">
<conductor signal="LED3" color="brown"/>
</wire>
<wire type="TP">
<conductor signal="LED1" color="blue/white"/>
<conductor signal="LED2" color="blue"/>
</wire>
</wirelist>
</cable>

I think the cable definition is especially nice because you can see which conductors are twisted, what color each conductor is, etc.

Naturally this isn't all fleshed out yet, but you can see the possibilities. From this information you can make almost any document you'll find necessary: tables can be made with HTML or FO/PDF, wiring diagrams can be made with SVG. And you only write it out once, then the XSL transformation will handle the rest - putting signal names to pins or wires, creating a connector pinout or a cable pinout, etc. That means fewer places to mess up. I think it's a good idea, but it will take a lot of work. Right now I'm defining the XML schemas for everything above. When that is done I'll be able to write an XML file that has all of the information in it. Then from that point I just have to write XSL transformations that turn it into output documents.

It is a lot of work, but I think worth it.

Wednesday, December 3, 2008

I just got back from a trip to California for Thanksgiving. I live in Florida. In case you're not familiar with geography, that's a long way. Let me outline what we went through to get there:

To California:

  • 2AM - Melbourne to Orlando Airport, arrive by 3:45AM

  • 3:45AM - Park in the satellite parking and take a bus to the terminal

  • 5:00AM - Flight to Atlanta

  • 7:30AM - Two hour layover in Atlanta

  • 9:30AM - Atlanta to Orange County Airport (5 hours!)

  • 11:15AM - Arrive at Orange County Airport, pick up luggage and take a taxi to the train station

  • 11:30AM - Arrive at train station, eat something and wait until 1:45PM for the train

  • 1:45PM - Train is late, wait until 2:15PM

  • 2:15PM - Train to Guadalupe station (5 hours again!)

  • 8:00PM - Arrival at sister's house, very tired



On the way back we got luckier:


  • 2:30PM - Board train

  • 2:45PM - Buy new tickets on the train because the ticket machine at the station doesn't work and we're in a cellular dead zone so they can't call HQ to verify our ticket (at least they cheerily refunded the old tickets)

  • 7:30PM - Arrival at station, take bus to LAX airport (nice service)

  • 8:15PM - Arrival at LAX, security, etc

  • 9:00PM - $11 margarita, $11 entree at an airport restaurant (the margarita was good)

  • 10:15PM - Flight to Orlando (direct!)

  • 6:00AM - arrive at Orlando, pick up luggage, take bus to car

  • 7:30AM - arrive at home in Melbourne, tired, take a sick day because California is too dry for my sinuses and they're angry


For those of you keeping score, it's 19 hours out there, 14 hours back. Moral of the story: when at all possible get direct flights.

Added bonus: trains are pretty nice. They have electrical outlets in every seat. I learned how to play RA3 with a trackpad. I highly recommend the train if you're headed in that direction and its' cheaper than a flight. Again, HIGHLY recommend the train, even if it is filled with highschoolers.

Tuesday, December 2, 2008

I can haz irony?

Well I started a blog. I always hated blogs but I suppose I can't withstand the Web 2.0 any longer. Also I hear you can make money with these, somehow. I seek to monetize my anger, thus, I have a blog. I think that's the definition of the internet.

One of my goals in this blog (other than time-wasting) is to write about things that interest me. I interest myself mainly for technical thingies and my preferred topic of the day is DocBook.

In theory DocBook is a good idea. The idea is to take all of the content you put in your document and enclose it in XML tags which determine layout and formatting for you. Take Word for example. When you write something in Word the content and the medium are directly intertwined: you can't (as far as I know) get to a mode in Word where you don't have to worry about page breaks and tab spacing. Everything that you see in the Word window will be there on the print page. If you've been playing the document-creation game for some time then you know that Word is a WYSIWYG (What You See Is What You Get) editor. A WYSIWYG editor is a very good thing. I may not be an old-timer but I've worked with computers long enough to remember when there were WYSINAAWYG editors (What You See Is Not At All What You Get). Trust me, they were a pain. With so many surprises every time you tried to print something. Without WYSIWYG editors desktop publishing would not exist.

DocBook takes a different approach. Rather than start off with the end product (ie, how does the page look? What are the margins? What point font do I use? etc) it chooses to focus on the content and meta-information first and formatting second. If you want a book you start off with a tag and then some tags and all the text goes in a tag and so on. There's special tags for cross-references, figures, acronyms, empahsis, etc. Trust me, if you've seen it done in a book somewhere there's probably a tag for it in the DocBook standard. After you've created all of the content you verify it against the standard, then run it through a converter and get some kind of print output - maybe a PDF, HTML, Help file, etc. Since it's XML you could also theoretically create a transformation to OpenOffice Document or Word XML Document (I've seen some rudimentary Word XML transformations but nothing great). THAT file is your WYSIWYG copy, tada! You're done!

Well, you're really not. The chapter titles look like 'Chapter 1 - The Phantom Meanace' where you wanted them to look like '1- The Phantom Meanace', and you wanted a bigger font for the body text, and when you want to emphasize text you'd like bold AND italics.... In short it doesn't look like you want it. Now you've met the meat of DocBook - customization. By default DocBook outputs don't look so... custom. They're bland and boring, and I'm sure the spacing is off by a bit. The good news is that there are options for some of the changes you want like numbering the chapters. They're easy to set - just put the options you want in an XSL file, include it in your conversion, and it'll work! The bad news is that for a lot of the more minor issues you get to write all-new XSL code and figure out just what the property or attribute you're looking to change is called, then maybe find it in the DocBook XSL files, copy and paste to a custom XSL file, change what you want, try again, change, try, change... It is not easy. It is not straightforward. Get your Google and your patience ready if you want to significantly change DocBook's default output.

So why use DocBook? It seems to be a step backwards towards YHNIWYWG (You Have No Idea What You Will Get) and YHNCOWYWG (You Have No Control Over What You Will Get, also known as the Outer Limits editor). In some respects it is undesirable. However, consider that once you have the formatting correct, it will ALWAYS be correct. One knowledgeable person can create the formatting rules and then any number of people can use them flawlessly thereafter. In a large organization with a need for a standard formatting this can be a real timesaver.

DocBook files are text. Plain ol' text. They're also XML. Use your favorite text editor or programming GUI. I like Notepad++ - it will do the tabbing and tag completion for me! If I need, I can create a python script to read the DocBook XML files and parse them for information, or edit them, or do a simple search and replace. I can create a python script to retrieve information from a database and format it into DocBook XML. Text is also version control friendly.

Consider also that creating DocBook is free. Free as in beer, maybe free as in freedom, I haven't done my homework. With a budget of $0 I can create a PDF from raw text in under an hour. The tools I prefer are free, there are books you can buy but there are also many online resources, free. Word, in contrast, is not free. OpenOffice is, but am I the only one who hates its interface? I don't like using it honestly.

DocBook is write once, publish many: once you've written a DocBook XML file you an convert it many different formats without any additional work.

DocBook encourages reuse and portability: you can include other DocBook files to reuse common sections such as titlepages. You can create an XSL transform to transform any XML data into a DocBook format. Got an HTML table you want in DocBook format? You can make a transform to do it in a jiffy. Got a CSV file? Write a python script to generate a table from it, somewhat jiffily. Got data in a database? Python again FTW. How much data do you automatically want to include in your DocBook XML file? Create a batch file or script to retrieve the most recent data from published sources, transform it into DocBook XML, make sure it is included in your document, then transform your DocBook into your final published format.

Ok, so most of that is a pipe dream that will take LOTS of effort to set up, but remember, once you have a system in place and documented, that system stays there. Put the knowledge in the world, put the process in the world and it won't get lost, and you wont' have to remember it yourself.

For more information on how you (and by you I mean a Windows-using engineer) can get started with DocBook visit my DocBook wiki at Steve's DocBook Reference