Sainsmart 3.2" (SSD1289) framebuffer driver

[notro]

320x240 LCD with integrated SSD1289 controller is the most viewed non HDMI/RCA thread in the Screens and displays forum.

I have wanted to add support for this controller to my project for a long time. But I wanted a different interface circuit than the one used in that thread.
Two reasons for this
* Using SPI for the control signals cuts the bandwidth in half.
* The circuit uses CS to latch the data into the LCD controller. Other LCD controllers doesn't support this.
Another benfit is that my circuit gives a completed transfer. Spritemods circuit needs the next byte to latch in the current data.

So, I started small and tested the circuit on the ITDB02-2.8 display which has an 8-bit bus, and that worked fine at 32Mhz.
The plan was to make an 8-bit protoboard, do some more testing and write documentation, but then my soldering iron died on me. So I'm awaiting a new one.

Well, documentation isn't really that much fun, so I skipped ahead and extended the breadboard circuit to try it with my Sainsmart 3.2" display which has a 16-bit bus.

I really get into trouble when there's alot of wires on the breadboard, so I had to write a script to test the circuit.
I needed to know that the circuit worked before I went on with the driver. And yes there was some miswiring
It took me some time to find out that after the script had used the SPI bus lines as GPIOs, I couldn't just reload the SPI controller driver spi_bcm2708.
I had to reboot the computer! I haven't done any investigation into why it behaves like this.

So with a reboot the SPI bus was working properly.

Spritemods had already made a framebuffer driver for this LCD controller, so I copied the initialization sequence from him.
The flexfb driver was extended to support the SSD1289, and in minutes I had a working display.
It was a bit disappointing that I couldn't drive the display at 32MHz. I had to step down to 16MHz. This resulted in ~10fps.

This post indicates that we could use speeds between 16 and 32MHz: http://www.raspberrypi.org/phpBB3/viewt ... 44&t=43442
I will look more into this later, when I'm done documenting what I've done so far.

The next step was to make a dedicated driver for this display: sainsmart32fb. This was a breeze.
Just copy the itdb28fb driver, change all occurences of itdb28fb to sainsmart32fb, add initialization sequence and set_addr_win function. Add section to Kconfig and Makefile and finally add the device to fbtft_device.
A little fight with the init code to get rotation working though.

Commercial
I encourage people writing framebuffer drivers for these small displays, to try the FBTFT project.
With the FBTFT SD-image it is very easy to do driver development: https://github.com/notro/fbtft/wiki/Development
And the flexfb driver can handle a lot of displays without the need for a dedicated driver: https://github.com/notro/fbtft/wiki/flexfb

Touchpanel
The last step was to get the touchpanel to work. I already had some experience with the ITDB02-2.8 display which had a TSC7846 touch controller.
The Sainsmart display had an ADS7843 controller, which is supported by the same Linux driver: ads7846.
Earlier I had extended the FBTFT SD-image with a modified ads7846 driver that can add it's own device. This makes it ideal for testing different setups.
The touch controller has a SPI interface and an IRQ line that signals when pressure is detected. This makes it easy to hook up, and luckily there's two Chip Select lines on the Pi.
Sadly this touchpanel didn't behave as good as the ITDB02-2.8 display. The x values increased as I moved the stylus along the y-axis. The y values was much better.
I got these values when dragging a stylus from edge to edge:
X
Top 350-2800
Middle 750-3200
Bottom 1500-3800

Y
Left 750-3250
Middle 750-3300
Right 750-3250

A quick test with X server proved it hard to use. Hopefully I have received a bad apple or that better calibration can yield a better result.

Testing
I write small test scripts for my displays, making it easy to test them all before each release. So I made one for this as well.
But wait, looking at the test running it was as if the display was out of focus! Escpecially when having the console on screen.
What caused this? Maybe the init sequence had something to do with it. I went to the Sainsmart product page and downloaded the example code.
It was an old version of Henning Karlsen's library. But, no. The display looked the same. The other displays I have is quite sharp, so this wasn't good.
Maybe quality and price goes together here, the display is really cheap: $15.99.

