Let's make circuit diagrams accessible: Part 3

This is part of a series of posts on automatically generating circuit descriptions. In part 1, I wrote about the problem I’m trying to solve by converting circuits to text. Part 2 describes where we can get some example circuits. Today we’re going to take a look at the fruits of my labor so far.

Example circuits

Here are a few Fritzing projects automatically described by the program I’m working on:

As you can see, each page follows the same format. First is the title and description pulled from the Fritzing website. Next is an automatically generated bill of materials (or BOM), which lists the parts you need to build the circuit. Then there are all the nets in the circuit, showing how it’s connected together. Finally we provide any additional detail about each part based on what’s in the Fritzing part library.

I tried to make the layout of the page as natural and useful as possible. Having the bill of materials first makes it easier to judge the complexity of the project, in addition to helping you check that you have all the required parts. When we have more details about a part listed in the BOM, you’ll get a link to the part details section. Similarly, each part in the connections section has a link to the BOM so you can quickly look it up (for example, you can follow the R1 link to find the resistance of R1). Finally each net in the net list has a checkbox, which you can mark to track your progress if you’re reading or building a long circuit.

What’s next

This is where the fun part begins! Now that I have a working prototype it’s time to get feedback. The questions I have are 1) is this useful, and 2) how could it be better? I’ll be reaching out to folks in the community to hear your thoughts.

Even with the ideal format (which I haven’t achieved here), it’s going to take practice to learn to understand circuits through these kinds of linear text descriptions. It may never be as natural as reading a visual or tactile diagram. Therefore, a major goal of this project is to re-ignite the conversation about ways to represent circuits with text, and to give us a way to prototype different representations quickly.

In addition to refining the format, I’d like to make it easier to discover finished, high-quality Fritzing projects. Right now many projects in the directory are rather low quality, and many don’t have a schematic layout (only breadboard, the describer doesn’t support). Often projects have missing elements that are clear when visually inspecting the project in Fritzing, but may be frustratingly non-obvious when just looking at the text description. I have been working on code to crawl through the Fritzing projects and separate the wheat from the chaff, so I can provide a directory of circuits with clear titles, descriptions, and net lists.

Finally, if you find a project on the Fritzing website that sparks your interest, let me know about it. You can email me at troy@blindmakers.net and I’ll try to convert the project for you.

Source code

For any developers out there, I’ve uploaded my source code to GitHub and will continue to share my progress. Right now the code is in the prototype stage and some parts are more robust than others. I recommend first looking at models.py to understand how I represent circuits internally. From there, fritzing_parser.py reads the circuit and performs the graph traversal to find nets, and describer.py does the relatively easy job of producing the output. The scraper and postmaker modules are my start at getting data directly from the Fritzing project website, and I used postmaker.py to generate the examples above.

by Troy