Sunday, May 26, 2013

Pifi Mini - Tutorial Part Two

Tutorial Part Two - For those who wish to add an LCD
DISCLAIMER: Since the following instructions involve wiring something to your Pi there is a risk of damaging your Pi if you wire something wrong. I take no responsibility if you damage your Pi while following this tutorial. If followed correctly this tutorial should be quite safe for your Pi.

Skill level: Intermediate, requires soldering

Time: Varies, it really depends on your experience level. For someone used to doing this stuff it shouldn't be more than an hour.

Equipment & materials:
This will really depend on how you're planning on mounting the display but you'll basically need a 16x2 hd44780 LCD screen, wire, pin headers, and of course a soldering iron. If you want to play it safe you can start with a reusable breadboard and reusable jumper cables (look on ebay for  dupont breadboard cables). All of this stuff can be obtained even cheaper if you look on ebay and but for ease of use I'll just provide links to Adafruit products if you want to get them all in one place.

16x2 LCD display using the hd44780 chipset - Very common, available on ebay for $5
*Note if ordering a display do not get the EL or "Electro Luminescent" backlight because these require way more power.
Here's a link to one at Adafruit if you get this one it comes with the 16pin header strip and potentiometer

16 Pin Single Row Male Header with 0.1" pitch (2.54mm)
- These typically come in longer lengths and you simply break off what you need
- If you are buying the display from Adafruit via the link above it already comes with the header you need.

560ohm 1/4 watt resistor
- Not required if you're buying the LCD from Adafruit
- Some cheap Chinese displays do not have a current limiting resistor installed for the LED backlight, this resistor is only needed for those. Since it's just about impossible to tell until you actually apply power to the LCD it's a good idea to wire one in first just to be safe, if the backlight is very dim then you can remove it.

28 Gauge Wire - Rainbow ribbon isn't necessary but it is handy
Here is an Adafruit link

Dupont Breadboard Cables - Female/Female (Optional)
- Alternative to the above 28 gauge wire. I highly recommend these for prototyping even if you're not using a breadboard. 
- Look on ebay for these, they're cheap I got 100 cables 20cm long in 5 colours for $9

26 Pin Dual Row Female Header with 0.1" pitch ( 2.54mm) for 0.025" square pins
 Adafruit link
- I used an 80pin one from and just cut it down with a dremel

Bread board (Optional)
- Adafruit link

Wiring the LCD

Click here for a full size pdf of the wiring diagram

It is especially important when wiring up the LCD that pin 5 of the LCD be connected to ground, this is the R/W pin and it is 5V. Connecting this to any other pin on the Pi will damage your Pi!! Since we're only writing to the LCD we don't need this pin so we're shorting it to ground.

Note that in the wiring diagram there is a 560 ohm resistor between LCD Pin 15 and pin 1 on the potentiometer, this is due to the fact that some cheaper LCD displays do not come with a current limiting resistor for the backlight LED. Installing a resistor around 560 ohms will ensure the LCD does not draw too much current from the Pi, if you install it and the display's backlight is barely on then your LCD already has a current limiting resistor and it is safe to remove the one we added.

Once you've triple checked your wiring plug in your usb wifi dongle and usb keyboard, connect the Pi to a display and apply power to your Pi. There shouldn't be any smoke or fire if you've done everything correctly :) There will be no display on the LCD screen yet, adjust the potentiometer until you can just see the start of black boxes.

If your Pi fails to boot at this point go back and re-check your wiring, if it still doesn't boot then it could be that your power supply isn't powerful enough (you should be using a 5V 700mA supply). Even if your supply says it's 700mA or higher it's not uncommon for cheap no-name supplies to lie, try using a name brand cell phone charger for a smartphone (ie Samsung, Blackberry etc), obviously it'll need to have a micro usb end. You can also try booting with just the LCD screen installed but no wifi dongle or usb keyboard, if it boots then this confirms that the power supply isn't strong enough.

If you've double checked your wiring and ensured your Pi is good but it still isn't booting it may also be a good idea to remove all wiring from the header on the Pi and ensure that it is still working.

Note: Depending on the LCD you chose you may find that the potentiometer used to adjust the contrast is unnecessary and that LCD pin 3 can simply be shorted to ground instead. In my experience the yellow screens with black letters do not need a pot but blue screens with white letters do.

