Yesterday I experienced some frustration with the SainSmart I2C LCD Module that I bought to help Pete and Bill uncover the problems that they’ve been having. If you go and read, you’ll find that I had a lot of difficulty finding the right combination of code that can be used with this module. Eventually, I figured out how to use it, so I thought I’d document it here, to avoid the pain that someone else may feel.

The basics are essentially this:

1. The LiquidCrystal library that ships with I2C is probably fine for connecting to LCDs with a parallel interface, but it does not support I2C bus displays.
2. There is a so-called “New” or “FM” version of the LiquidCrystal library that you can find documented here. You can download the code by clicking here. I tested LiquidCrystal_V1.2.1.zip while typing this up.
3. The new library is viewed as a replacement for the existing library. That means that you have to delete the existing library from the 1.6.3 libraries directory, and add the LiquidCrystal library in its place. This is kind of a pain, and is the worst part of this procedure. The instructions are here, but not very explicit. The commands you type also vary a bit with what operating system you use. Basically, the idea is to find the directory where the Arduino system libraries are installed, and delete (maybe after backing up) the LiquidCrystal directory, and replace its contents with the new LiquidCrystal directory. You’ll have to shutdown and restart the Arduino IDE after making the change.

And, you are almost home. You’ll have to make a couple of small changes to your sketches to make them use the I2C LCD display. Instead of including “LiquidCrystal.h”, you’ll need to include “LiquidCrystal_I2C.h”. And, you’ll need to make a small change to the “constructor” that builds the LCD object.

#include "LiquidCrystal_I2C.h"
#define BACKLIGHT_PIN (3)
#define LED_ADDR (0x27)  // might need to be 0x3F, if 0x27 doesn't work
LiquidCrystal_I2C lcd(LED_ADDR, 2, 1, 0, 4, 5, 6, 7, BACKLIGHT_PIN, POSITIVE) ;

And then you should be able to use the “lcd” object just like any other. If you look at this page, you can see all the operations that the lcd object supports. If you ever want to use (say) a parallel interfaced LCD, you’ll probably be able to do so by just changing the include and the constructor.

Bonus explanation: You are probably asking “what’s with all that the numbers in that constructor?” and “why those numbers?” and “what do they mean?” Here’s the basics (the details are not that important). The “piggyback” board that we use is mostly a chip that we call an “I2C I/O expander”. If you look carefully, you can read the part number off the chip. In this case, it says that it’s a PCF8574. A little Googling will reveal that it’s a chip made by Texas Instrument, and it basically has a set of data pins that can be individually configured as inputs and outputs, and read and written by commands sent over the I2C bus. The little backpack connects each one of those outputs to a particular pin on the LCD board. The library (you can think of it as a driver) is basically the code that knows how to send commands over the I2C lines, that causes each of the eight or so pins on the PCF8574 to go high or low, and thereby activating functions on the LCD.

There are a couple of complications that can arise. First of all, while the PCF8574 is a common chip, there are similar backpacks you can buy that might use different (but similar chips). If your backpack doesn’t have a PCF8574 on it, you may find that my code above doesn’t work, and you’ll have to figure out what’s happening on your own.

But even if it does, there appear to be incompatibilities between some backpacks as well. As I mentioned before, some appear to have the address 0x27 (like mine) but some might have the address 0x3F. I’m not sure why that may happen (perhaps they are using a “work-a-like” chip whose real only difference is the I2C Address it response to?)

But the major problem is that even if they use the same chip, they need to wire the circuit to the LCD in the same way. I’ll try to explain. Let’s say the I/O expander has 8 output pins, which we will label P0 through P7. They all have similar capabilities. To drive the LCD parallel inputs, we need to wire them up. One of the LCD pins controls the backlight. Which of the I/O expander outputs should we wire to it? It’s actually arbitrary, we could pick whatever we like. But to turn on the backlight, we need to know which choice was made (which of the P0-P7 we need to turn on), and the same goes for all the other pins that we need write. Thus, the software needs to know how the wiring of this little backpack is setup.

