Patternflow Pattern Guide

You built the device — now fill it. This guide covers one loop, end to end: pull patterns from the community onto your device, make your own in Pattern Lab, verify them on real hardware, and share them back.

Assembly and the first flash are BUILD_GUIDE.md. This guide is what comes after.

Rather do it than read it? patternflow.work/guide/make is the same loop as a hands-on tutorial: a practice community, your real Pattern Lab in a window, and a practice AI to take the two prompts.

0. Before you start
1. One concept: a pattern is a small file
2. A look around the community
3. Putting someone else's pattern on your device
4. Making your own in Pattern Lab
5. Verifying on your device
6. Sharing to the community
7. When something goes wrong

0. Before you start

A USB cable is for exactly one moment: the very first flash, with the ESP32-S3 out of the board, from Flash Patternflow at patternflow.work/pattern. Put the module in download mode first — hold BOOT, tap RST, let go of BOOT — then press the button. The Wi-Fi step usually does not appear after that first install, and that is expected: press RST, run Flash Patternflow again and choose Connect to Wi-Fi, or seat the module, power the panel and join the network it raises for itself, patternflow-xxxx (password patternflow), to set Wi-Fi at http://192.168.4.1/. From then on everything is wireless. Whether you're in the community or in Pattern Lab, every path a pattern takes to the device goes over Wi-Fi.

So this whole guide rests on one assumption: the device is powered on and on the same Wi-Fi network as your computer. If you haven't done the first flash and Wi-Fi setup yet, finish the firmware section of BUILD_GUIDE first, or the Play guide's Flash chapter, which walks it on a board you can turn.

You need	Why
An assembled, flashed Patternflow	It's what this guide is about
The device connected to Wi-Fi	The premise of every transfer here
Firmware v3.10.5 or newer (the flasher installs the current release)	Pattern modules (wireless install) need v3.2.0, the Basics pack v3.5.1, and the larger patterns, as they are built now, v3.10.5
A community account (optional)	Browsing, knobs and deck-building work without one. Sending to your device (building) and sharing / liking / forking need a sign-in

The device's page lives at patternflow.local. Android can't resolve .local addresses — use the IP shown on the device's NETWORK screen (hold K2) instead.

1. One concept: a pattern is a small file

Understand this one thing and everything else falls into place. A pattern travels to the device as a module — a .pfm file of a few KB — and arrives over Wi-Fi in seconds. The firmware is not rebuilt and nothing is reflashed.

The buttons wear slightly different names on different screens — Send to my Patternflow, SEND TO MY BOARD, Apply to my Patternflow — but they are all the same thing: compile this pattern into a module, hand it to the board.

Only Origin is built into the firmware, as the failsafe that lights the panel when storage is empty. Everything else you see on your device is a module you (or a deck) put there, and anything you install you can also delete.

Updating the firmware is a separate thing, and the device tells you when it matters: open patternflow.local, and if a newer release exists the console says so and links to patternflow.work/update, which hands the new build to your board over Wi-Fi. Your patterns, Wi-Fi networks and storage are untouched by it.

2. A look around the community

From the landing page's PATTERN tab, click Community ↗. (Or go straight to patternflow.work/community.)

The first thing you see is the wall — and every pattern on it runs on every Patternflow. You can play with all of it without an account.

What the wall does:

Hover and the pattern actually plays (the still image is only a preview)
While it plays, scroll to turn its knobs — your cursor's horizontal position picks which of K1–K4 you're holding
Ctrl + scroll resizes the cards
Search above the wall finds a pattern by its title, or by its author with @name
Sorting: Newest · Oldest · Most liked · Most forked · In decks, plus the .h Flashable now filter — an .h badge means the author uploaded a firmware header they verified on a real device, so the pattern can go straight onto yours

Some cards have no + (add to deck) button — that's not a bug. It means the author shared the pattern without an .h header, so it hasn't been verified on hardware yet. Only header-carrying patterns can be sent to a device, so only they get the +.

Click a pattern and you're on its detail page — the full code, knob sliders, and a row of buttons. Open in Pattern Lab pulls the pattern onto your own workbench to take apart and remix (a fork). Just note it for now; the next chapters use all of this.

One more thing in the top nav — Workshop is where directions get discussed and decided. It's under heavy construction, so this guide leaves it alone for now.

3. Putting someone else's pattern on your device

The fastest route to a first success. Two ways to do it.

3-1. A deck of several at once (recommended)

A deck is a set of patterns bound for the device. The device cycles patterns in order, so think of it as a setlist.

Press + on any pattern card you like, or drag the card down into the deck bar at the bottom of the screen. Up to 20.
Inside the deck, drag to rearrange, × to remove.
Press SEND TO MY BOARD at the deck's bottom right.
The build finishes in seconds — you'll see something like ✓ 4 modules · 32 KB. Press SEND OVER WI-FI.
The device's Patterns page opens and the modules upload themselves. When done ticks down the list, that's it — they appear on the device immediately.

