Crystal Focus X Documentation

Pixel Accent Strips Guide

Pixel Accent Strips — A Beginner's Guide for Crystal Focus X

Follow-up to the GraFx Tutorial. Make sure you're comfortable with GraFx basics before diving in here.

What Are Pixel Accent Strips?

Your main blade isn't the only thing that can run pixel animations. The CFX supports up to two additional pixel accent strips — small strings of individually addressable LEDs (WS2812B / Neopixel) that you can put anywhere in your saber:

• Crystal chamber — a few LEDs inside the hilt, illuminating a kyber crystal
• Illuminated pommel — LEDs at the bottom of the hilt
• Chassis lighting — LEDs decorating the internal chassis
• Speaker grill — LEDs shining through the speaker holes
• Any decorative LED strip — anywhere you want animated lighting

These accent strips play their own independent BMP animations, using the same frame-by-frame system as GraFx on the main blade. They're called PIXIES in CFX terminology.

What You Need

Everything from the GraFx tutorial, plus:

• One or two small pixel LED strips (WS2812B / Neopixel), wired to your CFX board
• Knowledge of how many LEDs are in each strip

Part 1: Hardware Setup in config.txt

Before the CFX can drive your accent strips, you need to tell it they exist. Open config.txt on your SD card and add a line for each strip.

Accent Strip 1

accentstrip=8

This tells the CFX that your first accent strip has 8 LEDs.

Accent Strip 2 (optional)

auxaccentstrip=5

A second accent strip with 5 LEDs.

Which Physical Output?

The CFX board has two neopixel outputs: LS1 (main) and LS2 (aux). The sign of the number controls which output your accent strip lives on:

If you have your accent strip on a completely separate wire from the blade, use a negative value to put it on LS2.

Part 2: The PIXIES Folder

Pixel accent strip animations live in their own folder, separate from GraFx:

SD Card
└── extra/
    └── PIXIES/
        ├── 1-CrystalPulse/
        │   ├── pixels.txt         <-- config file (not grafx1.txt!)
        │   ├── normal1.bmp        <-- on-state animation
        │   ├── idle1.bmp          <-- standby animation
        │   ├── forever1.bmp       <-- always-on animation
        │   └── ...
        ├── 2-CrystalBreathing/
        │   ├── pixels.txt
        │   └── ...
        └── 3-ChamberFire/
            └── ...

Key differences from GraFx:

The BMP file names (normal1.bmp, poweron1.bmp, etc.) and the section names inside the config file ([LEDS], [IDLE], [FOREVER], etc.) are exactly the same as GraFx.

Part 3: Creating BMP Files for Accent Strips

The process is identical to creating GraFx BMPs, but with one important difference:

If your crystal chamber has 8 LEDs, your BMPs must be 8 pixels wide.

Example: A Pulsing Crystal Chamber

For an 8-LED crystal chamber that gently pulses, create normal1.bmp:

1. Create a new image: 8 pixels wide × 40 pixels tall
2. Paint each row a shade of blue — start bright at the bottom, dim in the middle, bright again at the top
3. This creates a smooth pulsing loop (remember: bottom row = first frame)
4. Save as 24-bit BMP

Example: An Idle Breathing Effect

For a slow breathing effect while the saber is OFF, create idle1.bmp:

1. Create a new image: 8 pixels wide × 60 pixels tall
2. Bottom rows: very dim (almost black)
3. Middle rows: gradually brighter
4. Top rows: back down to dim
5. Save as 24-bit BMP

Example: A Flickering Crystal

For an always-on flickering crystal, create forever1.bmp:

1. Create a new image: 8 pixels wide × 30 pixels tall
2. Vary each pixel's brightness randomly across rows
3. Use warm whites or your preferred crystal color
4. Save as 24-bit BMP

Part 4: The pixels.txt Config File

The config file for accent strips is called pixels.txt and uses the same format as grafx1.txt:

[FOREVER]
delay=50
many=1
accents=aaaaaaaa

[LEDS]
delay=35
many=1
accents=aaaaaaaa

[IDLE]
delay=80
many=1
accents=aaaaaaaa

Sections

Same sections as GraFx — [LEDS], [IDLE], [POWERON], [POWEROFF], [PREON], [POSTOFF], [BLASTER], [FOREVER].

Parameters

Same parameters as GraFx — delay=, many=, power=, accents=, colorshift_intensity=, colorshift_threshold=.

The delay=0 auto-sync trick also works for timed sequences ([POWERON], [POWEROFF], [PREON], [POSTOFF], [BLASTER]).

Part 5: The FOREVER Sequence

[FOREVER] is especially useful on accent strips. When a FOREVER sequence is defined, it overrides all other sequences — the accent strip plays the FOREVER animation continuously, regardless of whether the saber is on, off, igniting, or retracting.

The only exception: blaster GraFx can temporarily interrupt FOREVER. After the blaster bolt animation finishes, FOREVER resumes.

When to use FOREVER

• Crystal chamber that's always glowing — regardless of saber state
• Accent lighting that never turns off — chassis LEDs, pommel glow
• Persistent ambient effects — a pulsing crystal that doesn't care about ignition/retraction

When NOT to use FOREVER

• If you want your accent strip to react to saber state changes (different animation when on vs. off)
• If you want accent strips to go dark when the saber is off

If you want state-dependent behavior, use [LEDS] for the on-state and [IDLE] for the off-state instead of [FOREVER].

Part 6: Assigning PIXIES in the Blade Profile

Open your saber's config.txt, find the active Blade Profile, and set:

## PIXEL ACCENT STRIPS
## Point accent strip 1 to PIXIES folder #1 (the "1-" folder)
style_pixies=1

## Point accent strip 2 to PIXIES folder #2 (optional)
style_auxpixies=2

Important: These PIXIES assignment keys belong in the active Blade Profile inside config.txt.

Important: style_pixies= and style_auxpixies= are blade profile parameters in config.txt. They are not part of font_config.txt.

Both strips can point to the same folder number if you want them to play the same animation, or different folders for different effects. These assignments belong to the relevant blade profile in config.txt, not to font_config.txt.

Part 7: A Complete Minimal Example

SD Card Layout

SD Card/
├── config.txt                    <-- hardware config (accentstrip=8)
├── 1-MyFont/
│   ├── config.txt                <-- blade profile contains style_pixies=1
│   ├── hum.wav
│   └── ...
└── extra/
    ├── GRAFX/
    │   └── 1-MyBlade/           <-- main blade GraFx (from previous tutorial)
    │       ├── grafx1.txt
    │       └── normal1.bmp
    └── PIXIES/
        └── 1-MyCrystal/
            ├── pixels.txt        <-- accent strip config
            ├── normal1.bmp       <-- on-state animation (8px wide)
            └── idle1.bmp         <-- off-state animation (8px wide)

config.txt (add this line)

accentstrip=8

config.txt Blade Profile

style_pixies=1

pixels.txt

[LEDS]
delay=40
many=1
accents=aaaaaaaa

[IDLE]
delay=80
many=1
accents=aaaaaaaa

BMP Files (for an 8-LED crystal chamber)

• normal1.bmp — 8 × 30 pixels, your on-state animation
• idle1.bmp — 8 × 40 pixels, your standby animation

Part 8: Using Two Accent Strips

You can run two independent pixel accent strips, each with their own animation set.

config.txt

accentstrip=8
auxaccentstrip=5

config.txt Blade Profile

style_pixies=1
style_auxpixies=2

SD Card Layout

extra/
└── PIXIES/
    ├── 1-CrystalChamber/        <-- AccentStrip (8 LEDs)
    │   ├── pixels.txt
    │   ├── normal1.bmp           <-- 8px wide
    │   └── idle1.bmp             <-- 8px wide
    └── 2-PommelGlow/            <-- AccentStrip2 (5 LEDs)
        ├── pixels.txt
        ├── normal1.bmp           <-- 5px wide
        └── idle1.bmp             <-- 5px wide