And sadly, it appears that there might be different boards, with different wiring. Luckily, in this new LiquidCrystal library, they foresaw this eventuality, and allowed you to specify how those things are wired up. If you look in the file LiquidCrystal_I2C.h, you’ll see a definition for the constructor that we are using:

  // Constructor with backlight control
   LiquidCrystal_I2C(uint8_t lcd_Addr, uint8_t En, uint8_t Rw, uint8_t Rs,
                     uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7,
                     uint8_t backlighPin, t_backlighPol pol);

This looks a bit daunting, but what it means is that you can specify an LCD panel by specifying a bunch of values. The uint8_t is just an ugly shorthand for a small integer (an unsigned value, ranging from 0-255). The first argument is the I2C address (0x27 in the case of my board). The next arguments are which I/O pin on the I/O expander goes to the named pin on the LCD board. For example, in our case, the next argument after the address was a 2. That means that P2 of the I/O expander is wired to En (the enable pin) on the LCD board. Similarly P1 goes to the Read/Write Pin, and so on. The final two arguments say that the backlight was wired to P3, and that it’s polarity is POSITIVE (some displays have the LED turn on when the pin goes to ground).

So, how did I figure out which pin goes to which? If you had a schematic for the board, you could work it out using datasheets. I actually got lucky, and realized that the example sketch on the SainSmart product page had an example sketch which included these lines. The code they posted there is not compatible with the 1.6.3 IDE (sigh) but the information was helpful.

So, it took WAY too much time, and WAY too much work, but I have it working. Hope that helps someone else who comes along later.

This little gadget arrived via Amazon Prime today: a three axis gyroscope/accelerometer that can be programmed via the I2C bus. I didn’t really have any reason to get one, other than simple curiosity, although I suspect that possibly mounting one on my (as yet unfinished) robot platform might be able to determine motion parameters of the robot.

The board itself is well documented on the Arduino Playground as the MPU-6050 Accelerometer + Gyro. The pinout is rather simple: your normal +5 and GND, SDA and SCL (I2C bus serial data and clock) one address pin (which lets you decide between two addresses for the chip) and an interrupt pin. The chip includes a FIFO buffer, and whenever the chip places data in the FIFO, it triggers the interrupt, indicating that there is data available for reading. Additionally, the chip includes two other lines (XDA AND XCL) which are a separate I2C bus that the chip can use to talk to a magnetometer. Probably won’t be using that anytime soon, but you never know.

As you can see from the picture, it’s really quite small, about the size of a postage stamp, and includes two mounting holes. When I get home, I think I’ll measure up the dimensions and put together the design for a little plastic case that can snap over it and provide some protection for it. The kit includes both right angle and normal headers, I think the right angle will do nicely.

More later.

Addendum: It’s later. Got the thing hooked up. It appears that I needed to ground the AD0 pin to set the address properly (I should double check this, I thought that if I left it floating, it would default to 0x69). Other than that, it’s dead simple. I wrote this code to get raw acceleration and gyro values from the sensor. I’m told that if you divide the raw values by 16384, you get the acceleration in terms of the gravitational acceleration “g”. In other words, if the board was lying perfectly flat on the tabletop, you’d expect that the X and Y accelerations were zero, and the Z would be 16384. Here’s a screen grab:

As you can see, I wasn’t really quite flat, mostly tilted in X. If you find the lengths of the acceleration vectors, you find it’s something like 0.92 g (we are off by 8% or so). I don’t know what the specs on this thing are, I’ll have to check the datasheet. I know that despite returning 16 bit values, it does not provide 16 bits of accuracy.

Anyway, here’s a simple test sketch:

[sourcecode lang=”cpp”]
//
// A short sketch to read data from the MPU-6050, aka the GY-51
//
// Cribbed from online sources by mvandewettering@gmail.com

#include <Wire.h>

const int MPU = 0x68 ; // I did ground the A0 pin…

int16_t acc_x, acc_y, acc_z ;
int16_t temperature ;
int16_t gyr_x, gyr_y, gyr_z ;

void
setup()
{
Wire.begin() ;
Wire.beginTransmission(MPU) ;
Wire.write(0x6B) ;
Wire.write(0) ;
Wire.endTransmission(true) ;
Serial.begin(9600) ;
}

