Updated SSD1306xLED library, fixes, compatibility with SSD1315 and more

SSD1306xLED Testing

Our SSD1306xLED library works well with the SSD1306 displays, it is small as binary code and is very fast.

But, there was a problem …

Several months ago we ordered some displays from the Far East and we expected them to work just fine. Unfortunately, they did not. And the problem was not in our library but with the chips. Instead of SSD1306, it seems they put the not that well known SSD1315 OLED display controller. We found that out by looking closely at the PCB, beneath the LCD glass plate.

ssd1306xled testing
SSD1315 OLED display controller

The testing script was producing the result shown in the picture. Note the bottom lines – they were not redrawn, or not always, at least.

On another display that we’ve got earlier, a few years ago, and that was using the SSD1306 controller the picture was looking good.

SSD1306xLED Testing
SSD1306 OLED display controller

Apparently, the problem was with the display controller. Further experiments proved that.

What made it worse for us was that we’ve discovered that from about a hundred display modules we’ve ordered recently half seemed not compatible with our code. We couldn’t even figure out what exactly was the OLED controller on those modules –
SSD1306 as stated in the description where we bought them, or the SSD1315 looking at the testing scripts results. So, we decided to just fix the problem for both kinds of chips. Easy to say it than to do it.

First attempt

2 months ago. We played with the timing and the speed of the data sent to the modules. Tried a few other things, like reordering the commands sent while drawing. We even moved some of the I2C specific code to a separate library to isolate the potential problems and try to fix the issue. No luck.

Second attempt

2 days ago. We decided to re-do the initialization sequence for the OLED controller. These are the commands that we send to the chip before we start drawing things on the display. We read, again, the Solomon Systech PDF file about the SSD1306 controller – the so-called datasheet. There was a half-baked algorithm of how to initialize the chip. Also, looked at several other libraries to see how they do it. Actually, the “Adafruit_SSD1306.cpp” was a really good example so we used some know-how from it.

Wrote the code. Tested it. And, it worked!


SSD1306xLED Testing
SSD1306xLED Testing

Some optimizations

There were a couple of TO-DO’s in the source code for the optimization of multiplication by a constant. That could be easily converted to a combination of 1 or more left-bitwise-shift and additions.