Each strip gets its own folder with BMPs sized to match its own LED count.

Part 9: Accent Types for Accent Strips

Accent strips support the same accents= characters as GraFx. Each character in the string controls one LED position on the strip.

Good beginner default: start with all a characters so every LED simply follows the BMP. Once that works, experiment with color shift, pulsing, audio flicker, PLI, or magnetic-driven behavior.

Mixing Accent Types

You can mix different types per LED. For an 8-LED strip where the center 4 LEDs pulse in blade color and the outer LEDs play the BMP:

accents=aaBBBBaa

Or a crystal chamber where the first LED is a battery indicator and the rest follow the BMP:

accents=Paaaaaaa

Part 10: Understanding Strip Order on the Data Line

The sign of each strip length decides which physical output it is placed on:

Within each output, the render order is always:

accent strips → quillon strips → blade

That means decorative PIXIES strips are placed first, quillon-style side strips come after them, and the blade for that output comes last.

Example: All on LS1

For an 8-LED accentstrip + 5-LED auxaccentstrip + 144-LED main blade, all on LS1:

Important: auxaccentstrip always comes after accentstrip on the same output.

If They Are on Different Outputs

If one strip is positive and the other is negative, they are no longer chained on the same output. Each one starts at pixel offset 0 on its own output.

Where Quillons and Aux Blades Fit

tridentstrip (the QuillonStrip) sits after both accent strips but before the blade on whichever output its sign selects.

auxstrip (the AuxBladeStrip) is not a PIXIES strip. It is a full blade-class strip that uses the GraFx system. By convention it lives on LS2, and any negative-signed accent or quillon strips are placed in front of it on that same output.

Part 11: Blaster Effects on Accent Strips

Accent strips support blaster GraFx — you can create a flash or pulse BMP that plays on the accent strip when a blaster bolt is triggered.

1. Create blaster1.bmp in your PIXIES folder (8 pixels wide, for example)
2. Add to pixels.txt:

   [BLASTER]
   delay=0
   many=1
   accents=aaaaaaaa

1. In the active Blade Profile inside config.txt, ensure the blaster style is set to GraFx mode:

   style_blaster=9

The blaster animation temporarily overlays on top of whatever the accent strip is currently showing, then returns to the previous animation when done.

Unlike the main blade, accent strip blaster overlays play in-place — there's no bolt position offset. The entire strip gets the overlay.

Part 12: Font Glyphs

Accent strips can display a static glyph image when a font or theme is selected. This is a single-frame BMP that briefly shows on the accent strip when you switch fonts.

1. Create a glyph.bmp file inside your sound font folder (for example 1-MyFont/glyph.bmp).
2. Make the image 1 pixel tall. Its width should match the LED count of the strip you want it to appear on.

This is simply how the current firmware behaves right now. It may change in future firmware updates, so think of this as current behavior rather than a guaranteed long-term limitation.

Practical takeaway: if you want a font glyph to appear on an accent strip, plan for it on accentstrip, not on auxaccentstrip.

Tips & Troubleshooting

General Tips

• Start with FOREVER. For your first accent strip setup, use a single [FOREVER] section — it's the simplest and shows results immediately regardless of saber state.
• Keep BMPs small. Accent strips typically have very few LEDs (3–12). Your BMPs will be tiny images — that's normal.
• Colors render exactly as drawn. Unlike the main blade, accent strips don't apply any color blending or drift effects. What you put in the BMP is exactly what appears on the LEDs.

Common Mistakes