Having fun
Even though this display was a bit disappointing, the joy of getting this to work is reward enough for me.
Now, it's back to that protoboard soldering.

Signal timing
I'm really interested in responses on the interface circuit, escpecially on the timing calculations I have done on the wiki page.
I have tried to find where the timing bottlenecks are. But why can't I drive the SSD1289 at 32MHz as I could with the ILI9325?
I haven't found an answer in the datasheets at least.
Maybe it will be better on a protoboard...
If I only had access to a professional Logic Analyzer...


References
Step-by-step guide and SD-image download: https://github.com/notro/fbtft/wiki
Interface circuit: https://github.com/notro/fbtft/wiki/SPI ... ce-circuit
Display info: https://github.com/notro/fbtft/wiki/LCD-Modules
Touch info: https://github.com/notro/fbtft/wiki/Touchpanel
Driver code: https://github.com/notro/fbtft/blob/mas ... mart32fb.c
Test script: https://github.com/notro/fbtft_test/blo ... pi_test.py

[elektrknight]

notro - fantastic resource thank you!

You made me want that SSD1289 display This LCD will be a perfect compliment
to my logic chips I have been stashing for years.

> The x values increased as I moved the stylus along the y-axis.
Resitive touch panels require calibration before using.
Does the Linux driver: ads7846 has built-in calibration?

> But why can't I drive the SSD1289 at 32MHz ...

Could be that SSD1289 is either slower then ILI9235 or has somewhat different timing
requirements that are not met at 32MHz. Reading datasheet could tell you more
but then you would have to have a way of capturing what is going on during transfer.

>If I only had access to a professional Logic Analyzer...

I have been thinking of using other P1 GPIO pins as a sort of built-in logic analyzer.
The catch is to capture these inputs as fast as possible which seems like a job for a DMA
kernel driver.

[notro]

> The x values increased as I moved the stylus along the y-axis.
Resitive touch panels require calibration before using.
Does the Linux driver: ads7846 has built-in calibration?

Yes, I know. I have a section about it here: https://github.com/notro/fbtft/wiki/Tou ... alibration
The ad7846 has these calibration setttings: x_plate_ohms, x_min, x_max, y_min, y_max, swap_xy
The problem with this display, is that x_min and x_max varies depending on where you are on the panel, whereas y_min, and y_max stays constant. The x values probably need a linear function to calibrate it's value.
evdev is the xorg input driver, and I can't find any information about this kind of calibration.

[elektrknight]

> ... and I can't find any information about this kind of calibration.

You need to go to the source see "How to calibrate touch screens" by Carlos E. Vidales
this is the latest working URL:
http://www.embedded.com/design/configur ... ch-Screens

RasPi should not have any problem with a bit of a vector math this method is using.
BTW C implementation is linked on that page.

[notro]

> ... and I can't find any information about this kind of calibration.

You need to go to the source see "How to calibrate touch screens" by Carlos E. Vidales
this is the latest working URL:
http://www.embedded.com/design/configur ... ch-Screens

RasPi should not have any problem with a bit of a vector math this method is using.
BTW C implementation is linked on that page.

OK, I understand that it is possible, but the ads7846 driver can't do this, and neither does the evdev drivers do this. The name evdev is a bit ambigious, because it's the name of the kernel event char driver and the xorg input driver.
So to handle this the ads7846 driver would have to be modified. But I believe that if this was a common problem with touchpanels, it would have been configurable already.
I suspect that since the display is so cheap, they might be using panels that didn't pass the most strict quality controls.

[elektrknight]

I suspect that since the display is so cheap, they might be using panels that didn't pass the most strict quality controls.

The problem stems from mis registration between LCD and resistive overlay. It is actually pretty common
in these displays but you might have one with especially bad case of it.
However, even the 3 point correction would probably be enough to fully take care of it and 5 point
would completely eliminate it.

