Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
# 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](BUILD_GUIDE.md). This guide
is what comes after.
- [0. Before you start](#0-before-you-start)
- [1. One concept: a pattern is a small file](#1-one-concept-a-pattern-is-a-small-file)
- [2. A look around the community](#2-a-look-around-the-community)
- [3. Putting someone else's pattern on your device](#3-putting-someone-elses-pattern-on-your-device)
- [4. Making your own in Pattern Lab](#4-making-your-own-in-pattern-lab)
- [5. Verifying on your device](#5-verifying-on-your-device)
- [6. Sharing to the community](#6-sharing-to-the-community)
- [7. When something goes wrong](#7-when-something-goes-wrong)
---
## 0. Before you start
**A USB cable is for exactly one moment.** The very first browser flash at
[patternflow.work/pattern](https://patternflow.work/pattern) — you set up
Wi-Fi as part of it, and 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](BUILD_GUIDE.md#8-firmware) first.
| 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.2.0 or newer** | Pattern modules (wireless install) need it |
| 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](https://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](https://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
- Sorting: Newest · 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.
1. 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.
2. Inside the deck, **drag to rearrange**, **×** to remove.
3. Press **`SEND TO MY BOARD`** at the deck's bottom right.
4. The build finishes in seconds — you'll see something like
`✓ 4 modules · 32 KB`. Press **`SEND OVER WI-FI`**.
5. 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 published deck also gets a **`Download pack (.zip)`** button, and that is
the link you can hand to anyone: no account, no build queue. The `.zip` holds
the modules *and* the running order, so dropping it on a device's Patterns
page installs the whole set arranged exactly as its author left it. Keep a few
on a USB stick and you have your sets with you whether or not there is
internet in the room.
### 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: builds the module, then offers `Send over Wi-Fi`.
Seconds, no reflash.
---
## 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.
1. Press **`COPY PROMPT`** in the CODE panel. It copies a prompt that carries
every rule of a Patternflow pattern.
2. Paste it into whatever AI you use — ChatGPT, Claude, Gemini — and then
describe what you want to make.
3. The AI comes back with **five patterns**. Copy them in one at a time with
**`PASTE`** — the preview updates instantly.
4. 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
1. Press **`To hardware`** at the lab's top right.
2. The "Convert to a firmware header" dialog opens. Press
**`COPY THE CONVERSION PROMPT`** and paste it into the same AI you've been
using.
3. 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.**
1. Press **`APPLY TO MY PATTERNFLOW`** — it builds the module and takes
seconds.
2. In the dialog, press **`Send over Wi-Fi`** — with the device on and
connected, it uploads immediately.
3. **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 |
| --- | --- |
| `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](https://patternflow.work/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.*
e5b871ed5This file is pinned to the selected release. Download the original to open it in your design tool.