JAL Library for SSD1306 graphic display module.

137 views
Skip to first unread message

RobJ

unread,
Jul 18, 2020, 10:43:30 AM7/18/20
to jallib
Hi all,

I created a library for the graphic display module using the SSD1306 display controller.

For more info (with video) see: http://justanotherlanguage.org/node/321

The library will be available in the next bee package.

Kind regards,

Rob

Sunish Issac

unread,
Aug 2, 2020, 10:13:01 AM8/2/20
to jal...@googlegroups.com
Hello Rob,

I could test your SSD1306 library today. Nice work Rob.

The i2c version works perfectly. Tested with Jaluino2 board and 18f4550.

But I couldn't get the SPI version to work. The module which I used had no CS/csn pin.

One thing I noticed while using the library was, i2c version gets locked in the init function if SDA/SCL pins are interchanged,ie. if there is no i2c communication. But SPI version was continuing with the init function.

Kind regards,
Sunish  

--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jallib/f78e7935-eb7a-4432-8803-dbb2926de832o%40googlegroups.com.

Rob CJ

unread,
Aug 2, 2020, 11:34:23 AM8/2/20
to jal...@googlegroups.com
Hi Sunish,

Thanks for the feedback.

For IIC I include the standard IIC software or IIC hardware JAL library so the problem may then be in one of these libraries.

Did the problem occur when using software IIC or hardware IIC? Also, can you explain what you mean with SDA/SCL being interchanged?

Thanks

Kind regards,

Rob

Van: jal...@googlegroups.com <jal...@googlegroups.com> namens Sunish Issac <sunis...@gmail.com>
Verzonden: zondag 2 augustus 2020 16:11
Aan: jal...@googlegroups.com <jal...@googlegroups.com>
Onderwerp: Re: [jallib] JAL Library for SSD1306 graphic display module.
 

Sunish Issac

unread,
Aug 2, 2020, 1:10:43 PM8/2/20
to jal...@googlegroups.com
Hi Rob,
I was using hardware i2c. By interchanging I meant is there is no timeout happening if there is no reply from i2c device.

Any hints on what to check with SPI version to get it working ?

Sunish



Rob CJ

unread,
Aug 2, 2020, 1:54:06 PM8/2/20
to jal...@googlegroups.com
Hi Sunish,

Hmm for that I need to study the hardware IIC JAL Library.

You said you had no csn pin which is a bit strange for using SPI since I have often seen SPI in combination with some kind of chip select. The csn pin only goes low at the start of a SPI message and goes high when it ends. The library itself does not care about the csn pin, it just makes it low and high as just mentioned.

Can you tell me which pins your device does have? I thought there where only 2 versions and those I used to test the library with.

Thanks.

Kind regards,

Rob

Verzonden: zondag 2 augustus 2020 19:10

Sunish Issac

unread,
Aug 3, 2020, 3:01:56 AM8/3/20
to jal...@googlegroups.com
See the pin naming for the 2 versions I have. Yes it's surprising how they call it SPI.

Rear view indicates jumpers for SPI.

Kind regards,
Sunish

To view this discussion on the web visit https://groups.google.com/d/msgid/jallib/AM0PR07MB6241C8A8DB7358FBFEDF3B9CE64C0%40AM0PR07MB6241.eurprd07.prod.outlook.com.
IMG_20200803_122821.jpg

Rob CJ

unread,
Aug 3, 2020, 1:08:50 PM8/3/20
to jal...@googlegroups.com
Hi Sunish,

I had a look at the datasheet of the SSD1306, it supports 2 types of serial interfaces (see below) and none of them use a RES input. The chip has a RES as reset but you always need to have a CS, see below. So the only option would be that 'RES' is 'CS' but I assume you already tried that (or RES is an inverted version of CS, just thinking out loud here). 

If you can find any other information on this type of interface I may be able to adapt the library but currently I have no clue how the interface of your SPI version should work based on the information in the datasheet.

Kind regards,

Rob






Verzonden: maandag 3 augustus 2020 09:01

Mike

unread,
Aug 31, 2020, 4:39:46 PM8/31/20
to jallib
I have not used this library, since I wrote my own a while ago.  But just a note if you decide to support the smaller 128x32 display...

The SetComPins value will have to change in the init() procedure.  So...

