Introduction
There is lots of Pi help out there, and a little googling will find you heaps. All of it helps people with different skill levels. Sometimes a blog that helps one person will be useless to another. With that in mind I have created a summary of how to build an LED matrix display from scratch, in the hope that it helps lots of people with similar skill level to mine.
NOTE: Some of this tutorial is MAC based, I apologise and will review later to make it more generic.
I have also done most of this on a newer Pi without any issues. I have changed this post a little and need to also note that using an original Pi, I had troubles until I updated my version using NOOBs 1_4_2 on an 8GB SD card - without the internet connected - that gave me grief as well!.
NOTE: Some of this tutorial is MAC based, I apologise and will review later to make it more generic.
I have also done most of this on a newer Pi without any issues. I have changed this post a little and need to also note that using an original Pi, I had troubles until I updated my version using NOOBs 1_4_2 on an 8GB SD card - without the internet connected - that gave me grief as well!.
Basis for this work - Pete Goss
See Pete's work on the Rasperry Pi site. I had my Pi for well over a year and was always looking for something to do with it - Pete had the answer!
What are you going to get
An LED matrix display that you can control externally with http posts, updating words, scrolling or patterns, including a range of functions which are best discovered using the test files included with the source code.
Example 1: Actual Tram arrivals at my local stop
Example 2: The Heartbeat
Technology we are going to play with
Raspberry Pi: The driver of our Matrix. I am using an original Raspberry Pi with the Debian OS so this tutorial is particularly useful if you want to do something with that old Raspberry Pi!
Node.Js: Needed to supply an easy way to communicate with the Pi that I was familiar with (web technologies) and Node.Js is just cool and the easiest thing to implement basic functionality in.
html/css/javascript: Very small bit of HTML and javascript.
Python: Where most of the work if is done in this project. I took the work of Pete Goss and hacked it to suit my needs. I also built a range of tools around it to make the Matrix externally interactive.
Lego: How else are you going to protect your new toy!
Building the LED Matrix
Step 1: Get your hardware: You will need the following
- Raspberry Pi with Debian installed
- 2 x 5v Power sources
- 1 for the Pi - you should have this already
- 1 for the LED matrix. I got an old usb phone charger and stripped it down to get the positive and negative. This is not essential as the power in the Pi can drive the LED matrix, but trust me, its heaps better when you give it some juice.
- LED matrix from Embedded Adventures.
- The important thing this came with was the 5V connector for the matrix.
- Network cable. You could also make it stand-alone wireless, but I prefer to have at least control of the network that is running it. I also plan to use it at work, so some security was at the back of my mind.
- Lego. I was forbidden from using my son's lego, but eBay has an AMAZING range of lego for sale including 1kg, 5kg, 10kg lots. Just incredible. I got a 1kg bag and it was mostly small stuff so provided a real challenge in creating my casing.
- 2 x Lead Jumper set from Jaycar (or anyone else). I just found this the easiest way to connect the Pi GPIO pins to the LED matrix using female to female connectors.
Step 2: Run your Pi headless. You will need to
- Hook the Pi up to
- keyboard
- mouse and
- monitor (I had to use my TV because all our computers are laptops)
- Network (i.e. internet) connection - most routers have at least one spare port. The router should then dynamically assign an IP address for your Pi.
- Turn on the Pi and open a terminal session on you Pi and type sudo apt-get install xrdp
- It is magic. It installs and sets up remote desktop client to always run on startup.
- Install a RDC client on your computer.
- For a Mac at home I use CoRD - it works fine
- At work, the native windows RDC also worked without any special help
- It often asks if you trust certificates - I have always said yes
From this point on all you need to do is have your Pi plugged into a network with power, and you can work on it using a remote desktop client. This is very handy! I use 2 techniques for finding the IP address:
- IPads/IPhones there is an app called Fing - which searches your network and tells you everything on it. No doubt Android will have something similar.
- Scan from laptop/PC. Windows has a range of these tools. On my Mac I use a free product called LanScan.
Step 3: Hook up your LED matrix to your Raspberry Pi. I did this using the female to female connectors mentioned in the hardware section above, but you could also use the strip that comes with the LED Matrix, or if you are really keen - solder!
Pete Goss describes this in his ldp.py header quite well. I have put it here for completeness
###################################################
# ldp python module (ldp.py)
# use: import ldp (in your script)
# A set of functions to make it easier to interface
# with Embedded Adventures' 80x8 led matrix LDP-8008
# By Pete Goss 14/1/2014
###################################################
# connect Raspberry Pi GPIO to J1 on LDP-8008
###################################################
# GPIO pin LDP-8008 pin
# 3 ------------> 2 A (Row address)
# 5 ------------> 4 B (Row address)
# 6 ------------> 5 GND
# 7 ------------> 6 C (Row address)
# 8 ------------> 7 EN (Enable Display)
# 10 ------------> 8 D (Row address)
# 11 ------------> 9 \R1 (Red Led)
# 12 ------------> 10 \G1 (Green Led)
# 13 ------------> 14 L (Latch)
# 15 ------------> 16 S (Shift)
###################################################
Also helpful is GPIO pin layout (Physical numbering from GPIO site)
Step 4: Install node.js and some packages. Again more magic. Once you are running headless and it is connected to the internet. Type the next 2 lines
wget http://node-arm.herokuapp.com/node_latest_armhf.deb
sudo dpkg -i node_latest_armhf.deb
wget http://node-arm.herokuapp.com/node_latest_armhf.deb
sudo dpkg -i node_latest_armhf.deb
This installs node.js ready to run on you Pi.
The next 2 lines install packages using the node packaging tool you just installed. express is a lightweight html server that among things allows you to build static web pages and the json API's. nconf is a package that helps with configuration - mainly so we don't have to hardcode some information into our code.
npm install express
npm install nconf –save
The next 2 lines install packages using the node packaging tool you just installed. express is a lightweight html server that among things allows you to build static web pages and the json API's. nconf is a package that helps with configuration - mainly so we don't have to hardcode some information into our code.
npm install express
npm install nconf –save
Step 5: Deploy the folder src, and its contents to the Pi.
- Get the src zip from my google docs.
- Expand it
- Create a directory so you have the structure home/pi/led/
- If you don't have this structure the node server will not work correctly. You will need to adjust the configuration files. See details below
- Copy the src folder across to your Pi under the led folder
- I use Filezilla for this - see Trevors blog for more detail.
Step 6. Start up python file monitoring and node js to receive http commands. This is where we actually can start to see something cool!
As shown in the diagram, you will need to open 2 separate windows and enter 2 commands from specific directories
- Go to the directory home/pi/led/src and type sudo python pi_interface
- This starts the monitoring of the home/pi/led/src/messages directory for json files with instructions for the LED Matrix
- Go to the directory home/pi/led/src/node and type nodejs app.js
- This starts the node web server ready to receive json posts which it will then put in the messages directory for processing by python process we just started.
- It also makes any web pages under public viewable over port 8080
Running the LED Matrix
Use the archived files (or create your own)
If you look in the archive directory of the files you have deployed on your Pi, there are a set of files (which I explain later). By simply moving the file up one directory level to messages, the running python script will process the file, move it back to the archive directory, and start presenting the message.
Run python unit tests
I use PyDev, and a plugin for eclipse, which combined has a very simple way of running unit tests. I do all my coding and testing on my local machine. The test_node.py is a unit test which I can run locally, either to test the node server (which I also run locally), or using the ip address of the Pi to run it there.
Create your own services
This is really what I did all the work for. Simple application/json http posts can drive the entire display. So from any device that has access to your network, you can display messages. See What is it for below for a detailed explanation of what I want to use it for.
Delete messages
Go to http://<ip adress of pi>:8080/app.html and a simple web page will list messages on the Pi. This is really not meant to be application grade functionality - but just show using express to create web site functionality.
Next version
Now I have built an easy way to delete messages, a full blown website to create messages is the next logical step.
What is it for
I have had so many idea's - if you have others, feel free to post them :-).
Managing alerts at work
Imagine you are in a support role and you get e-mails when there is a system issue. How about the LED Matrix sitting on the wall in front of everyone suddenly lights up with the issue. That makes it more visible.
Developers and testers often have similar devices such as sirens and flashing lights for when a developer breaks the build. With this, you can name and shame then in lights!
Managing your mornings
I drop the kids off to school some mornings, and I catch a Tram to drop them off. How great would it be to have the "next tram" times coming up in your living room! Sometimes while making lunches, refereeing fights and trying to read the paper, actually having a spare hand to check the phone is not an option.
Sad to say not everyone agrees that an LED would look good as a centrepiece in our living room - but I am hopeful someone out there will have better luck than me..
Obviously this is Melbourne (Aus, not US) specific, but I am sure there are a similar service for many cities around the world)
Obviously this is Melbourne (Aus, not US) specific, but I am sure there are a similar service for many cities around the world)
Cheering up a weary project
We actually used it for a project countdown at work (thus one of the functions) which meant each day the "number of days left" on the project automatically ticked over. We also showed a joke of the day to keep spirits up, but I didn't automate that - next time.
Sending messages home
I often get the SMS around 5pm "ETA". If I knew it was going to be displayed on an LED matrix, I reckon I would send it pro-actively each day - now that would be handy. Another great idea that I am sure will not see the light of day at my house..
And......
So many more.... using the display functionality you could manage multiple devices that needed monitoring (thinking of the networks guys here). Honestly the list is endless...
Further details about the solution
Intention
When I first started coding, my intention was that you would send the LED matrix messages in a queue and it would rotate the messages until they were deleted. I only ever built a clear all messages function, and never a delete individual message. So the ability remains to continually add messages, but only the ability to delete all messages being played. I am intending to implement that functionality with the web front end in the next version.
The deployed files
The following files are in the src file that is deployed on the Pi for this solution. I will go through all the src files before I go into the sub directories.
Contents of the src directory
fontv.py: provided by Pete Goss to write ascii characters. I found it wonderful to understand and can highly recommend looking at it for its simple ingenuity.
ldp.py: provided by Pete Goss to interface with the GPIO on the Pi driving the LED matrix.
pi_inteface_mock.py: A very simple emulator for the LED matrix when testing code on your local machine. It was not built to emulate the LED matrix functionality, but actually test the functional code before I start using it to drive the LED matrix.
pi_interface.py: This is my real thievery. I have taken Pete Goss's work and "functionalised" it for my own needs. Running this now starts a thread that instead of taking direct input, polls a directory looking for messages of a certain format.
test_node.py: unit tests that can be run which send http post requests to a node server running the node_server.js in the src/node directory
messages (directory): Where the python looks for message files to process
node\app.js: The extensive amount of coding required to set up a http receive port using node. Note my sarcasm with the word extensive... It also invokes express which does some of the web server heavy lifting.
node\conf.json: Directory configuration for the deployed code. Development is not done on the Pi and directory structure is different bewteen local running and running on the server.
node\public\app.html: Simple web page for deleting messages on the queue of the Pi.
node\public\js\jquery-1.11.2.min.js: For talking between the web page on the browser client and the node server, jquery makes it all very simple. The code in app.html uses this library.
pi (directory): Standard python structure for a package. The majority of my work (versus Pete Goss's work) is done here. All the polling, interpreting of json, and some utils I wrote (probably unnecessarily)
pi\__init__.py: standard pi file for a package.
pi\Display.py: most of my work. Pythons ability to pass functions made it easy for me to separate Peter's work from mine.
pi\utils.py: simple helper functions I built while coding this solution. If you are an experienced python developer, you would probably know of existing/better ways to do this stuff.
messages\archive: sample messages to drive the Pi. Most of them are (hopefully) self explanatory, but I will explain 2 of them
messages\archive\TramResponses.txt: using developer tools in any browser, I looked at the network traffic to get the responses from the tram requests, so I could figure out how to parse the results for the information I wanted. This is just a couple of the responses I received.
messages\archive\n_display.txt: The only sample file that is not easily self explainable. I have explained below in its own section.
messages\current\msg.json: This file is written every time the message array is changed. The Node server on a /led GET call returns this data so the web page knows what is being displayed on the Pi.
Creating personalised displays
Because creating your own display may take a lot of instructions, I have kept the json as brief as possible. To start with you need to know that the LED is represented by an array, [0..79] of [0..7], each containing one of 0(off), 1(red), 2(green), 3(orange) being an 80x8 matrix.The data element for the json works like this (apologies if you are looking on a small screen):
[ [ [[x,y,z],[x,y,z],[x,y,z]],t], [ [[x,y,z],[x,y,z]],t] ]
1 2 2 1 1 2 2 1
- It is an array of instructions
- Each instruction (1) contains 2 elements
- An array of switches (2)
- x = [0..79] position
- y = [0..7] position
- z = colour (0=off, 1=red, 2=green, 3=red)
- t = the length of time it should hold the current configuration
Knowing this, have a look at the n_display.txt file now, and the heartbeat video further up the page and you will figure it out.
