LCD Gamma - portapack-mayhem/mayhem-firmware GitHub Wiki
LCD Gamma tunes the colors of the PortaPack's 240x320 LCD. It works together with the IPS panel option in Settings > Display, which adds proper support for IPS glass. With them you can fix washed out or off colors, compare built-in presets, fine tune gamma and VCOM for your exact panel, and share a tuning as a small text file.
[!NOTE] LCD Gamma only works on PortaPacks with a 240x320 ILI9341 display (H1, H2, H4M and compatible). On devices with a 320x480 display it shows "Only for 240x320 panels" and changes nothing.
Which panel do I have?
PortaPacks ship with either TN or IPS glass. Both use the same ILI9341 controller and report the same display ID, so the firmware can't tell them apart. You have to choose.
| TN | IPS | |
|---|---|---|
| Viewing angle | Colors shift when tilted | Colors stay the same at any angle |
| Look on stock settings | Normal | Off colors, low contrast, raised blacks, warm tones turning orange |
| Setting | IPS panel off | IPS panel on |
If your screen looks washed out or the colors are clearly wrong compared to another PortaPack, you most likely have IPS glass.
Turning on IPS mode
- Go to Settings > Display.
- Check IPS panel (inversion).
- Press Save. The change applies immediately, no reboot needed.
[!TIP] The Normally black only checkbox is the older option (previously labelled "IPS Screen"). It only flips the panel polarity and keeps the TN color curve. When IPS panel is checked, Normally black only is ignored.
[!TIP] The built-in IPS settings were tuned on Rabbit-Labs IPS H4 screens (FPC marking CL32BC272-40A). On most IPS panels, turning on IPS mode is all you need. Use LCD Gamma only if your panel still looks off.
Opening LCD Gamma
LCD Gamma is an external app. Make sure lcd_gamma.ppma is in the APPS folder on your SD card (it is included in the release .ppfw.tar and the SD card package), then go to Settings > LCD Gamma.
All changes are shown live. Nothing is stored until you press Save, and leaving the app without saving restores your saved settings.
Screen layout
Test pattern (top): a 32 step gray ramp, red, green and blue ramps, and color bars (black, white, red, green, blue, cyan, magenta, yellow). Use it to judge your changes.
Preset: the starting point for tuning.
| Preset | What it loads |
|---|---|
| Saved | Your saved tuning, or the built-in values if you have none |
| Built-in | The firmware default for the current mode (TN or IPS) |
| TN stock | The original TN gamma and VCOM |
| IPS | The built-in IPS gamma and VCOM |
| Generic | A common ILI9341 gamma table used by many other projects |
Mode: Easy for simple sliders, Advanced for direct register editing.
Easy mode
| Control | Range | What it does |
|---|---|---|
| VCOM offset | -64 to 63 | Shifts the panel's common voltage. Affects contrast, black level and gray balance. 0 is centered. |
| Gamma low | -32 to 32 | Adjusts the darker part of the curve |
| Gamma mid | -32 to 32 | Adjusts the mid tones |
| Gamma high | -32 to 32 | Adjusts the brighter part of the curve |
| Swap red/blue | on / off | For panels that show red as blue and blue as red |
The gamma sliders move the positive and negative gamma tables together. They don't change the absolute black and white end points.
[!NOTE] Whether a slider makes a range darker or brighter depends on the panel. Watch the gray ramp while you adjust.
Advanced mode
| Control | What it does |
|---|---|
| Parameter number (00 to 32) | Selects the value to edit: 00 to 14 are E0h (positive gamma), 15 to 29 are E1h (negative gamma), 30 is C5h VMH, 31 is C5h VML, 32 is C7h VMF |
| Name and max | Shows which gamma point or VCOM value is selected, and its largest allowed value |
| Value | The value itself. It's limited to the size of that register field, so you can't enter an invalid value. |
| Hex rows | The full E0h, E1h, C5h and C7h values currently applied |
When you switch from Advanced back to Easy, the Easy sliders start from whatever Advanced mode produced.
Buttons
| Button | What it does |
|---|---|
| Patterns | Full screen test patterns (see below) |
| Save | Stores the current tuning. If it matches the built-in values, it is stored as "built-in" so future firmware defaults apply. |
| Revert | Goes back to your last saved tuning |
| Export SD | Writes the current tuning to SETTINGS/lcd_gamma.txt |
| Import SD | Loads SETTINGS/lcd_gamma.txt. It is applied live. Press Save to keep it. |
Full screen patterns
Press Patterns for full screen test images: a 32 step gray ramp, an 8 step gray ramp, white, black, 50% gray, red, green, blue and color bars.
- Turn the encoder, press Left/Right/Up/Down, or tap the screen to change the pattern.
- Press any other button to go back.
Tuning your panel
- Turn on IPS mode first if you have IPS glass. Press Save in Settings > Display.
- Open LCD Gamma and look at the test pattern. If it already looks right, you're done.
- Try the presets (IPS, TN stock, Generic) and keep the one that looks best.
- Open Patterns and use the 32 step gray ramp:
- Every step should be visible, from black to white.
- The grays should look neutral, with no color tint.
- Black should look black, and white should look white, not gray.
- Adjust Gamma low until the dark steps are separate and neutral, then Gamma mid for the mid grays, then Gamma high for the bright end.
- Adjust VCOM offset only if the blacks still look raised or the contrast is low.
- Check the red, green and blue fills. If red and blue are swapped, check Swap red/blue.
- Press Save. Press Export SD if you want to keep a copy or share it.
[!TIP] Comparing against a second PortaPack, or against a photo of the same splash image on a good screen, makes tuning much easier.
The lcd_gamma.txt file
Export SD writes a plain text file to SETTINGS/lcd_gamma.txt:
# Mayhem LCD tuning (ILI9341 240x320)
E0=0F2A28080E0854A9430A0F00000000
E1=0015170711062B563C05100F3F3F0F
C5=323C
C7=C0
BGR=0
E0andE1: positive and negative gamma, 15 bytes each, in hexC5: VCOM control 1 (VMH, VML)C7: VCOM control 2 (VMF)BGR: 1 swaps red and blue
You can copy this file to another PortaPack and use Import SD, then Save. If you find a good tuning for a different panel lot, share it on the Mayhem Discord along with the FPC marking printed on the panel's ribbon cable.
If things go wrong
Screen unreadable after tuning: hold Left + Right while powering on. This resets persistent memory, including the LCD settings. If your settings are stored on the SD card (no coin cell), also delete SETTINGS/pmem_settings from the card.
Negative image after turning on IPS mode: your panel is probably TN. Go to Settings > Display and uncheck IPS panel (inversion). The menus are still readable in negative.
LCD Gamma isn't in the Settings menu: copy lcd_gamma.ppma into the SD card's APPS folder, using the version that matches your firmware.
Settings lost after reboot: without a working coin cell, settings are only kept if Use SD card for P.Mem is checked in Settings > P.Memory Mgmt.
Known limitations
- No autodetection: TN and IPS panels look identical to the firmware, so the panel type must be selected by hand.
- Panel lots differ: the built-in IPS values were verified on one panel lot (CL32BC272-40A). Other lots may need some tuning.
- One curve for all colors: the gamma tables apply to red, green and blue together, so you can't adjust one color channel on its own.
- Screenshots don't show it: Mayhem screenshots capture the image data, not what the glass displays, so gamma changes don't appear in screenshots. Use a camera to compare.
- Debug view: the Debug PMem dump includes the
lcd_ipsflag and the saved tuning values, which is handy for bug reports.