For 128x64:
_ssd1306_write_byte(_SSD1306_SET_COMPINS)
_ssd1306_write_byte(0x12)

For 128x32:
_ssd1306_write_byte(_SSD1306_SET_COMPINS)
_ssd1306_write_byte(0x02)


-Mike

Mike

unread,
Aug 31, 2020, 4:42:39 PM8/31/20
to jallib
Also, if you put the clear_screen() call at the beginning of the init() procedure instead of at the end it will make the display boot up nicely without displaying garbage first.  If one cares about that.

-Mike

Rob CJ

unread,
Sep 1, 2020, 11:56:50 AM9/1/20
to jallib
Hi Mike,

Thanks for the feedback. 

I could change the _ssd1306_write_byte(_SSD1306_SET_COMPINS) by making SSD1306_MAX_Y_PIXELS adjustable and if it is set to 32 use the other setting as you mentioned.

About the clear screen. I cannot clear the screen before the device is initialized (setting start lines and such). I solved this by putting the display off at the start of the initialization but  I could move the clear screen before the call where I put the display on. I think that will solve the issue.

I will make these changes and upload a new version.


Kind regards,

Rob



Van: 'Mike' via jallib <jal...@googlegroups.com>
Verzonden: maandag 31 augustus 2020 22:42
Aan: jallib <jal...@googlegroups.com>
Onderwerp: [jallib] Re: JAL Library for SSD1306 graphic display module.
 
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.

Mike

unread,
Sep 5, 2020, 9:41:00 PM9/5/20
to jallib
FYI: If anyone is using an SSD1306 display with the i2c_hardware library, you may need to set the i2c_level to false.  This was tripping me up.  I have a 128x32 display connected to a 12F1840 running a real time clock program and it kept locking up within a few minutes.  The problem was resolved with this line:

const bit  _i2c_level     = false

I was using "true" based on the comment in the library.  If "false" is a more tolerant level perhaps the library comment could indicate that?

Regards,
Mike



On Saturday, July 18, 2020 at 10:43:30 AM UTC-4, RobJ wrote:

Rob CJ

unread,
Sep 6, 2020, 4:01:36 AM9/6/20
to jallib
Hi Mike,

I could set it FALSE by default in the SSD1306 library. I could also remove the include of the IIC library at all from the SSD1306 library so that it has to be included by the main program and the user can set it there. I tried to make life simpler by including the required IIC or SPI libraries in the SSD1306 library.

I am not sure what the best practice is, suggestions are welcome. 

BTW I will include your 2 other suggestions also, but maybe this one too.

Kind regards,

Rob

 
Van: 'Mike' via jallib <jal...@googlegroups.com>
Verzonden: zondag 6 september 2020 03:41

Aan: jallib <jal...@googlegroups.com>
Onderwerp: [jallib] Re: JAL Library for SSD1306 graphic display module.
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.

Rob Hamerling

unread,
Sep 6, 2020, 4:36:34 AM9/6/20
to jal...@googlegroups.com

Hi Rob,


On 06/09/2020 10:01, Rob CJ wrote:

I could set it FALSE by default in the SSD1306 library. I could also remove the include of the IIC library at all from the SSD1306 library so that it has to be included by the main program and the user can set it there. I tried to make life simpler by including the required IIC or SPI libraries in the SSD1306 library.

I am not sure what the best practice is, suggestions are welcome. 

With I2C you can have the choices:
    - idle state of CLK signal high or low
    - data capture on first or second clock transition (either can be falling or rising)
It depends on the implementation of the slave which combination is appropriate.
So I would think that the choices should be made in the SSDD1306 library.

However, the datasheet of the SSD1306 (fig 8-6) shows that data capture is on the rising CLK signal, but it seems not to care about the CLK idle state. When CLK-idle is low then data capture is on the first CLK transition, when CLK-idle is high then it is on the second transition.  So it is somewhat difficult to decide which are the right choices!

Regards, Rob.



--
Rob Hamerling, Vianen, NL

Rob CJ

unread,
Sep 6, 2020, 5:21:20 AM9/6/20
to jal...@googlegroups.com
Hi Rob, Mike,

I fixed the SSD1306 library with the following changes:

1) When the device is initialized, the display is turned on AFTER the screen is cleared.
2) You can select a display using 128 x 32 instead of the default of 128 x 64 by setting: const SSD1306_Y_32_PIXELS = TRUE
3) About the SMB levels, if the main program defines: const bit _i2c_level = FALSE then it will use the SMB levels, if nothing is defined it or the variable is set to TRUE uses the IIC levels.

I updated this version and the updated sample files to GitHub so it should be in the next bee package.

I do not have a 128 x 32 display but when I select that, the resolution is half so I assume it works OK.

Kind regards,

Rob


Van: jal...@googlegroups.com <jal...@googlegroups.com> namens Rob Hamerling <robham...@gmail.com>
Verzonden: zondag 6 september 2020 10:36
Aan: jal...@googlegroups.com <jal...@googlegroups.com>
Onderwerp: Re: [jallib] Re: JAL Library for SSD1306 graphic display module.
 
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.

Mike

unread,
Sep 6, 2020, 4:08:34 PM9/6/20
to jallib
Hi Rob,

Here's some more information, if that helps, regarding the I2C/SMbus levels.  The datasheet for the PIC12F1840 (Section 30.4, param D041) indicates that VIH for I2C levels is 0.7VDD, which is 3.5V if VDD is 5V.  And VIH for SMbus levels is 2.1V for the VDD voltage range of 2.7V to 5.5V.  Herein must lie the problem.  While the SSD1306 OLED displays are 5V tolerant, they run at 3.3V.  I hooked up my oscilloscope to check and, yes, the bus is idling at 3.3V (pulled-up by the OLED).

So SMbus levels are correct for these displays, at least the two SSD1306 displays that I tested.  The times that I used I2C levels and it worked was just luck...If the VDD happened to be low, like 4.8V (which I know my PICKit2 is) then 4.8 x 0.7 = 3.36V.  That, plus a little forgiveness by the PIC would account for it.  But, of course, not advisable...a.k.a. "skating on thin ice".

Regards,
Mike
To unsubscribe from this group and stop receiving emails from it, send an email to jal...@googlegroups.com.

Rob CJ

unread,
Sep 7, 2020, 4:14:34 AM9/7/20
to jal...@googlegroups.com
Hi Mike,

Thanks for the clarification. Just to be sure that I understand this correctly. You mentioned that the module pulls-up the level to 3.3. Volt. Since I am also using the module at 5 Volt, does that mean that I should not use any pull-up resistors to 5 Volt but leave it open and rely on the module to pull the levels up to 3.3. Volt?

I can imagine that pulling the IIC pins up to 5 Volt may destroy the SSD1306.

BTW. I did not yet receive an e-mail that a new bee-package was created. If you want an update of the SSD1306 library, let me know.

Kind regards,

Rob

Van: 'Mike' via jallib <jal...@googlegroups.com>
Verzonden: zondag 6 september 2020 22:08
Aan: jallib <jal...@googlegroups.com>
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jallib/1efccce8-00a6-420d-ae47-9f06e676f154o%40googlegroups.com.

Mike

unread,
Sep 7, 2020, 9:12:06 AM9/7/20
to jallib
Hi Rob,

Yes, I wouldn't use pull-up resistors.  A simple test to see if the module has them (all of the ones I've worked with do have them, and it sure looks like these are all clones) is to not include them on your bus.  The display module outputs are open-drain, so the communication simply wouldn't work without pull-ups.  If the communication works, then the module has pull-ups.  And you get to save two parts.

I don't know what pin protection these modules have.  Being from China they are certainly built for low cost.  I wouldn't rely on the bus pins being 5V tolerant.  And technically we should be operating the modules at 3.3V, but it appears that they do have protection/regulation on VDD.  Either with a voltage regulator, resistor divider, or transistor level-switching.  At least the ones I've worked with.

Pulling the bus pins up to 5V may do some damage.  It won't be 5V, because of the pull-ups at the module.  It may be somewhere around 4V, depending on the value of the pullups.  But the 5V side is going to be shoving current backwards through the 3.3V side.  Might make the electrons mad.

Regards,
Mike

Mike

unread,
Sep 9, 2020, 5:55:10 PM9/9/20
to jallib
I haven't had time to test this yet.

-Mike

Mike