ads7846 driver can't do this, and neither does the evdev drivers do this.

The fact that driver does not do it is surprising, I have used the correction code on a small
MCUs and it worked really really well. I think Linux based touch computers became popular when
capacitive multi touch came out so this might explain why resistive touch is a bit neglected.

I did some searching and this came up "Opengalax is a Linux userland input device driver for touchscreen panels ...".
This code is for RS232,USB or PS2 based interfaces, seems like
it would be really easy to add I2C or SPI interface. It reads some calibration data and sets it
through IOCTLs on the file fd associated with the touch device.


https://github.com/poliva/opengalax.git

[notro]

I did some searching and this came up "Opengalax is a Linux userland input device driver for touchscreen panels ...".
https://github.com/poliva/opengalax.git

I had a look at the code, and it can only do min/max calibration

Code: Select all

		if (calibration_mode) {
			// show calibration values
			if (x > calib_xmax)
				calib_xmax=x;
			if (y > calib_ymax)
				calib_ymax=y;
			if (x < calib_xmin && x!=0)
				calib_xmin=x;
			if (y < calib_ymin && y!=0)
				calib_ymin=y;

Googling "linux touch carlos vidales", I came across another part of the Linux community with a solution for this:
How it works: https://community.freescale.com/thread/244374
Calibration tool: https://github.com/onyx-intl/platform_s ... librator.c
Driver: http://git.tqc.de/cgi-bin/gitweb.cgi?p= ... dce378eb98

For those in the know, is this a calibration standard on Android?

The calibration tool uses 3 points, so I guess it based on the article by Carlos E. Vidales.

Thanks @elektrknight for bringing this up. With the Linux touch driver implementation and calibration tool, it should be quite easy to enhance the ads7846 driver.

All we need now is someone willing do it

[elektrknight]

notro good links. I have also found this page:
"Touchscreen calibration under Linux
A snapshot of the state-of-affairs on 20 december 2009"
http://tias.ulyssis.org/calibration/
and
"Touchscreen device support under Linux
A snapshot of the state-of-affairs on 20 december 2009"
http://tias.ulyssis.org/calibration/device_support.html

Time to dig more...

[mwilliams03]

Good post Notro.

I start X with;

Code: Select all

FRAMEBUFFER=/dev/fb1 startx -- -dpi 60

lowering the dpi allows for more information to be displayed on screen.

[notro]

lowering the dpi allows for more information to be displayed on screen.

Thanks, I wasn't aware of that.

[guzunty]

I'm just gearing up to try this.

I've pulled and built all the source successfully, but the modprobes are not behaving as I expected.

First of all, I'm not 100% certain which modules I should be loading.

I believe I have the same display as on this thread. It has TFT_320QVT on the back side of the board.

I first of all do:

sudo modprobe fbtft_device name=sainsmart32fb

I'm not sure this is the right module to use.

dmesg reports:

[ 564.811048] fbtft_device: SPI devices registered:
[ 564.811095] fbtft_device: spidev spi0.0 500kHz 8 bits mode=0x00
[ 564.811112] fbtft_device: spidev spi0.1 500kHz 8 bits mode=0x00
[ 564.811123] fbtft_device: 'fb' Platform devices registered:
[ 564.811144] fbtft_device: bcm2708_fb id=-1 pdata? no
[ 564.814431] fbtft_device: GPIOS used by 'sainsmart32fb':
[ 564.814463] fbtft_device: 'fb' Platform devices registered:
[ 564.814487] fbtft_device: bcm2708_fb id=-1 pdata? no
[ 564.814524] fbtft_device: sainsmart32fb id=0 pdata? yes

but when I follow it with:

sudo modprobe sainsmart32fb

dmesg shows:

[ 919.226290] sainsmart32fb sainsmart32fb.0: Missing info about 'dc' gpio. Aborting.
[ 919.226386] sainsmart32fb: probe of sainsmart32fb.0 failed with error -22

and unsurprisingly there is no framebuffer device created.

Now, I take it that I need to add some gpio arguments, but am I using the correct module to start with?

[guzunty]

I had better luck with:

sudo modprobe fbtft_device name=sainsmart32spifb

followed by:

sudo modprobe sainsmart32fb

dmesg now reports:

[ 120.894334] fbtft_device: SPI devices registered:
[ 120.894380] fbtft_device: spidev spi0.0 500kHz 8 bits mode=0x00
[ 120.894399] fbtft_device: spidev spi0.1 500kHz 8 bits mode=0x00
[ 120.894408] fbtft_device: 'fb' Platform devices registered:
[ 120.894428] fbtft_device: bcm2708_fb id=-1 pdata? no
[ 120.894476] fbtft_device: Deleting spi0.0
[ 120.897154] spi spi0.0: setup: want 16000000 Hz; bus_hz=250000000 / cdiv=16 == 15625000 Hz; mode 0: cs 0x00000000
[ 120.897190] spi spi0.0: setup: cd 0: 16000000 Hz, bpw 8, mode 0x0 -> CS=00000000 CDIV=0010
[ 120.897320] fbtft_device: GPIOS used by 'sainsmart32spifb':
[ 120.897339] fbtft_device: 'reset' = GPIO25
[ 120.897351] fbtft_device: 'dc' = GPIO24
[ 120.897359] fbtft_device: SPI devices registered:
[ 120.897375] fbtft_device: spidev spi0.1 500kHz 8 bits mode=0x00
[ 120.897390] fbtft_device: sainsmart32spifb spi0.0 16000kHz 8 bits mode=0x00
[ 155.796193] Console: switching to colour frame buffer device 40x29
[ 155.797933] graphics fb1: sainsmart32fb frame buffer, 240x320, 150 KiB video memory, 4 KiB buffer memory, fps=20, spi0.0 at 16 MHz

and I have a frame buffer.

Is this the correct procedure?

I am a bit confused by the '8 bits mode' diagnostics. This display has a 16bit bus. Are these messages referring to the width of the spi frames?

thanks,

Derek

[notro]

sudo modprobe fbtft_device name=sainsmart32spifb
sudo modprobe sainsmart32fb

Is this the correct procedure?

The sainsmart32fb driver supports two devices:
* sainsmart32fb - This is for devices driven with 8-bit latched or 16-bit bus. But it has not been tested.
* sainsmart32spifb - This is for driving the display with an interface circuit: https://github.com/notro/fbtft/wiki/SPI ... ce-circuit

I am a bit confused by the '8 bits mode' diagnostics.

What are you referring to?

[guzunty]

What are you referring to?

[ 120.897375] fbtft_device: spidev spi0.1 500kHz 8 bits mode=0x00
[ 120.897390] fbtft_device: sainsmart32spifb spi0.0 16000kHz 8 bits mode=0x00

Please see '8 bits mode' in the above two dmesg entries.

Also 'bpw 8' here:

[ 120.897190] spi spi0.0: setup: cd 0: 16000000 Hz, bpw 8, mode 0x0 -> CS=00000000 CDIV=0010

Although this one definitely looks like it is SPI specific (bits per word?).

[notro]

What are you referring to?

[ 120.897375] fbtft_device: spidev spi0.1 500kHz 8 bits mode=0x00
[ 120.897390] fbtft_device: sainsmart32spifb spi0.0 16000kHz 8 bits mode=0x00

Please see '8 bits mode' in the above two dmesg entries.

Also 'bpw 8' here:

[ 120.897190] spi spi0.0: setup: cd 0: 16000000 Hz, bpw 8, mode 0x0 -> CS=00000000 CDIV=0010

Although this one definitely looks like it is SPI specific (bits per word?).

Yes, that's 8-bit SPI.

[guzunty]

Well the display is doing something, but it looks like the row and column counts are not correct, the display dots are all sheared.

Any suggestions?

[guzunty]

Should I be able to modprobe sainsmart32spifb ?

[guzunty]

Never mind. I have success. The display corruption was due to a poor DuPont cable contact on the wr signal.

[guzunty]

I have not gotten around to measuring frame rate yet, but what I can say so far is that a CPLD based design using a GuzuntyPi (https://github.com/Guzunty/Pi/wiki) driving the Sainsmart 3.2 LCD module will run with a SPI clock of 32MHz.

There is more than enough logic in the CPLD to bring the 'wr' signal up one half SPI clock earlier than the discrete logic is able to do. This may make the circuit a little more stable. In fact, it *almost* runs at 48MHz, albeit with some bad pixel jittering. Quite likely with a properly routed board rather than a nest of jumpers it will be fine.

I'll post again when I have frame rate data to share. I'll also share the VHDL if you'd like to see it.

One thing I have noticed is that, while the cpu load is indeed negligible as noted elsewhere, an ssh session seems sluggish and prone to broken pipes. Likewise, keyboards plugged into the Pi directly seem to exhibit the sticky key syndrome more often. Has anyone else seen this? Is this expected?

[notro]

I have not gotten around to measuring frame rate yet, but what I can say so far is that a CPLD based design using a GuzuntyPi (https://github.com/Guzunty/Pi/wiki) driving the Sainsmart 3.2 LCD module will run with a SPI clock of 32MHz.

That's cool. I had a quick look through the wiki pages, but I couldn't find anything on how to program the CPLD. Can it be done from the Pi? And does the CPLD socket fit the holes in a breadboard?

There is more than enough logic in the CPLD to bring the 'wr' signal up one half SPI clock earlier than the discrete logic is able to do. This may make the circuit a little more stable. In fact, it *almost* runs at 48MHz, albeit with some bad pixel jittering. Quite likely with a properly routed board rather than a nest of jumpers it will be fine.

Which circuit are you referring to? Valdodov's?

I'll also share the VHDL if you'd like to see it.

Yes, please.

One thing I have noticed is that, while the cpu load is indeed negligible as noted elsewhere, an ssh session seems sluggish and prone to broken pipes.

I haven't noticed this, and I work entirely through SSH.

Likewise, keyboards plugged into the Pi directly seem to exhibit the sticky key syndrome more often. Has anyone else seen this? Is this expected?

Yes, I haven't had this problem at all until the last FBTFT release. Looking at the commits, I can't see anything that should cause this since the last FBTFT image (2013-02-09-wheezy-raspbian-2013-05-24-fbtft).
Commits: https://github.com/raspberrypi/linux/commits/rpi-3.6.y
I don't have a HDMI monitor to try with, but I would like to know if the vanilla 2013-05-25-wheezy-raspbian behaves like this?

[guzunty]

That's cool. I had a quick look through the wiki pages, but I couldn't find anything on how to program the CPLD.

There are two aspects to that question; programming the CPLD with a new ready made core, and creating a new core to your own design.

Can it be done from the Pi?

Yes, programming the CPLD can be done from the Pi very easily:

Code: Select all

sudo gz_load my_new_core.xsvf

Creating a new core to your own design, sadly, is not currently possible on the Pi. You need either Windows, RedHat Enterprise or SUSE Enterprise Desktop. I use the last one to host the Xilinx ISE tool which takes VHDL and turns it into a core for you. There's also a simulator. I have not yet gotten around to providing directions for downloading, installing or running ISE on the Wiki. Too much else to do . Also, there are lots of useful cores already available for download on the site, so not everyone needs to learn to program new cores.

And does the CPLD socket fit the holes in a breadboard?

The CPLD socket does have 2.54mm pin spacing, but the pins are arranged in a matrix so would not be compatible with most breadboards, I'm afraid. I use M-F Dupont cables to take signals from the Guzunty to a breadboard (except in this case, where I used F-F Duponts to connect the Guzunty pins directly to the LCD). It is also worth noting that a CPLD can often *completely eliminate* the need for a breadboard (as indeed happened in this case).

Which circuit are you referring to? Valdodov's?

I am referring to all circuits derived from the original sprite-mod design.

PCMIIAW, but my analysis of the common design is that the shift register strobes are activated by the ripple counter on the 16th cycle of the SPI clock (or 8th or 4th depending on the design) . This causes a lot of oscillation on the databus outputs as the shift sequence completes. This should not matter so long as the data is latched after shifting is complete. However, I wondered if this could cause ringing at higher data rates.

The CPLD design does not use a shift register. Instead, it latches each bit as it arrives from the 'mosi' input signal, eliminating unnecessary oscillation (obviously, it cannot and does not eliminate *necessary* oscillation).

The CPLD uses a 16 bit SPI design (like yours) with separate signalling for DC and Reset signals. My reading of the SSD1289 interface specification led me to believe that data is latched either on the rising edge of 'wr' (if 'cs' is low) or the rising edge of 'cs' (if 'wr' is low). I could be wrong, but there seemed to me to be a potential race condition if 'cs' and 'wr' are allowed to rise together as they are in some sprite-mod derived circuits. Accordingly, the CPLD design raises the 'wr' signal on the falling edge of the SPI clock, which is one half SPI clock cycle before 'cs' rises with SPI_CS0. I will post the VHDL shortly below.

I haven't noticed this, and I work entirely through SSH.

I am using SSH over a wi-fi connection, it is maybe this that is being interrupted. I will investigate further as I get a chance. Everything else seems to be working perfectly following the directions on your Wiki.

I don't have a HDMI monitor to try with, but I would like to know if the vanilla 2013-05-25-wheezy-raspbian behaves like this?

I do. I'll try to experiment and report back on this. How do I go about being sure I have an exactly vanilla wheezy-raspbian release? Do you just mean an up to date installation according to apt-get?

[guzunty]

Here is the VHDL as promised. Note that I am routing the processor controlled signals through the CPLD for convenience at the moment.

Code: Select all

architecture RTL of gz_LCD is
signal bit_cnt: natural range 0 to 15 := 15;
begin
  cs <= sel;
  reset <= pi_reset;
  cd <= pi_cd;
  ena <= '1';
  process (sclk, sel) is
  begin
  if (sel = '0') then
    if (rising_edge(sclk)) then
	   outputs(bit_cnt) <= mosi;
	 end if;
	 if (falling_edge(sclk)) then
	   if (bit_cnt = 0) then
		  bit_cnt <= 15;
		else
		  bit_cnt <= bit_cnt - 1;
		end if;
		if (bit_cnt > 0 and bit_cnt < 8) then
		  wr <= '0';
		else
		  wr <= '1';
		end if;
	 end if;
  else
    bit_cnt <= 15;
	 wr <= '1';
  end if;
  end process;
end RTL;

[guzunty]

When I make a proper interface board, I will hardwire many of these piped signals outside of the CPLD and free up some CPLD resources for reading incoming signals. And therein lies another question

Specifically, there are 12 pins left over on the Guzunty which I would like to use as inputs. Since the LCD interface is write only, I would like to transfer the value of these across the SPI0.0 bus as data is clocked out to the display.

Notro, you have a great understanding of linux devices and their drivers, how do you think I should best make these pins available to the user?

Obviously, we don't want reading these to interfere with the display update, so asynchronously reading the data would get the last clocked in set of pin values.

I want to use these to sense buttons, lots of buttons, more than I can sense with the GPIO signals remaining after driving the LCD.

[notro]

Here is the VHDL as promised. Note that I am routing the processor controlled signals through the CPLD for convenience at the moment.

Quite facinating that you can do all this with only 31 code lines!

[guzunty]

I'm biased of course, but I think everyone should learn a bit of HDL. It is such a contrast to 'normal' programming, it can teach you a lot.

Most of all, though, it aligns with the educational goals of the Raspberry Pi itself.

Its actually a few more lines than those posted, but they are all declaring the interface signals etc. This is indeed _all_ of the behavioural specification. And it works!