documentation

20 Articles

pinout leaf

Pinoutleaf: Simplifying Pinout References

May 2, 2025 by 10 Comments

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

January 11, 2025 by 16 Comments

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

December 24, 2024 by 4 Comments

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

December 14, 2024 by 16 Comments

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

January 19, 2024 by 26 Comments

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” →

“Cheap Yellow Display” Builds Community Through Hardware

October 28, 2023 by 29 Comments

For the most part, Hackaday is all about hardware hacking projects. Sometimes, though, the real hack in a project isn’t building hardware, but rather building a community around the hardware.

Case in point: [Brian Lough]’s latest project, which he dubs “CYD,” for the “cheap yellow display” that it’s based on; which is a lot easier to remember than its official designation, ESP32-2432S028R. Whatever you call it, this board is better than it sounds, with an ESP32 with WiFi, Bluetooth, a 320×480 resistive touch screen, and niceties like USB and an SD card socket — all on aforementioned yellow PCB. The good news is that you can get this thing for about $15 on Ali Express. The bad news is that, as is often the case with hardware from the Big Rock Candy Mountain, the only documentation available comes from a website we wouldn’t touch with a ten-foot pole.

To fix this problem, [Brian] started what he hopes will be a collaborative effort to build a knowledge base for the CYD, to encourage people to put these little gems to work. He has already kick-started that with a ton of quality documentation, including setup and configuration instructions, tips and gotchas, and some sample projects that put the CYD’s capabilities to the test. It’s all on GitHub and there’s already at least one pull request; hopefully that’ll grow once the word gets out.

Honestly, these look like fantastic little boards that are a heck of a bargain. We’re thinking about picking up a few of these while they last, and maybe even getting in on the action in this nascent community. And hats off to [Brian] for getting this effort going.

Continue reading ““Cheap Yellow Display” Builds Community Through Hardware” →

Horrendous Mess Of Wires

September 30, 2023 by 21 Comments

When do you post your projects? When they’re done? When they’re to the basic prototype stage? Or all along the way, from their very conception? All of these have their merits, and their champions.

In the post-all-along-the-way corner, we have Hackaday’s own [Arya Voronova], who outlines the many ways that you can start documenting your project before it’s even a fully fledged project. She calls these tidbits “breadcrumbs”, and it strikes me as being a lot like keeping a logbook, but doing it in public. The advantages? Instead of just you, everyone on the Internet can see what you’re up to. This means they can offer help, give you parts recommendations, and find that incorrect pinout that one pair of eyes would have missed. It takes a lot of courage to post your unfinished business for all to see, but ironically, that’s the stage of the project where you stand to gain the most from the exposure.

On the opposite end of the spectrum are the folks who document their projects at the very end. We see a ton of these on Hackaday.io and in people’s personal blogs. It’s a great service to the community, frankly, because at that point, you’re already done with the project. This is the point where the reward, for you, is at its minimum, but it’s also the point where you feel least inhibited about sharing if you’re one of those people who are afraid of showing your work off half-done. The risk here, if you’re like me, is that you’re already on to the next project when one is “done”, and going back over it to make notes seems superfluous. Those of you who do it regardless, we salute you!

And then there’s the middle ground. When you’re about one third of the way done, you realize that you might have something half workable, and you start taking a photo or two, or maybe even typing words into a computer. Your git logs start to contain more than just “fixed more stuff” for each check-in, because what if someone else actually reads this? Maybe you’re to the point where you’ve just made the nice box to put it in, and you’re not sure if you’ll ever go back and untangle that rat’s nest, so you take a couple of pictures of the innards before you hot glue it down.

I’m a little ashamed I’m probably on the “post only when it’s done” end of things than is healthy, mostly because I don’t have the aforementioned strength of will to go back. What about you?

This article is part of the Hackaday.com newsletter, delivered every seven days for each of the last 200+ weeks. It also includes our favorite articles from the last seven days that you can see on the web version of the newsletter. Want this type of article to hit your inbox every Friday morning? You should sign up!