unread,
Sep 14, 2020, 8:02:37 PM9/14/20
to jallib
Hi,

A note for anyone using these displays with hardware I2C.  At 5V I can run the comm speed at 1MHz, but when running below about 4.2V I have to reduce the speed to 400kHz.  With software I2C, however, I'm able to run 1MHz from 5V all the way down to 3.6V.

Regards,
Mike

Mike

unread,
Sep 23, 2020, 9:10:23 AM9/23/20
to jallib
A little testing done.  I forgot to include this change:

The SetMultiplexRatio value will have to change in the init() procedure.  So...

For 128x64:
_ssd1306_write_byte(_SSD1306_SET_MULTIPLEX)
_ssd1306_write_byte(0x3F)

For 128x32:
_ssd1306_write_byte(_SSD1306_SET_MULTIPLEX)
_ssd1306_write_byte(0x1F)

EDIT: After looking in the library Rob has beat me to it. :)  It's programmed as WIDTH-1.  Great!

Still need more testing, as I'm finding a strange bug when using vertical and page mode together.  This isn't part of the library, but I think it has exposed another difference between 128x64 and 128x32 displays.

Regards,
Mike


On Monday, August 31, 2020 at 4:39:46 PM UTC-4, Mike wrote:

Mike

unread,
Sep 23, 2020, 9:45:47 AM9/23/20
to jallib
I found my "bug".  I'm not sure if anyone will encounter this, since the library doesn't switch addressing modes.  But I'll put it here for future reference.

I'm using vertical addressing mode to place a large (2-line) digit on the display, and then switch back to page mode for the other text.  It was causing strange overwrites.  Oddly, the problem does not happen on a 128x64 display.

There are commands for using vertical/horizontal mode to set the bounds (which line to which other line, and which column to which other column) of what you're writing.  These commands are noted in the datasheet as "for horizontal/vertical modes only".  But if you don't reset the values back, then writing in page mode gets messed up.  So, if you're using horizontal or vertical mode and you change the column start/end (command 0x21) then you need to set them back to the full screen values of (start 0, end 127).  Perhaps this also applies to page start/end, but my testing doesn't show this.

Regards,
Mike

Rob CJ

unread,
Sep 23, 2020, 12:28:44 PM9/23/20
to jallib
Hi Mike,

Thanks for all testing.

So for know the library is OK and no changes are needed, right?

Kind regards,

Rob

Van: 'Mike' via jallib <jal...@googlegroups.com>
Verzonden: woensdag 23 september 2020 15:45
Aan: jallib <jal...@googlegroups.com>
Onderwerp: [jallib] Re: JAL Library for SSD1306 graphic display module.
 
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jallib/bf5c679f-cd2b-4120-9b41-a8b9232af237o%40googlegroups.com.

Mike

unread,
Sep 23, 2020, 2:00:07 PM9/23/20
to jallib
Hi Rob,

Yes, no changes needed.

Regards,
Mike
To unsubscribe from this group and stop receiving emails from it, send an email to jal...@googlegroups.com.

Sunish Issac

unread,
Oct 7, 2020, 11:20:49 PM10/7/20
to jal...@googlegroups.com
Hello Rob,
How can I print text with a bigger size ? Also is there any option to change display size in pixels ?

Kind regards,
Sunish

To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jallib/388a6003-b026-4965-adf9-4ed82ef48902o%40googlegroups.com.

Rob CJ

unread,
Oct 8, 2020, 4:31:22 AM10/8/20
to jal...@googlegroups.com
Hi Sunish,

I used the standard JAL libraries for the fonts and there are some standard fonts available although I did not see fonts that are much bigger in size. 

But I saw on GitHub a pull request from 2015 for bigger fonts but this pull request was never accepted. I was already thinking about trying them out before accepting it but did not find out how to it test first before accepting. Can you check if this pull-request has the fonts you need?
I may give it a try to see how to test this before accepting it.

About the pixel size. I already - after the feedback of Mike - made the number of Y Pixels configurable so that you can use 32 or 64 pixels. I did not do that for the number of X pixels, which is 128 since I could not find a reason to do that. What would be the reason to make that flexible too?

Kind regards,

Rob