⚠️ When this step fails, it is almost always one thing: the device is off, or on a different network than your computer. Power it on, check it's on the same Wi-Fi, and press again.

The Patterns page is also where you tidy up: tick the checkboxes and press Delete selected, or Select all first to clear the lot. Only Origin is built in (PRESET) and cannot be removed; everything else is a module you can delete freely.

Click a name to play it — the device switches immediately, which is the fastest way to remember what a pattern actually looks like. Drag rows to rearrange them, then Save order: that order is what the device's knob cycles through, and it survives a reboot.

Decks can be shared, too. Share deck (next to SEND TO MY BOARD) publishes your selection to the community — and under Decks in the top nav you can browse the sets other people have curated and send one straight to your own device.

A public deck's page has Install to my board and Download .zip side by side, for anyone who opens it — no account, no build queue. Share gives you the pack's link to hand to someone else. The .zip holds the modules and the running order, so dropping it on a device's Patterns page installs the whole set arranged as its author left it, first in the board's list. The first download of a pattern compiles it, which takes a few seconds; after that it is immediate. A slot that cannot be built (no header, or a header that does not compile) is left out, and the page says which. Keep a few packs on a USB stick and you have your sets with you whether or not there is internet in the room.

On a VPN, or on a different network from the board? Install to my board needs your browser to reach the board, so use the file instead:

Download .zip on the deck (or pattern) page.
Open your board's Patterns page — http://patternflow.local/patterns, or the board's IP. Turn the VPN off first: the board is on your home network.
Drop the .zip on Upload, or tap Upload and choose it. Don't unzip it.

3-2. One pattern, from its detail page

Send to my Patternflow on a pattern's detail page does the same thing a deck does, for one pattern: Send over Wi-Fi hands the board the pattern's module, and it appears in the list in seconds. No sign-in, no reflash. Download .zip beside it gets the same module as a file, for the steps above. A single pattern's .zip leaves the board's order as it is.

4. Making your own in Pattern Lab

Now for the making side. Click Pattern Lab ↗ at the community's top right.

Pattern Lab has a lot of panels, but this guide uses exactly two things: pattern generation and the color ramp. They're enough to take a pattern from nothing to your device. Layers, pixel art, the gallery — all of that is for a later guide.

4-1. Pick a resolution first

