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
- +5V
- LED2
- LED3
- LED6
- LED1
- LED4
- LED5
- 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
- 5
- 2
- 4
- 6
- 7
- 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
<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.
No comments:
Post a Comment