• Wrong BMP width: Your BMP width must match the LED count of the specific accent strip, not the main blade. If accentstrip=8, BMPs must be 8 pixels wide.
• Wrong config file name: Accent strips use pixels.txt, not grafx1.txt.
• Wrong SD card folder: Accent strips use /extra/PIXIES/, not /extra/GRAFX/.
• Missing accentstrip= in config.txt: The hardware line must be present for the firmware to know the strip exists.
• Missing accents=: Always specify the accents string. Its length should match your LED count.
• Mixing up keys: Use style_pixies= for accent strips, not style_grafx1= (that's for the main blade).

Testing

• Start with just one accent strip and one [FOREVER] section before adding state-dependent animations.
• If nothing lights up, verify accentstrip= is in config.txt and that style_pixies= is set in the correct blade profile inside config.txt.
• Verify BMP width matches LED count exactly.

Quick Reference Card

config.txt — Hardware

accentstrip=N           # Accent strip 1 length (+LS1 / -LS2)
auxaccentstrip=N        # Accent strip 2 length (+LS1 / -LS2)

config.txt Blade Profile — Style Assignment

style_pixies=<N>        # Which PIXIES folder for AccentStrip
style_auxpixies=<N>     # Which PIXIES folder for AccentStrip2

Folder Structure

extra/PIXIES/<N>-<name>/pixels.txt    (config)
extra/PIXIES/<N>-<name>/normal1.bmp   (on-state animation)
extra/PIXIES/<N>-<name>/idle1.bmp     (standby animation)
extra/PIXIES/<N>-<name>/forever1.bmp  (always-on animation)
extra/PIXIES/<N>-<name>/poweron1.bmp  (ignition accent)
extra/PIXIES/<N>-<name>/poweroff1.bmp (retraction accent)
extra/PIXIES/<N>-<name>/blaster1.bmp  (blaster flash)
extra/PIXIES/<N>-<name>/preon1.bmp    (pre-ignition accent)
extra/PIXIES/<N>-<name>/pstoff1.bmp   (post-retraction accent)
extra/PIXIES/<N>-<name>/lockup1.bmp   (lockup accent)

pixels.txt — Sections & Parameters

[LEDS]                # On-state animation
[IDLE]                # Standby animation (blade OFF)
[POWERON]             # Ignition accent
[POWEROFF]            # Retraction accent
[PREON]               # Pre-ignition accent
[POSTOFF]             # Post-retraction accent
[LOCKUP]              # Lockup accent
[BLASTER]             # Blaster flash
[FOREVER]             # Always-on (overrides all except BLASTER)

# Parameters (per section):
delay=<ms>            # Frame delay in ms (0 = auto-sync to sound)
many=<count>          # Number of BMP variants (cycles sequentially)
power=<0-100>         # Brightness percentage
accents=<string>      # Per-LED behavior characters (length must match LED count)
colorshift_intensity=<0-255>
colorshift_threshold=<0-255>
stop=1                # Stop after last frame instead of looping
accpulsed=<0-100>     # Pulse depth percentage
accpulsel=<ms>        # Pulse duration in ms

Accent Type Characters

a  = Regular (BMP color as-is)
H  = Color-shift gray/white toward blade color
s  = Mirror of main blade pixel #1
@  = Audio-reactive flicker from BMP color
#  = Inverted audio-reactive flicker from BMP color
m  = Morphing pixel
r  = Randomized RGB color
R  = Randomized color-wheel color
~  = Self-pulsing from BMP color
^  = Self-pulsing from BMP color (inverted phase)
B  = Self-pulsing in blade color
I  = Self-pulsing in blade color (inverted phase)
X  = Self-pulsing in crystal color
L  = Self-pulsing in crystal color (inverted phase)
*  = Audio-reactive flicker in blade color
$  = Audio-reactive flicker in crystal color
p  = Single-pixel PLI
P  = Multi-pixel PLI
M  = Magnetic level using blade color
C  = Magnetic level using crystal color
S  = Magnetic field controls blade-color self-pulsing
T  = Magnetic field controls crystal-color self-pulsing
A  = Magnetic field reveals BMP brightness

Happy crystal chamber building!