void
loop()
{
Wire.beginTransmission(MPU) ;
Wire.write(0x3B) ;
Wire.endTransmission(false) ;

Wire.requestFrom(MPU, 14, true) ;

acc_x = (Wire.read() << 8) | Wire.read() ;
acc_y = (Wire.read() << 8) | Wire.read() ;
acc_z = (Wire.read() << 8) | Wire.read() ;

temperature = (Wire.read() << 8) | Wire.read() ;

gyr_x = (Wire.read() << 8) | Wire.read() ;
gyr_y = (Wire.read() << 8) | Wire.read() ;
gyr_z = (Wire.read() << 8) | Wire.read() ;

Serial.print("\e[2J\e[H") ;
Serial.println("RAW MPU-6050 DATA") ;
Serial.println() ;
Serial.print("ACCX ") ; Serial.println(acc_x) ;
Serial.print("ACCY ") ; Serial.println(acc_y) ;
Serial.print("ACCZ ") ; Serial.println(acc_z) ;

Serial.print("GYRX ") ; Serial.println(gyr_x) ;
Serial.print("GYRY ") ; Serial.println(gyr_y) ;
Serial.print("GYRZ ") ; Serial.println(gyr_z) ;

Serial.print("TEMP ") ; Serial.println(temperature / 340. + 36.53) ;

Serial.println() ;

delay(1000) ;
}
[/sourcecode]

Addendum²: Here is a library for accessing the MPU-6050 well (it can return quaternions for orientation, no gimbal lock!).

Early in 2012, I posted a small version of Tiny BASIC that I had adapted to run on the Arduino. It is based upon code which was written by Mike Field, and based upon an earlier version of TinyBasic for the 68000 written by Gordon Brandly, which owes its roots to Palo Alto Tiny BASIC, written all the way back in 1976 as one of the first examples of a free software project.

I had done a couple of extensions to that code to include simple commands to read and write digital and analog I/O pins, implement simple delays, and even generate simple tones. But then the project languished. Tonight, I dusted that code off and made a number of improvements.

First of all, the original program didn’t have very much memory to store programs. This is due largely to the fact that the Arduino Uno has only 2048 bytes of RAM to use for any purpose at all, so every byte is important. What I realized in staring at the code tonight was that a significant number of bytes (well, significant in this context) number of bytes were used to store some static data tables that defined the keywords and functions available to the interpreter. By changing those to “const” tables, I could move them to be stored in the flash (read-only) memory, and free up a couple hundred additional bytes of storage. That may not sound like a lot, but every little bit helps. Now when the system boots, it has 1146 bytes of memory to store programs.

Next, I thought it would be fun to use the OLED display that I’ve been tinkering with to act as an output display. I did a little quick math: I liked an 8×13 font for display, so that meant I could just get 4 lines of 16 characters on the display. That meant that I’d need 64 bytes of ram to store the contents, but that should be a small price to pay. I wrote up a new “outputchar” routine that would deposit printed characters at the the cursor location in the memory buffer, and then increment the cursor position, and handle scrolling. Refreshing the LED screen is not very fast, since it is occurring over the I2C bus, so I thought about a couple ways to “batch” the printing of individual characters, and only refresh the screen when a bunch of output has occurred, only when the screen was “dirty”, and when a time interval had passed. It took me a couple of tries to get this right, but it seems like it worked.

I filmed a short demo of the system working. The keyboard input is still coming from the serial monitor, but display is going to the OLED.

I’d be happy to release the code in a few days after I tinker a bit more. Right now, command line editing is a bit rough, and I’d like to get that working better.

Addendum: This code (the original authors, not mine) has served as the basis for additional versions, some more capable than mine. TinyBasicPlus includes commands to save and chain programs from the internal EEPROM, and store them to SD cards. Very neat.

I intended to play around with some of the NRF24L01 radio modules I have around, but my brain didn’t feel up to it after a day of debugging. So, instead i dusted off a Parallax PING))) sensor that I’ve had around for a long time. I thought it might be fun to see if I could use the OLED display to display the distance measured by the sensor. While watching Agents of Shield, I came up with the following tiny bit of code, demo’ed below.