Verzonden: donderdag 8 oktober 2020 05:21
Aan: jal...@googlegroups.com <jal...@googlegroups.com>
Onderwerp: Re: [jallib] Re: JAL Library for SSD1306 graphic display module.
 

Mike

unread,
Oct 14, 2020, 10:24:04 AM10/14/20
to jallib
Hi Rob,

Just a note...The dimming ability of the display can be greatly extended by using the SETPRECHARGE and SETVCOMDETECT commands.  I am able to make the display very dim - much dimmer than just using the contrast - by setting all three parameters to zero.  This could be very useful for battery powered devices.

Regards,
Mike


On Saturday, July 18, 2020 at 10:43:30 AM UTC-4, RobJ wrote:

Rob CJ

unread,
Oct 14, 2020, 12:50:59 PM10/14/20
to jal...@googlegroups.com
Hi Mike,

Thanks for the tip. I can adapt the library for that but need to test what you are suggesting.

Kind regards,

Rob

Van: 'Mike' via jallib <jal...@googlegroups.com>
Verzonden: woensdag 14 oktober 2020 16:24

Aan: jallib <jal...@googlegroups.com>
Onderwerp: [jallib] Re: JAL Library for SSD1306 graphic display module.
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.

Rob Hamerling

unread,
Oct 17, 2020, 8:29:59 AM10/17/20
to jal...@googlegroups.com

Hi Mike,


On 14/10/2020 16.24, 'Mike' via jallib wrote:

Just a note...The dimming ability of the display can be greatly extended by using the SETPRECHARGE and SETVCOMDETECT commands.  I am able to make the display very dim - much dimmer than just using the contrast - by setting all three parameters to zero.  This could be very useful for battery powered devices.

I'm using ssd1306 (and sh1106) in other environments (ESP8266/ESP32 with Micropython, and Teensy 4.0 with C/C++). I am interested to extend some of the oled support libraries for these environments for better contrast-control. But the datasheets were not helpful (enough) for me. Could you point me to more elaborate information w.r.t. the above commands (meaning, explanation and format)? 

Regards, RobH

Rob CJ

unread,
Oct 17, 2020, 8:49:09 AM10/17/20
to jal...@googlegroups.com
Hi Mike,

I had a look at what you requested and I since what you are doing is more advanced I thought of the simplest way to add two procedures for advanced users so that you can do anything you want. BTW. I noticed that setting the precharge to 0 is an invalid value according to the datasheet. 

These are the two procedures I added to the library:

procedure ssd1306_send_command(byte in command)
procedure ssd1306_send_command_parameter(byte in command, byte in parameter)
 
This version wil be in the next bee package (ready on Sunday).

Kind regards,

Rob

Verzonden: zaterdag 17 oktober 2020 14:29
Aan: jal...@googlegroups.com <jal...@googlegroups.com>
Onderwerp: Re: [jallib] Re: JAL Library for SSD1306 graphic display module.
 
--
You received this message because you are subscribed to the Google Groups "jallib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jallib+un...@googlegroups.com.

Mike

unread,
Oct 17, 2020, 9:30:19 AM10/17/20
to jallib
Hi RobH,

I didn't find any documentation about these commands.  I only found their usefulness through experimentation.  I also see that the Arduino community has found this out as well.

Sorry that I couldn't be of more help.

Regards,
Mike

Mike

unread,
Oct 17, 2020, 9:39:58 AM10/17/20
to jallib
Hi Rob,

I have found that while the datasheet doesn't say so a value of 0 for PRECHARGE is accepted and has an effect.  I've also found that 10h and 40h are valid values for VCOMHDESELECT.

As for the function, I have seen a couple implementations for Arduino that set contrast, precharge, and vcomh in a dim() function, making it easy for the user/programmer.

Here's are two quick examples I found:


Regards,
Mike
To unsubscribe from this group and stop receiving emails from it, send an email to jal...@googlegroups.com.

Mike

unread,
Oct 17, 2020, 9:48:57 AM10/17/20
to jallib
Here's another good link:


-Mike

Rob Hamerling

unread,
Oct 17, 2020, 2:13:04 PM10/17/20
to jal...@googlegroups.com


On 17/10/2020 15.48, 'Mike' via jallib wrote:
Thanks, also for the other links. I'll give it a try.
Reply all
Reply to author
Forward
0 new messages