ST7789 / GC9A01 / ST7735 Init Problems: Offset, SPI Mode and CS

These three controllers sit behind most small SPI colour displays, and most “my display shows garbage / a shifted image / nothing” threads trace back to the same handful of causes: the controller RAM is larger than the glass, the CS pin changes which SPI mode works, and inversion and colour order are per-panel settings that example code cannot know. None of them are faults - they are configuration, and they are all fixable in software.

Written by the Junxian applications engineering team. Figures quoted for “our models” are calculated from the 103 models on this site that carry a full parameter set, so they change when the catalogue changes.

Same controller, different panel: why example code half-works

An ST7789 addresses a 240x320 pixel RAM regardless of the glass in front of it. A 240x280 or 240x240 panel shows a window into that RAM, and where that window sits is a property of the module, not the controller. Example code written for one module compiles and runs on another - and produces an image shifted by exactly the offset difference, with a band of noise where the unwritten RAM shows. The fix is one line: set the column and row offsets for your module before drawing.

The offset numbers, and where to get them

For a 240x320 panel the offsets are zero. For shorter glass the window is placed by the module maker - commonly centred, so a 240x280 panel starts 20 rows in, and a 240x240 panel 80 rows in on one rotation - but “commonly” is not a specification. The authoritative numbers are in the module datasheet, and they can differ between two modules that look identical. If your image is shifted by a constant amount in one axis, you are looking at an offset problem, not a timing problem.

SPI mode, and the boards with no CS pin

These controllers sample SPI in mode 0 with CS driven normally. Some breakout boards tie CS permanently low to save a pin - and with CS never toggling, the controller loses the edge it uses to frame the transaction, which in practice means the module only works in SPI mode 3. So: board has a CS pin, use mode 0 and drive it; board has no CS pin, try mode 3 before concluding the module is dead. Mixing this up produces a perfectly white, perfectly silent screen.

Inverted colours and swapped red/blue

Whether the glass is normally-black or normally-white decides if the inversion command must be on or off - get it wrong and you see a photographic negative. Separately, the RGB/BGR bit decides channel order - get that wrong and reds and blues swap while everything else looks fine. Both are one-command fixes, both are per-panel properties, and both are the first thing to try when colours are wrong but geometry is right.

Reset and shared-bus discipline

All three controllers need a deliberate reset pulse and a wait before the init sequence, and a further wait after sleep-out - shortening these delays to speed boot is a false economy that produces intermittent cold-start failures. On a bus shared with SD cards or flash, every device needs its CS managed; a floating CS on any device can corrupt the display's transactions only sometimes, which is the worst kind of bug to chase.

Library configuration: where the settings live

Whether you use TFT_eSPI, LVGL with a driver layer, u8g2 for monochrome, or a vendor HAL, all of the above surface as configuration entries: driver selection, width, height, column offset, row offset, SPI mode, inversion, colour order. The library is rarely wrong; its defaults are simply for a different module. Copying a configuration from a forum post transplants that stranger's module onto yours - use the numbers from your module's datasheet instead.

The controllers we ship and what you get with them

The table below is the driver IC mix across our published models. For any of them, ask with the model number and we supply the verified initialisation table for that module and batch - offsets, inversion, colour order and reset timing included - so the settings above are numbers you copy in, not numbers you discover.

Taken from the published specification of each model. A further 21 published models do not name the controller on the public page - that is deliberate on glass where the source can change; ask and we will confirm the current IC for a specific order.