[sourcecode lang=”cpp”]
#include "U8glib.h"

U8GLIB_SSD1306_128X64 u8g(U8G_I2C_OPT_NONE);

// _
// ___ (_)__ ___ _
// / _ \/ / _ \/ _ `/
// / .__/_/_//_/\_, /
// /_/ /___/
//
// A simple rangefinder program using the Parallax PING sensor
// Writes display out to my tiny OLED display…

const int pingPin = 7 ;

char dbuf[10] ;

void
draw()
{
u8g.setDefaultBackgroundColor();
u8g.drawBox(0, 0, 128, 64);
u8g.setDefaultForegroundColor();
u8g.setFont(u8g_font_10x20);
u8g.drawStr(14, 42, dbuf);
u8g.drawStr(94, 42, "cm");
}

void
setup()
{
Serial.begin(9600);
}

void
loop()
{
long duration ;

pinMode(pingPin, OUTPUT);
digitalWrite(pingPin, LOW); // Make sure we drive the pin low…
delayMicroseconds(2);
digitalWrite(pingPin, HIGH); // Pulse high for 5us
delayMicroseconds(5);
digitalWrite(pingPin, LOW); // Finish the pulse…

pinMode(pingPin, INPUT); // Get ready to read…
duration = pulseIn(pingPin, HIGH); // Wait for the echo pulse to drop back to low

// The speed of sound is 29 us per cm… j

float cm = duration / (29. * 2.) ;
dtostrf(cm, 8, 2, dbuf) ;

u8g.firstPage() ;
do {
draw() ;
} while (u8g.nextPage()) ;
}
[/sourcecode]

Addendum: I’ve been snapping short videos with the Vine app, and then posting them to Twitter and Facebook. Irritatingly, these don’t seem to actually play properly when I embed them back in my website. I’ll figure out a better workflow next time.

Addendum²: Goofing around a little, it appeared that this sensor worked out until about 70cm or so, and then snaps to 340cm. Not sure what that is about: the sensor should behave more accurately than that. I’ll experiment more tomorrow. I should also note that these Parallax sensors are fairly pricey: list price is almost $30. I like the Parallax guys a lot, but that’s pretty spendy. You can get much cheaper modules on Ebay, with costs as low as around $1.50. I haven’t got any of these, but they are worth trying, although various sources on the web suggest that you might get what you pay for. Try googling for “HC-SR04” for more information.

Without a lot more explanation, I did a bit more work on my implementation of Conway’s life, reducing the overhead so I can implement the full 128×64 bit resolution of the OLED display. I also hardcoded an initial pattern: the classic Gosper glider gun. It runs at about 1.625 frames/second, so a new glider is emitted every 18 seconds or so. Eventually, they wrap around and destroy the glider gun by colliding with it. I can think of a few more optimizations that are easy, but I doubt they are very important.

[sourcecode lang=”cpp”]
#include "U8glib.h"

U8GLIB_SSD1306_128X64 u8g(U8G_I2C_OPT_NONE);

#define XSIZE (128)
#define XMASK (127)
#define XSIZE_UINT8 (XSIZE/8)
#define YSIZE (64)
#define YMASK (63)

// We use the extra lines as buffer space…
uint8_t c[YSIZE][XSIZE_UINT8] ;

#define MODX(x) (((x)+XSIZE)&XMASK)
#define MODY(y) (((y)+YSIZE)&YMASK)

#define ISSET(a, x) \
(a[MODX(x)>>3] & (0x1<<(MODX(x)&7)))

#define SET(a, x) \
a[MODX(x)>>3] |= (0x1<<(MODX(x)&7))

#define SETXY(a, x, y) \
a[y][x>>3] |= (0x1<<((x)&7))

#define CLR(a, x) \
a[MODX(x)>>3] &= ~(0x1<<(MODX(x)&7))

void
initrandom()
{
int i, j ;
for (j=0; j<YSIZE; j++)
for (i=0; i<XSIZE_UINT8; i++)
c[j][i] = random(256) ;
}