Start with the resolution selector above the Preview panel. A standard Patternflow is 128 × 64 (landscape) or 64 × 128 (portrait — the device's usual standing orientation). The choice is recorded in the code as a single // @matrix line and travels with the pattern through sharing, forking, and firmware conversion.

4-2. Generating patterns with AI

A pattern is JavaScript code — but you don't have to write it.

Press COPY PROMPT in the CODE panel. It copies a prompt that carries every rule of a Patternflow pattern.
Paste it into whatever AI you use — ChatGPT, Claude, Gemini — and then describe what you want to make.
The AI comes back with five patterns. Copy them in one at a time with PASTE — the preview updates instantly.
Nothing you love? Ask for another five. And another. Finding a good pattern takes real patience — and how specifically you describe what you want, i.e. how well you write the prompt, matters just as much.

Try the sliders in the Knobs panel on the right — a well-made pattern changes character completely across its four knobs. These are the same four you'll be turning as physical knobs on the device.

The number boxes flanking each slider are its minimum and maximum. You can tune the range a knob travels through, and the ranges you set here are applied everywhere — in the code that goes to your device and in the code that gets shared. Narrow a knob down to the band where the pattern is actually interesting, and the physical knob on the device will sweep exactly that band.

Want to touch the code itself? The CODE GUIDE button documents the pattern structure (setup / update / draw). This guide doesn't go there.

4-3. Coloring with the ramp

Many generated patterns draw only in brightness (0–1). For those, color comes not from the code but from the COLOR RAMP panel — a tool that maps a color gradient across brightness from 0 to 1.

Click the ramp bar to add stops, and pick a color per stop
The mode (linear / smooth / step / hsv short / hsv long) changes how colors blend between stops — the hsv modes travel around the color wheel, rainbow style

The same pattern becomes a completely different object with a different ramp. Play here until the colors feel right — the ramp is recorded in the code as a // @ramp line and ships with the pattern when you share it.

ALPHA is for stacking multiple layers. Layers aren't covered in this guide — but if you're used to Photoshop-style layering you'll get it at a glance, so feel free to explore.

4-4. Two more panels: Director and Graphic Export

Both live in the same workspace, under Panels ▾ if they are closed.

Director automates the knobs over time. Each of the four knobs gets a lane; double-click a lane to drop a keyframe, drag it, and choose whether the segment to the next keyframe holds or eases (the ease handles pull like Blender's). The result is a show — a .pfs file the panel plays by itself (the Performance edition) — and it publishes alongside the pattern when you share, or exports as a MIDI clip for a DAW. docs/pfst-v2-spec.md describes the file; docs/director-midi.md the MIDI side.
Graphic Export renders the pattern at print and screen sizes: PNG stills and MP4/WebM clips, entirely in your browser. Patterns that bake the 128×64 frame into their math are upscaled pixel-for-pixel; ones that scale get a true re-render, and the panel tells you which it did. A poster gets its own renderer (a GLSL twin of the pattern), so a 4K still is not a stretched panel.

Neither changes what goes to the device — the pattern is still the code layer; these are two ways of taking it somewhere else.

5. Verifying on your device

Do this before you share. Every time. The reason is simple:

The device runs C++; patterns are JavaScript. To get onto hardware, an AI translates the code into a C++ header (.h) — and that translation doesn't always succeed. A pattern can be perfect in the browser and come out different on the device. So before publishing: check it on your own device with your own eyes, fix what needs fixing, and share the version that's done. That's what lets the next person trust the .h badge and flash it without thinking.

5-1. Convert to an .h header

Press To hardware at the lab's top right.
The "Convert to a firmware header" dialog opens. Press COPY THE CONVERSION PROMPT and paste it into the same AI you've been using.
It returns .h code starting with #pragma once. Copy that into the dialog's input and press NEXT →.

5-2. Put it on the device and look

The "On to hardware" screen appears. Your header is ready — and it tells you to try it on the board first.

Press Apply to my Patternflow — it builds the module and takes seconds.
In the dialog, press Send over Wi-Fi — with the device on and connected, it uploads immediately.
Look at the device. Does it match the browser preview? Do the knobs respond the same way?

If something's off: go BACK TO THE HEADER and ask the AI to convert again (a straight retry often fixes it), or adjust the pattern code and reconvert. Repeat until it looks right — then move on.

6. Sharing to the community

Once it's verified on your device, press UPLOAD TO THE COMMUNITY on that same "On to hardware" screen. Publishing this way carries your verified .h header along with the pattern, so it lands on the wall wearing the .h badge — a pattern anyone can flash right now.

(The Share button at the lab's top right also publishes, but that path uploads the JS pattern only, with no .h. If you went to the trouble of making the header, publish from here.)

What you fill in:

Title / Description — a name and a short note
How was it made? — generated with AI, hand-edited, and so on. Using AI is no mark against anything here — Pattern Lab is built for it. It's recorded now simply because nobody can reconstruct the answer later.
License — the default recommendation is CC BY-SA 4.0: anyone may use and adapt your pattern as long as they credit you and share their versions under the same terms.
Who can see it? — Public puts it on the wall.

Press Publish to the wall and you're done. Your pattern now plays on the wall; someone hovers it, turns its knobs, forks their own version, decks it onto their device. The loop has come all the way around.

7. When something goes wrong

Symptom	Check
The panel isn't on Wi-Fi, or the flasher never asked for a network	Expected after a first flash. Press RST, run Flash Patternflow again and choose Connect to Wi-Fi (2.4 GHz only; type the name exactly). Or power the panel, wait about 15 s, join its own network `patternflow-xxxx` (password `patternflow`; hold K2 for the exact name; not in the phone's list yet? refresh it) and pick your network at `http://192.168.4.1/` — BUILD_GUIDE §8
`Send over Wi-Fi` does nothing, or fails	Device power · same Wi-Fi network as the computer · on Android, use the IP from the NETWORK screen (hold K2) instead of `patternflow.local`
The device's Patterns page won't open	Same as above — try typing `patternflow.local` into the address bar directly
A card has no `+` (add to deck)	Not a bug — the author shared it without an `.h` header (not hardware-verified)
The `.h` conversion looks wrong on the device	Ask the AI to convert again (a plain retry often fixes it) · simplify the pattern code · try a different model
Modules uploaded but don't appear in the list	Firmware older than v3.2.0 — update it at patternflow.work/update. A larger pattern that shows PATTERN FAILED on firmware older than v3.10.5 needs the same update
A `.zip` pack was dropped but nothing installed	The pack has to contain `.pfm` modules. A zip of `.js` patterns is not a pack — build them first
The deck's order came out wrong on the device	Re-download the pack: the running order ships inside it, and a pack built before the deck was rearranged carries the old one
The device is out of storage	The Patterns page shows free space (KB free) at the top right — delete modules you don't use
The build button asks you to sign in	Baking modules/firmware happens on a server, so it needs a community account (username + password only — no email asked)

The rest of Pattern Lab — layer compositing, pixel art, the gallery — gets its own guide later.

Navigation Menu