documentation

17 Articles

Tldr-pages Keeps It Short, Wherever You Need It

December 14, 2024 by 15 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 27 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!

Share Your Projects: Leave Breadcrumbs

August 9, 2023 by 20 Comments

I’ve talked about a low-effort way to document your projects by taking plenty of pictures, and about ways that your PCBs could be documenting themselves. Today, let’s talk about a quick and easy way that you could help other hackers as you go through your own hacking adventures — leaving breadcrumbs.

In short, breadcrumbs are little pieces of crucial information that you had to spend time to figure out. They are solutions to problems that another hacker just like you could stumble upon in the future, something that you perhaps wish you didn’t have to figure out on your own, and certainly something that others won’t need to spend time figuring out.

Breadcrumbs are about saving time, for you and others. It helps if you think of your solved problems in terms of time spent. If you figure out a small problem and then publish your solution, you might be saving half an hour, a full hour, or a good few hours of time another hacker that’s could even be less experienced in debugging than you. In fact, your breadcrumb might even make a difference between someone completing a project and abandoning it!

However, there’s also the trade-off of taking time to document something. If you can’t publish your solution in a few minutes’ time, it might become much harder to persuade your brain to publish the next time you have something notable. Here’s a guideline: if you’ve just figured out a cool terminal command that helps you solve a certain kind of problem, you should have a quick way to publish that command within a minute. The good news is, the internet has a hundred different places you could easily share your findings, depending on the kind of problem you’ve solved! Continue reading “Share Your Projects: Leave Breadcrumbs” →

Well Documented Code Helps Revive Decades-Old Commodore Project

June 7, 2023 by 15 Comments

In the 1980s, [Mike] was working on his own RPG for the Commodore 64, inspired by dungeon crawlers of the era like Ultima IV and Telengard, both some of his favorites. The mechanics and gameplay were fairly revolutionary for the time, and [Mike] wanted to develop some of these ideas, especially the idea of line-of-sight, even further with his own game. But an illness, a stint in the military, and the rest of life since the 80s got in the way of finishing this project. This always nagged at him, so he finally dug out his decades-old project, dusted out his old Commodore and other antique equipment, and is hoping to finish it by 2024.

Luckily [Mike’s] younger self went to some extremes documenting the project, starting with a map he created which was inspired by Dungeons and Dragons. There are printed notes from a Commodore 64 printer, including all of the assembly instructions, augmented with his handwritten notes to explain how everything worked. He also has handwritten notes, including character set plans, disk sector use plans, menus, player commands, character stats, and equipment, all saved on paper. The early code was written using a machine language monitor since [Mike] didn’t know about the existence of assemblers at the time. Eventually, he discovered them and attempted to rebuild the code on a Commodore 128 and then an Amiga, but never got everything working together. There is some working code still on a floppy disk, but a lot of it doesn’t work together either.

While not quite finished yet, [Mike] has a well-thought-out plan for completing the build, involving aggregating all of the commented source code and doing quarterly sprints from here on out to attempt to get the project finished. We’re all excited to see how this project fares in the future. Beyond the huge scope of this pet project, we’d also suggest that this is an excellent example of thoroughly commenting one’s code to avoid having to solve mysteries or reinvent wheels when revisiting projects months (or decades) later. After all, self-documenting code doesn’t exist.

Continue reading “Well Documented Code Helps Revive Decades-Old Commodore Project” →

Motion Canvas Helps Get Your Point Across

June 5, 2023 by 1 Comment

Generating videos for projects can be difficult. Not only do you have to create the thing, but you film the process and cut it together in a story that a viewer can follow. Explaining complex topics to the viewer often involves a whiteboard of some sort, but as we all know, it’s not always a perfect solution. [Jacob] was working on a video game and making videos to document the progress and built a tool called Motion Canvas to help visualize topics like custom shaders. A few months ago, he decided to release it as an open source project.

Since then, it has seen quite a few forks and GitHub forks with a lively showcase on the community Discord. Looking at the docs, it is pretty easy to see why. The interface allows you to write procedural animations using the async semantics of TypeScript while still offering the GUI interface we expect from our video editors. In particular, the signal system allows dependencies to be defined between values. The system runs in Node, and the GUI runs in your browser locally while you edit the files in your terminal/notepad/IDE. CSS and Flexbox are available as the video is rendered to a web canvas and then compiled into a video via FFMPEG. The documentation is quite extensive, and it’s a great example of a tool someone built to fit a need they had going on to become something a little more fantastic.

This isn’t the first time we’ve discussed how to share your projects with the world, and we’ll freely admit we have a bit of bias toward encouraging folks to document their projects.

Continue reading “Motion Canvas Helps Get Your Point Across” →