void
initgun()
{
memset(c, 0, sizeof(c)) ;
SETXY(c, 70, 28); SETXY(c, 68, 29); SETXY(c, 70, 29); SETXY(c, 58, 30);
SETXY(c, 59, 30); SETXY(c, 66, 30); SETXY(c, 67, 30); SETXY(c, 80, 30);
SETXY(c, 81, 30); SETXY(c, 57, 31); SETXY(c, 61, 31); SETXY(c, 66, 31);
SETXY(c, 67, 31); SETXY(c, 80, 31); SETXY(c, 81, 31); SETXY(c, 46, 32);
SETXY(c, 47, 32); SETXY(c, 56, 32); SETXY(c, 62, 32); SETXY(c, 66, 32);
SETXY(c, 67, 32); SETXY(c, 46, 33); SETXY(c, 47, 33); SETXY(c, 56, 33);
SETXY(c, 60, 33); SETXY(c, 62, 33); SETXY(c, 63, 33); SETXY(c, 68, 33);
SETXY(c, 70, 33); SETXY(c, 56, 34); SETXY(c, 62, 34); SETXY(c, 70, 34);
SETXY(c, 57, 35); SETXY(c, 61, 35); SETXY(c, 58, 36); SETXY(c, 59, 36);
}

void
setup()
{
#ifdef TIME_ME
Serial.begin(9600) ;
#endif

randomSeed(analogRead(A0));
initgun() ;
}

void
draw()
{
u8g.setDefaultBackgroundColor() ;
u8g.drawBox(0, 0, 128, 64) ;
u8g.setDefaultForegroundColor() ;
u8g.drawXBM(0, 0, XSIZE, YSIZE, (const uint8_t *) c) ;
}

void
line(const uint8_t *a, const uint8_t *b, const uint8_t *c,
uint8_t *out)
{
int i ;
for (i=0; i<XSIZE; i++) {
int sum = 0 ;
if (ISSET(a, i-1)) sum ++ ;
if (ISSET(a, i )) sum ++ ;
if (ISSET(a, i+1)) sum ++ ;
if (ISSET(b, i-1)) sum ++ ;
if (ISSET(b, i+1)) sum ++ ;
if (ISSET(c, i-1)) sum ++ ;
if (ISSET(c, i )) sum ++ ;
if (ISSET(c, i+1)) sum ++ ;

if (ISSET(b, i)) {
if (sum == 2 || sum == 3)
SET(out, i) ;
else
CLR(out, i) ;
} else {
if (sum == 3)
SET(out, i) ;
else
CLR(out, i) ;
}
}
}

void
loop()
{
int j, op ;
uint8_t obuf[2][XSIZE_UINT8] ;
uint8_t otmp[XSIZE_UINT8] ;

#ifdef TIME_ME
unsigned long time_start, time_stop ;

time_start = millis() ;
#endif

line(c[YSIZE-1], c[0], c[1], obuf[0]) ;
line(c[0], c[1], c[2], obuf[1]) ;
op = 0 ;

// We need this for the wrap around.

memcpy(otmp, c[0], XSIZE_UINT8) ;

for (j=2; j<YSIZE-1; j++) {
memcpy(c[j-2], obuf[op], XSIZE_UINT8) ;
line(c[MODY(j-1)], c[j], c[MODY(j+1)], obuf[op]) ;
op = 1 – op ;
}

// We still have three lines we need to copy back…
// And one more buffer to compute with line()

memcpy(c[YSIZE-3], obuf[op], XSIZE_UINT8) ;
line(c[YSIZE-2], c[YSIZE-1], otmp, obuf[op]) ;
op = 1 – op ;
memcpy(c[YSIZE-2], obuf[op], XSIZE_UINT8) ;
op = 1 – op ;
memcpy(c[YSIZE-1], obuf[op], XSIZE_UINT8) ;

// compute one generation..

u8g.firstPage() ;
do {
draw() ;
} while (u8g.nextPage()) ;

#ifdef TIME_ME
time_stop = millis() ;

Serial.print(time_stop – time_start) ;
Serial.println() ;
#endif
}
[/sourcecode]