Share Your Projects: Imperfectionism

Everyone has a standard for publishing projects, and they can get pretty controversial. We see a lot of people complain about hacks embedded in YouTube videos, social media threads, Discord servers, Facebook posts, IRC channels, different degrees of open-sourcing, licenses, searchability, and monetization. I personally have my own share of frustrations with a number of these factors.

It’s common to believe that hacking as a culture doesn’t thrive until a certain set of conditions is met, and everyone has their own set of conditions in mind. My own dealbreaker, as you might’ve seen, is open-sourcing of code and hardware alike – I think that’s a sufficiently large barrier for hacking being repeatable, and repeatability is a big part of how hacking culture spreads.

This kind of belief is often self-limiting. Many people believe that their code or PCB source file is not a good contribution to hacking culture unless it meets a certain cleanliness or completeness standard. This is understandable, and I do that, too.

Today, I’d like to argue against my own view, and show how imperfect publishing helps build hacking culture despite its imperfections. Let’s talk about open-source in context of 3D printing.

Continue reading “Share Your Projects: Imperfectionism”

Who Is Your Audience?

Here at Hackaday HQ, we all have opinions about the way we like to do things. And no surprise, this extends to the way we like to lay out circuits in schematics. So when we were discussing our own takes on this piece on suggested schematic standards, it was maybe more surprising how much we did agree on than how much we had different preferred styles. But of course, it was the points where we disagreed that provoked the most interesting discussion, and that’s when I had a revelation.

Besides torturing electronics, we all also write for you all, and one thing we always have in mind is who we’re writing for. The Hackaday audience, not to blow you up, is pretty knowledgeable and basically “full-stack” in terms of the hardware/software spectrum. This isn’t to say that everyone is a specialist in everything, though, and we also have certain archetypes in mind: the software type who is just starting out with hardware, the hardware type who isn’t as savvy about software, etc. So, back to schematic layout: Who is your audience? It matters.

For instance, do you organize the pinout for an IC by pin number or by pin function, grouping the power pins and the ADC pins and so on? If your audience is trying to figure out the circuit logic, you should probably go functional. But if you are trying to debug a circuit, you’re often looking at the circuit diagram to figure out what a given pin does, and the pin-number layout is more appropriate.

Do you lay out the logical flow of the circuit in the schematic, or do you try to mimic the PCB layout? Again, it could depend on how your audience will be using it. If they have access to your CAD tool, and can hop back and forth seamlessly from schematic to PCB, the logical flow layout is the win. However, if they are an audience of beginners, or stuck with a PDF of the schematic, or trying to debug a non-working board, perhaps the physical layout is the right approach.

Al Williams, who has experience with projects of a much larger scale than most of us self-taught hackers, doesn’t even think that a schematic makes sense. He thinks that it’s much easier to read and write the design in a hardware description language like VHDL. Of course, that’s certainly true for IC designs, and probably also for boards of a certain complexity. But this is only true when your audience is also familiar with the HDL in question. Otherwise, you’re writing in Finnish for an audience of Spaniards.

Before this conversation, I was thinking of schematic layout as Tom Nardi described it on the podcast – a step along the way to get to the fun parts of PCB layout and then to getting the boards in hand. But at least in our open-source hardware world, it’s also a piece of the documentation, and a document that has an audience of peers who it pays to keep in mind just as much as when I’m sitting down and writing this very newsletter. In some ways, it’s the same thing.

(And yeah, I know the featured image doesn’t exactly fit the topic, but I love it anyway.)

pinout leaf

Pinoutleaf: Simplifying Pinout References

We all appreciate clear easy-to-read reference materials. In that pursuit [Andreas] over at Splitbrain sent in his latest project, Pinoutleaf. This useful web app simplifies the creation of clean, professional board pinout reference images.

The app uses YAML or JSON configuration files to define the board, including photos for the front and back, the number and spacing of pins, and their names and attributes.For example, you can designate pin 3 as GPIO3 or A3, and the app will color-code these layers accordingly. The tool is designed to align with the standard 0.1″ pin spacing commonly used in breadboards. One clever feature is the automatic mirroring of labels for the rear photo, a lifesaver when you need to reverse-mount a board. Once your board is configured, Pinoutleaf generates an SVG image that you can download or print to slide over or under the pin headers, keeping your reference key easily accessible.