Installing LCD Proc

Before we start we need to check what version of raspberry pi you have.
This command will return a number corresponding to the version of Pi that you have, this will become important later when we are configuring the GPIO pins. 

The main reason we need to know this is because on model B rev 1 boards pin 13 on the Pi's pin header relates to GPIO #21, on model B rev 2 boards and model A boards pin 13 is GPIO #27

If your pi returns either:
0x2 and 0x3 Then you'll follow rev 1 GPIO mapping.

If your pi returns 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xD, 0xE, 0xF or higher you'll follow rev 2 GPIO mapping.

Now we're ready to update packages and install lcdproc

Stop LCDd service just in case it started automatically after installing

Get custom drivers for using lcdproc with the GPIO on the Raspberry Pi, put them in a folder at /home/pi/lcd_extra_drivers

Backup then edit the LCDd.conf file

Find Driver=curses (not the one in the description at the top of the file that has a # in front of it) and change it to:

Remember when using nano you can search for words by pressing ctrl+w

Find the lines
#Hello="  Welcome to"
#Hello="   LCDproc!"

Remove the # from the start and change the text to

Hello="Welcome to"

Find the lines
#GoodBye="Thanks for using"
#GoodBye="   LCDproc!"

Remove the # from the start and change the text to
GoodBye="Shutting Down"

Find the line

And remove the # from the front


Search again for hd44780
Change the line ConnectionType to =rpi

IMPORTANT!! If you have a rev 1 Pi D6 should be 21, if you have a rev 2 it should be 27

Edit your lines so they look like the following:
For Rev 1 GPIO

For Rev 2 GPIO

Find the line Size=20x4

And change it to:

Now save the file and exit (Press ctrl+x, then y, then hit enter)

Restart lcd proc

Now we write our lcd display script

Copy and paste the following text:

You should see info come up on your screen that scrolls
Press ctrl c to end the program, you'll get a few lines of info after that will end with "KeyboardInterrupt" just ignore this it's fine

Now we must go back and uncomment the lcd lines in our rc.local script

There should be two lines in the document like this:

#python /etc/ #start lcd script that displays mpd info

Remove the # from in front of it then save and exit the file.

Congrats, you should now have a working PiFi-Mini with an LCD display. From here you can choose to leave it as is and run it to your stereo or do what I did and incorporate it into a box with it's own speakers and amp.


  1. Hello,
    This is a great project, and all working well for me apart from the LCD. The backlight lights on my LCD, and I can adjust the brightness, but I can see no text. I followed all of the software steps above, and have check my connections from LCD to Pi several times using a continuity tester. I even though my LCD maybe DOA, so purchased another, but still no joy. Do you know if anyone else had had similar problems, and could you suggest anything further to fix it.

  2. Hi Nick, there is the LED backlight brightness but there is also LCD Contrast that needs to be adjusted, you'll need to adjust a potentiometer to do this. On some LCD's shorting it will work but on other's if you do this it'll be too "contrasty" and will just show as full black blocks. Hope this makes sense, please post back if it works or not. I've been insanely busy with a new job so I haven't had much time to post or reply to comments lately, so I apologize in advance if I don't reply right away.

  3. Thanks for the quick reply. Yes, I have the contrast pot installed and tested. Still no display. In your pdf diagram above there is a red connection from the potentiometer to pin 4 of the pi. I'm not sure if that was a mistake or not, but no good with or without. I'll keep trying.

  4. When you adjust the pot does the contrast change at all? Even if there is no text on the display the character "boxes" should turn dark as if every pixel making up the character is on. If this isn't happening then you probably have a wiring issue. Also you'll need to use a 10k ohm pot or lower, if it's higher than that it'll be nearly impossible to adjust.

    Just to go through the wiring again really quickly, pin 4 from the Pi is 5V, this connects to pin 1 on the pot, pin 2 on the pot (wiper) goes to pin 3 of the LCD.

    If the display is in fact changing as you adjust the pot (ie the squares get darker/lighter) then the issue lies somewhere else, most likely with the config file for your LCDd program. If you downloaded my SD card image it is pre-configured for a rev2 pi and the value for D6 is set to 27, if you are using a rev 1 pi this needs to be set to 21 as per the instructions in the above post.

    The more info you can provide me about what you've done and haven't done the better I can help you troubleshoot.

  5. Hello,
    Thanks for your help, I have now resolved the problem. It was a wiring issue to do with the potentiometer. The whole project now works fine. It's a great project, thanks for publishing it. Now to make the enclosure.
    Kind Regards

    1. Great, glad to hear you got it working. I'd love to see pictures of your project too, both work in progress and what the final box looks like.

  6. Hello mate,
    Amazing guide. I just wanted a quick guide for enabling lcd to display my own data that is being input from the USB port. I want to connect OBD2 cable to display cars information on the 20x4 lcd. Can you help?

  7. Hi Umair, there are quite a few tutorials for using LCD's with the Pi and various ways to do it. I'm using LCDd and a python script but for what you're wanting to do it might be better to do it all in python so you have more control. There seem to be pretty well documented LCD libraries etc for the Pi now using various languages. I'd love to follow your project so if you are posting anywhere about it (blog etc) let me know.

  8. I don't know if you are still checking the comments on this post, but I get the following message when I try running /etc/

    sudo python /etc/
    Traceback (most recent call last):
    File "/etc/", line 14, in
    tn = telnetlib.Telnet(host, port)
    File "/usr/lib/python2.7/", line 209, in __init__, port, timeout)
    File "/usr/lib/python2.7/", line 225, in open
    self.sock = socket.create_connection((host, port), timeout)
    File "/usr/lib/python2.7/", line 571, in create_connection
    raise err
    socket.error: [Errno 111] Connection refused

    Any advice?

    1. Hey, really sorry for the late reply, somehow I missed your comment. First things first, you've followed all of the other steps and installed and configured LCD Proc etc before trying to run If so I'm really not sure why you are getting this error, it looks like it's not connecting to LCD Proc via telnet for some reason. Also, did you download the file or create your own? If you created your own there can be issues when copy/pasting code. I don't have my device with me at the moment so I can't check the python version that is being used, it is possible that you've got a newer version that the one that was out when I built this.

  9. Hi, I have learned a lot about my Pi following your tutorial! Part 1 works well. I have this LCD: Adafruit RGB Positive 16x2 LCD+Keypad Kit for Raspberry Pi PRODUCT ID: 1109
    That works when I load other software, but does not display anything when running this script: python /etc/

    When I end it with Ctrl-C I get this:
    Traceback (most recent call last):
    File "/etc/", line 14, in
    tn = telnetlib.Telnet(host, port)
    File "/usr/lib/python2.7/", line 209, in __init__, port, timeout)
    File "/usr/lib/python2.7/", line 225, in open
    self.sock = socket.create_connection((host, port), timeout)
    File "/usr/lib/python2.7/", line 562, in create_connection
    File "/usr/lib/python2.7/", line 224, in meth
    return getattr(self._sock,name)(*args)

    Also on the HDMI monitor this message is repeated:
    ./etc/ line 27: [: ==: unary operator expected error: Timeout while connecting

    I did edit: sudo nano /etc/modules and added i2c-bcm2708, i2c-dev to the file.
    I also added:
    sudo apt-get -y install git pkg-config libevent-pthreads-2.0-5 libao-dev libgnutls28-dev libmad0-dev libfaad-dev libjson0-dev libgcrypt11-dev

    I added these files:
    git clone
    git clone

    cd Python-WiFi-Radio
    ln -s ../Adafruit-Raspberry-Pi-Python-Code/Adafruit_CharLCDPlate/*.py .

    I then ran the python program and it works perfectly. But re-running this:
    sudo python2.7 /etc/

    Did not work.

    Too much or too little modules to add?

    Any suggestions as to where to troubleshoot?

    Thanks very much for your time!

  10. Hi Joe, glad you liked the project! Sorry for the late reply, it seems you have a lot of other stuff running that I did not so there is the possibility that something is conflicting. Another thing that seems to mess a lot of people up is when they copy/paste code, sometimes a character is missed etc. There have been updates to the OS that may have broken something as well, over Christmas if I have the time I might try going through the Pi Fi setup from scratch again with a new stock image and see if I run into any issues, to be honest I haven't really delved into the Pi much over the last year.

    I was initially going to suggest you download the SD card image I posted and try that on a new card, however since your LCD is using I2C it would seem your requirements are different, LCD Proc would definitely need to be configured differently because for my setup uses multiple data lines and employs custom drivers (not written by me). A quick google search found me this info about using LCD Proc with an i2C LCD and the Pi

    Sorry I don't have anything more to contribute, please post back with your results either positive or negative.

    Merry Christmas

  11. Thanks for your response! I think my problem is the method your code uses to 'talk' to the LCD screen.
    Your uses tn = telnetlib.Telnet(host, port)

    With the Adafruit's I2C board, the command is:
    # Print a two line message

    Now I'm stuck. Is it best to try and rewrite your LCDprod code changing tn.write("hello\r"); to lcd.message('Hello\nworld!')

    would it be that simple?

    Thanks for your assistance. I know this takes up a lot of your 'free' time.

    Merry Christmas!

    1. Hey Joe, why do I feel the urge to complete that line from Jimi Hendrix suddenly :)

      As I look further into this I just don't know that your LCD will work with my setup at all, nowhere can I find what LCD chipset it's using (my code is based on an HD44780 LCD), if you could find that out and if that chipset is listed here then provided you write the LCDd config file properly it could work.

      Your best bet though would be to write your own code using only the Adafruit library, however this means you'll have to remove refrences to my lcd python scripts. Feel free to use my code as an example but know that you most likely can't copy and paste it into the Adafruit code. Adafruit wrote their own code to talk with the LCD, in my project I'm using LCD Proc which is completely different (even if the hello\r thing seems similar).

      So in short you have two options, 1) ditch the Adafruit LCD and get an HD44780 based LCD that is not I2C and use only my code without installing Adafruit modules or 2) keep the Adafruit LCD but write your own code within the Adafruit framework.

      If learning is one of your goals then option #2 is probably the better way to go, the Adafruit libraries are probably better documented, LCD Proc was kind of a pain to code for and it took me quite awhile (but I did learn a lot LOL).

      If you write your own code you get to customize it too, start simple with just displaying the currently playing song's name, then add more and more, that's basically how I wrote mine.

      Hope this helps!

  12. This comment has been removed by the author.

  13. Thanks JP for the reply. It may be way beyond my skill level, but I have time to try. I will take your advice and start small!

    I was hoping someone else had the same problem and an answer ;)

    Thanks again!

  14. A little more information on the Adafruit part # 1109 (LCD kit)

    It does use the HD44780 LCD. The Adafruit LCD Plate uses the address at 0x20.

    And if I a follow the code,
    I should be able to combine your flowsheet code to work with the LCD. Is there another, or more steps to get your code to work? Just (Ha, Ha) rewriting your code will work? Or is there other procedures (I don't know the correct terms) to get everything working?


  15. Is there a link to a video of what the LCD is suppose to display? Are the up/down buttons suppose to display information? I think I get all of your cmd1-6 messages.

    I think I have it working. I'll have to burn a new image and start over before I can list just the steps to get this to work.

    Thanks for your help!

  16. Hi Joe, to reply to your first post, basically you're trying to mix code that won't mix, this means that you will have to write your own in "Adafruit Land" :) Feel free to use my code as a reference.

    As for the LCD, I don't have a video of what the display is supposed to read unfortunately, if I have time over the holidays I'll try and record one though. If I remember correctly when it first starts up it says "Welcome to Pi Fi" (this is set in the LCDd conf) then it pulls the currently playing song along the top row, on the bottom it shows the WiFi power and the current volume (see the image in this post

    As for the buttons, I'm not sure if I ever included my button script, I had made a 2nd version of this project that uses a built in HDD and is more of a fixed component you'd have in your stereo cabinet than a portable device. For that one I included 4 buttons, here is a link to that code, THIS WILL NOT WORK WITH YOUR LCD since it is using i2C for the buttons as well, however feel free to reference what my code does and write your own.

    This code is meant to run in conjunction with the LCD code. I wrote the code so that 3 of the 4 buttons have two functions, one function if you tap it and another if you hold it. If you hold Stop then that will start a "safe shutdown", holding FF will skip to the next song, holding RW will go to the previous song.

    If you wind up getting all of this working and have some time please feel free to write up a guide yourself and I'll link to it in this post.

    Good luck and Happy Holidays!

  17. I would like to write up a How2, but I couldn't repeat my efforts with a clean install of your img file.
    But it does work as described without modifying your file. I added
    'import Adafruit_CharLCD as LCD
    import Adafruit_GPIO.MCP230xx as MCP

    I just Commented (#) them out and it still works!

    I think what worked was this:

    It has this link to 'patch' the LCDprod.conf file: had beat me too it, and his patch had already been merged into the head of the LCDproc source code.

    I followed this page in install Adafruit 16x2 LCD code:

    edited /etc/modules to add:

    Edit this:
    cd /etc/modprobe.d/
    sudo nano raspi-blacklist.conf
    - I added comment (#) to:
    #blacklist spi-bcm2708
    #blacklist i2c-bcm2708

    I think, but can't guarantee that this is/was the 'fix' to get the LCDprod.conf to 'talk' to my LCD.

    I did change the LCDd.conf file to include/change these lines:

    # Device of the i2c interface [default: /dev/lcd]
    # Raspberry Pi version 1 require i2c-0; version 2 requires i2c-1

    And in the rc.local file:
    Uncomment the line below if using an LCD and the PiFi LCD python scripts
    python /etc/ #start lcd script that displays mpd info

    Uncomment the next line if you're using an LCD, make sure you have created the python scripts first though
    python /etc/ #start lcd script that displays mpd info

    I did it without a logical approach. That's way I'm not a coder!

    A poor write up, but maybe someone else can sort out the proper steps/order to do this.

    1. Glad to hear you got it all working Joe, I powered mine up last night for a bit, I probably hadn't turned it on in 6 months or so. I shot a short video of the LCD but it looks like you have that figured out now. I wish I had more time to tinker, I thought of a few "ad ons" to this project that would be nice like an alarm clock and/or a sleep timer. Also I wish I could get Google Music working with this, there has been a bit of work by others on that front but it's not all the way there yet.

      Pi's are great though and provide a neat way to learn, I'm no coder either but I managed to cludge my way through :) Post back with some pics or email them, I always love to see what other people's projects look like.

      Happy holidays!

  18. No photos yet. Still looking to integrate my solar panels, batteries and the Pi with speakers into a box or tupperware! Poor woodworking skill, but I do make great sawdust ;)

    Looking to blend PiFi Mini and MusicBox software if possible. I found your web site while searching for a method to connect the Pi to an friend's wifi router without knowing the SSID/Password beforehand. Your 'Access Point fail-over mode' is great. Looking to integrate that into other projects.

    Happy New Year!

  19. Any update on your version 2? Finally got your program to work with Adafruit PiPlate!!

    Question: does your LCD also show 'LCDproc Server' along with the song title, IP address, Volume, Signal Power? Mine shows 'LCDproc Server, Cli:1 Scr:1'

    Is that normal?

    Thanks for your continued work!

    1. Hey Joe, sorry I have had very little time to work on this, I believe I was pretty close to having a version of the "pifi home" code but I'll have to go back and look. If I remember correctly it was designed with button support and with an internal HDD, I can't remember if I kept the wifi portion in it since it was meant to be plugged into your home entertainment unit and use a wired connection (ie not portable).

      As for the LCDProc lines you're seeing, I don't believe mine shows that, it might show LCDproc during initialization, I'll have to fire it up and see.

      Thanks for continuing to follow this project by the way, if I had more time I'd love to revisit it and incorporate the use of my 3D printer into a case design. Unfortunately I don't see this happening any time soon. This winter I'll look into making at github account and trying to learn how that works so I can put the code out there and allow other people to modify or maintain it.

      I'll try and post back with answers, if it's over a week and no response feel free to post another comment to remind me.


    2. To turn off the 'LDCproc Server', just edit LDCd.conf and remove the # from #ServerScreen=off
      That will stop the LCDproc Server from writing on the display.

      Found a nice Menu program for the Pi Plate here
      Link has the code and YouTube video of how it works.

      Thanks again. I could not have gotten this far without your help!

  20. This comment has been removed by the author.

  21. Excellent article. Very interesting to read. I really love to read such a nice article. Thanks! keep rocking.