void ssd1306tx_char(char ch) {
  uint8_t c = ch - 32; // Convert ASCII code to font data index.
  for (uint8_t i = 0; i < 6; i++) {
    ssd1306_data_byte(pgm_read_byte(&amp;ssd1306tx_font_src[c * 6 + i]));

We combined the c = ch – 32 and the c * 6 + i and optimized the entire expression.

void ssd1306tx_char(char ch) {
  uint16_t j = (ch << 2) + (ch << 1) - 192;
  for (uint8_t i = 0; i < 6; i++) {
    ssd1306_data_byte(pgm_read_byte(&amp;ssd1306tx_font_src[j + i]));

That saved us about 30 bytes of binary code and it is probably a bit faster than the multiplication with a subroutine.

We did something similar for the void ssd1306tx_stringxy(const uint8_t *fron_src, uint8_t x, uint8_t y, const char s[]); function but without the left-bitwise-shift as the compiler optimizes the very well the multiplication with numbers that are powers of 2, i.e. 2, 4, 8, etc. In our case – 16. That saved us another 20 bytes of binary code and probably gained some speed.

So, we saved about 50 bytes of machine code and gained some speed. That might not look that much but for a microcontroller with 4096 bytes for code and 1 or 8 MHz CPU that’s about 1.2% less memory usage. And, our library is now a bit faster.


There are more functions in the SSD1306xLED library such as for printing text and numbers on the screen and drawing images but that will be subject of another article.

The official page of the library (will be):

Source code is available at:

C Library for SSD1306 OLED Display and ATtiny85

C Library for SSD1306 OLED Display and ATtiny85

It isn’t hard to get one of those OLED displays from eBay or another place. They are usually controlled by SSD1306 chip – one of the most popular. Such displays could be used for a number of things – from just learning to control them and showing some text/numbers/graphics, display sensors’ data or even creating a small game.

SSD1306 OLED Display
SSD1306 OLED Display

Back in 2014, we wrote a small library for the ATtiny85 microcontroller to work with such displays and we called it SSD1306xLED after the name of the controlling chip for the display.

Here is a link to check what’s for sale now:
http://www.ebay.com / OLED 128 64


  1. This library works with the display modules that use the I2C protocol. This is important to know since there are other similar displays that use the same SSD1306 controller but communicate over the SPI interface. In that case, our library will not work. We use, in most cases, the modules with 4 pins – GND, Vcc, SCL, SDA.
  2. Although using the I2C interface, our SSD1306xLED library does not implement the I2C protocol but just a subset of it enough to accomplish the task of sending commands and data to the display. This comes with 2 great advantages: (1) it is super fast; (2) is super small – more details about those characteristics will be outlined below.

The library is, of course, open source and all the software is available at https://bitbucket.org/tinusaur/ssd1306xled/

The I2CSW sub-library

This is a small sub-library that implements a subset of the I2C protocols that is necessary to send some commands and data out. I2CSW stands for “I2C Simple Writer” and as its name implies it only writes out.

There are 2 macros to sent the SCL and SDA wires to high and to low, or, or 1 and 0.

Then, there are 3 low-level functions:
— void i2csw_start(void);
— void i2csw_stop(void);
— void i2csw_byte(uint8_t byte);

The i2csw_start function sets the SCL and SDA pins as output and the “start” condition. In other words, it lets the devices connected to the microcontroller know that we are about to send something out.

The i2csw_stop function sets the “stop” condition. This indicates that we have finished with sending the data. It also set the SDA pin as input so it won’t keep the SDA line at HIGH all the time.

SSD1306 I2C Start and Stop Condition
SSD1306 I2C Start and Stop Condition

The i2csw_byte function sends one byte of data out. It is used to send commands and data to the I2C devices – the display in our case.

SSD1306 I2C Acknowledgment Condition
SSD1306 I2C Acknowledgment Condition

NOTE: The I2CSW library does not handle the acknowledgment condition.

The ssd1306 core functions

There are 4 core functions in the library at the moment:
— void ssd1306_start_command(void);
— void ssd1306_start_data(void);
— void ssd1306_data_byte(uint8_t);
— void ssd1306_stop(void);

The ssd1306_start_command function indicates to the connected I2C devices that we’re about to send commands. This is used to configure the controller o to set some parameters such as the current position on the display.

The ssd1306_start_data function indicates to the connected I2C devices that we’re about to send some data. This is used to send some data to the display controller – like bitmaps or text.

The ssd1306_data_byte function sends 2 bytes of data to the display controller. That is used for both commands and data.

The ssd1306_stop function indicates that we have finished transmitting data.

SSD1306 I2C Write data
SSD1306 I2C Write data

The ssd1306 supplementary functions

These are convenience functions:
— void ssd1306_init(void);
— void ssd1306_setpos(uint8_t x, uint8_t y);
— void ssd1306_fill4(uint8_t, uint8_t, uint8_t, uint8_t);

The ssd1306_init function sends a sequence of commands that will initialize the display controller so it will work the way we expect.

The ssd1306_setpos function sets the current position on the display. Sending data after this command will display it at that position.

From the documentation:

Horizontal addressing mode (A[1:0]=00b)

In horizontal addressing mode, after the display RAM is read/written, the column address pointer is increased automatically by 1. If the column address pointer reaches column end address, the column address pointer is reset to column start address and page address pointer is increased by 1. The sequence of movement of the page and column address point for horizontal addressing mode is shown in Figure 10-3. When both column and page address pointers reach the end address, the pointers are reset to column start address and page start address (Dotted line in Figure 10-3.)

Solomon Systech Apr 2008 P 42/59 Rev 1.1 SSD1306
SSD1306 I2C Horizontal addressing mode
SSD1306 I2C Horizontal addressing mode

The ssd1306_fill4 function fills out the screen with the 4 bytes specified as parameters. The reason for 4 bytes is that it is convenient for filling out with patterns.

There are 3 other functions derived from the ssd1306_fill4 function:
ssd1306_clear() – clears the screen, i.e. fills it out with “0”.
ssd1306_fill(p) – fills the display with the specified byte.
ssd1306_fill2(p1, p2) – fills the display with the 2 specified bytes.

The testing scripts demonstrate the purpose and usage of those functions.

The testing in the “ssd1306xled_test1” folder

Source code at https://bitbucket.org/tinusaur/ssd1306xled/src/default/ssd1306xled_test1/main.c

This testing script demonstrates the use of the functions in the library.

The first section fills out the screen with random values using a Linear congruential generator.

SSD1306 Library SSD1306xLED Testing Script
SSD1306 Library SSD1306xLED Testing Script

The second section fills out the screen with a sequential number that creates some patterns on the screen.

SSD1306 Library SSD1306xLED Testing Script
SSD1306 Library SSD1306xLED Testing Script

The next section fills out the screen line by line.

SSD1306 Library SSD1306xLED Testing Script
SSD1306 Library SSD1306xLED Testing Script

The last section fills out the screen with various patterns.

More functions …

There are more functions in the SSD1306xLED library such as for printing text and numbers on the screen and drawing images but that will be subject of another article.

Please, share your thoughts!

The Tinusaur team was at the BETT Show in London

Meet Tinusaur team at BETT show London ExCeL

The Tinusaur Project is an educational platform that provides students, teachers, and makers with the tools to learn, teach and make things. We’ve been developing this since 2013 and it started because we needed such tools for our own courses. It is now used in a few schools and universities, both private and government in Bulgaria. The education, whether formal or informal, has always been the focus of the Tinusaur. Naturally, the BETT Show in London is one of the most interesting events of the year in that field.

BETT Show in London
BETT Show in London

The BETT Show is an annual trade show focused on innovations and technology in education. It takes place in London, United Kingdom, and started in 1985.

BETT Show in London
BETT Show in London – Learning Robotics

The Tinusaur team is at the BETT Show, of course, for the second time and it is great here!

BETT Show in London
BETT Show in London – Learning Robotics

What you immediately notice is that everyone has some sort of a robot – a car that you could control to make movements based on an algorithm, or a human-like stumping robot. And those who don’t have a robot – have at least a snapping blocks with electronics like LEDs, motors, servos, etc. that you could program with a Scratch-like environment. This sort of toys becomes a standard for education in electronics, robotics, and programming.

BETT Show in London
BETT Show in London – “Real” Robot

To us, this is a bit disconcerting. Most of those products turn education into a game or playing. Gamification is not just creating a game with which you might (or might no) learn something. It is rather implying the using of game-design elements to improve the process of learning without compromising the process of acquiring knowledge. Another concern that we have is that once you’re done with the playing and you have accomplished the task part of the educational toy you have to put it away and that’s it – you cannot use it to create something useful and practical.

BETT Show in London
BETT Show in London – Learning Robotics

We, at Tinusaur, are trying to avoid the downgrading of the educational part. That is why our kits may look a bit difficult and tedious at first. For the same reason, we decided to focus on C language programming, instead of some other scripting language.

Blocktinu WebUI
Blocktinu WebUI

Another thing we’re trying to do is make the kits equally good for learning and making. We think this is what makes us different. Our goal, from the very beginning, has been to create a platform where everything you learn and create could be used at a later point for something real, useful and practical. And over the years we found out that students really appreciate that.

Tinusaur OLED Display Кit
Tinusaur OLED Display Кit

The Tinusaur OLED Display Kit is a very good example for that.

  • You learn how to solder and assemble the boards and the modules.
  • You learn how to program the microcontroller, read the sensor data and visualize it on the display.
  • You could later use the boards and optionally add other sensors and create something that you could use at home.
  • Your imagination is the limit.

We have just launched a crowdfunding campaign for the Tinusaur OLED Kit.

Help us start the production of the Tinusaur OLED boards. Go get your own Tinusaur OLED Kit.

Meet the Tinusaur team at the FOSDEM in Brussels, Belgium

Tinusaur Team at FOSDEM

We are launching a crowdfunding campaign for the Tinusaur OLED Display Kit and this its page: https://www.crowdsupply.com/tinusaur/oled-display-kit

Meet the Tinusaur team at the FOSDEM in Brussels, Belgium on February 2nd and 3rd.

Would you like to contact us and meet at the event or have a question about our platform? Fill out the form below.

Launched crowdfunding campaign for the Tinusaur OLED Display Kit

Tinusaur OLED Display Кit

We have just launched our crowdfunding campaign at Crowd Supply for the Tinusaur OLED Display Kit – a bundle of boards and modules that allows you to connect an ATtiny85 microcontroller to an SSD1306 OLED display. This is a kit so you have to assemble the boards yourself by soldering the parts to the PCB thus start learning about electronics and physics. It might sound complicated at first but these Tinusaur boards are very easy to assemble using the guides and tutorials that we provide. Once all the boards are assembled you could connect a DHT11 sensor module, measure temperature and humidity and show the results on the screen.

Tinusaur OLED Display Кit
Tinusaur OLED Display Кit

With the Tinusaur OLED Display Kit, you get everything you need to start: the Tinusaur main board with the ATtiny85 microcontroller, the LED shield for test and learning, the OLED display shield, the SSD1306 OLED display, the DHT11 sensor module, a LiPo battery kit, and, a USBasp programmer.

The Tinusaur is an Open Source project – both the software and the hardware. Our own library for with the display, called SSD1306xLED, is considered one of the fastest for that display and microcontroller.

Check out the campaign page for details!

Launching Crowdfunding Campaign in January

Tinusaur OLED SSD1306xLED Crowdfunding Campaign

It looks like that our most popular software library is the SSD1306xLED. This is a library for working with OLED displays based on the SSD1306 controller. So, we decided to create a Tinusaur shield to carry an OLED display and we’re thinking about putting it up for crowdfunding this January.

What could you do it a Tinusaur Board and an OLED display?

There is an internal temperature sensor built into the ATtiny85 microcontroller and you don’t need any external components to use it. You can read its value and show it on the display.

Tinusaur OLED SSD1306xLED
Tinusaur OLED SSD1306xLED measuring temperature and voltage

We’ve figured a way to measure the battery level (or the power supply voltage) connected to the ATtiny85 microcontroller by using the PB5 (that is the RESET pin, yes) and one additional resistor. It is not very precise but could give you an indication, at least.

DHT11 module
DHT11 Module

You could also connect one of those popular DHT11 sensor modules, measure temperature and humidity and show it on the screen.

BM180 module
BM180 Module

You could also connect the Bosch BMP180 sensor module and measure barometric pressure and temperature, and show it on the screen. That will also allow you to calculate the altitude – pretty neat, isn’t it?

The official announcement with information about the start date, goals and other details is coming up in early January.

Updated User Guides for the Main Board, Shield LEDx2 and EDUx4IO

Main Board Shields LEDx2 EDUx4IO

We have updated the user guides for how to assemble the Tinusaur Board, Shield LEDx2 and Shield EDUx4IO. They are all in PDF format and are available at the following links:

The collection of user guides is at tinusaur.org/guides.

Our plans are, once finalized, to convert those slides to video and upload them to YouTube – that appears to be more convenient for some people. Also, add some voice-over … maybe. 🙂

Tinusaur Workshop UNI4KIDS Drenta

We’d like to ask you to take a look at the user guides and if you think there’s something to be added or changed, please, leave a comment below this post.



Tinusaur Selected as Best National Digital Solution for International World Summits Awards in the Category Learning & Education

TINUSAUR was nominated as best national digital solution for BULGARIA for the international World Summit Awards


Veliko Tarnovo/Salzburg, 2018-10-24

TINUSAUR was nominated as the best national digital solution for BULGARIA for the international World Summit Awards (WSA). The World Summit Awards are a global initiative selecting digital innovation making a positive impact on society. With this nomination in the Category Learning & Education TINUSAUR qualifies for evaluation among over 400 international projects by the WSA Jury 2018.

TINUSAUR was nominated as the best national digital solution for BULGARIA for the international World Summit Awards.

The Tinusaur is an educational platform and set of tools that focus on programming, robotics, and electronics and applying modern learning methods in an effort to present science and technology in an interesting and entertaining way to the students. It is a mixture of software and hardware. Here it is described in 3 simple steps: (1) you assemble your hardware yourself by soldering your board; then (2) you learn how to program it using puzzle-like blocks; then (3) you learn how to write C code. … After that, your imagination is the limit.

The Tinusaur project and its tools are currently being used in universities, schools, and as part of other educational initiatives all around the world. In such environments, the students get to keep their broads for themselves, take them home, play with them, make things and write programs. This is unlike many other similar products and solutions that are so expensive that there are just a few per class or school and the teachers keep them within the facilities.

The WSA nominees 2018 show the richness, diversity, and innovation of digital solutions on a global scale and prove how digital technology can improve society on each corner of the world. The WSA 2018 nominees will be evaluated based on seven fundamentals criteria: Content, Functionality, Design, Technology, Innovation, Impact and Global/UN value.

Each year, WSA nominees are selected by the WSA National Experts from more than 180 UN member states. The WSA National Experts nominate up to eight projects for each country – one for every WSA category.

A nomination to the WSA hence is already an award in itself – the qualification to compete and be presented on an international level and being the best practice in Learning & Education nationally.

About the Tinusaur OOD

The Tinusaur OOD, the Bulgarian company established earlier in 2018, is currently selling products and generates revenue that ensures the future of the project. It received an investment from 2 private individuals and has developed plans for the next 2 and 5 years as part of the planning for the next round if funding.

About the WSA

The World Summit Award is a global initiative within the framework of the United Nations World Summit on the Information Society (WSIS). WSA is the only ICT event worldwide, that reaches the mobile community in over 180 countries. WSA highlights digital content improving society and focusses on local content with global relevance.

Visit us on www.worldsummitawards.org, Facebook and Twitter, #WSA18

Media Contact World Summit Award:
Manuela Wagner
Network Development & Communications,
World Summit Awards


How to Assemble Your Tinusaur Shield LEDx2 – Guide (slides)

Tinusaur Shield LEDx2 - Assembling (slides)

We have just finished another guide – this time about how to assemble your Tinusaur Shield LEDx2.

Shield LEDx2 Assembled

The file in PDF format is available at this location:  Tinusaur Shield LEDx2 – Assembling (slides).

Please, download it and take a look. If you feel that there’s missing something or wrong, please, let us know.

When we update the files we will commit changes in this repository: https://bitbucket.org/tinusaur/shield-ledx2-docs/.