Visit the GitHub page to explore the tool’s features, including its Command-Line Interface for batch-generating pinouts for multiple boards. Creating clear documentation is challenging, so we love seeing projects like Pinoutleaf that make it easier to do it well.

IFixit Releases Command Line Docs For FixHub Iron

When we reviewed the iFixit FixHub back in September, one of the most interesting features of the portable soldering station was the command line interface that both the iron and the base station offered up once you connected to them via USB. While this feature wasn’t documented anywhere, it made a degree of a sense, as the devices used WebSerial to communicate with the browser. What was less clear at the time was whether or not the user was supposed to be fiddling with this interface, or if iFixit intended to lock it up in a future firmware update.

Thanks to a recent info dump on GitHub, it seems like we have our answer. In the repo, iFixit has provided documentation for each individual command on both the iron and base, including some background information and application notes for a few of the more esoteric functions. A handful of the commands are apparently disabled in the production version of the firmware, but there’s still plenty to poke around with.

Continue reading “IFixit Releases Command Line Docs For FixHub Iron”

Keeping Track Of Old Computer Manuals With The Manx Catalog

An unfortunate reality of pre-1990s computer systems is that any manuals and documentation that came with them likely only existed on paper. That’s not to say there aren’t scanned-in (PDF) copies of those documents floating around, but with few of these scans being indexable by search engines like Google and Duck Duck Go, they can be rather tricky to find. That’s where the Manx catalog website seeks to make life easier. According to its stats, it knows about 22,060 manuals (9,992 online) across 61 websites, with a focus on minicomputers and mainframes.

The code behind Manx is GPL 2.0 licensed and available on GitHub, which is where any issues can be filed too. While not a new project by any stretch of the imagination, it’s yet another useful tool to find a non-OCR-ed scan of the programming or user manual for an obscure system. As noted in a recent Hacker News thread, the ‘online’ part of the above listed statistics means that for manuals where no online copy is known, you get a placeholder message. Using the Bitsavers website along with Archive.org may still be the most pertinent way to hunt down that elusive manual, with the Manx website recommending 1000bit for microcomputer manuals.

Have you used the Manx catalog, or any of the other archiving websites? What have been your experiences with them? Let us know in the comments.

Tldr-pages Keeps It Short, Wherever You Need It

Let’s face it, even the most accomplished console cowboy can’t keep everything memorized. Sure, you might know all the important arguments for a daily-use tool like tar or ls, but what about the commands you don’t use that often? For that matter, even if you do use tar every day, we bet you don’t know all of the options it supports.

Built-in documentation or the man pages are of course a huge help, but they are dense resources. Sometimes what you really need is to see just a few key examples. When that happens, check out the tldr-pages project and its array of front-ends. Whether you’re working remotely on an embedded gadget, or have the luxury of a full desktop OS and browser, the project offers a way to get the help you need as quickly as possible.

Continue reading “Tldr-pages Keeps It Short, Wherever You Need It”

Z80 I/O Madness

While the 8080 started the personal computer revolution, the Z80 was quickly a winner because it was easier to use and had more capabilities. [Noel] found out though that the Z80 OUT instruction is a little odd and, in fact, some of the period documentation was incorrect.

Many CPUs used memory-mapped I/O, but the 8080 and Z80 had dedicated I/O addressing pins and instructions so you could fill up the memory map with actual memory and still have some I/O devices. A quick look in the famous Zak’s book on Z80 programming indicates that an instruction like OUT (C),A would write the A register to the output device indicated by the BC register pair (even though the instruction only mentions C. However, [Noel] missed the note about the B register and saw in the Zilog documentation that it did. Since he didn’t read the note in the Zak’s book until later, he assumed it was a discrepancy. Therefore, he went to the silicon to get the correct answer.

Breadboarding a little Z80 system allowed him to look at the actual behavior of the instruction. However, he also didn’t appreciate the syntax of the assembly language statements. We’ve done enough Z80 assembly that none of it struck us as particularly crazy, especially since odd instruction mnemonics were the norm in those days.

Still, it was interesting to see him work through all the instructions. He then looks at how Amstrad used or abused the instructions to do something even stranger.

If you want to breadboard a minimal Z80 system, consider this one. If you enjoy abuse of the Z80 I/O system, you don’t want to miss this Z80 hack for “protected mode.”

Continue reading “Z80 I/O Madness”