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”

“Cheap Yellow Display” Builds Community Through Hardware

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”