Software Setup
In this section, I will focus on the setup of a Raspberry Pi as main controller. If you don't have a running operating system, just follow the instructions from here.
In all cases, you have to boot you Pi in CLI mode with auto login. Otherwise, it may happen that the framework does not start automatically after booting. Change the boot mode by opening raspi-config:
sudo raspi-config
And select the following:
- Choose option 3: Boot Options
- Choose option B1: Desktop / CLI
- Choose option B2: Console Autologin
Now reboot your raspberry pi.
If you also have my game controllers from Thingiverse, you have to connect them to the I2C-GPIO pins of the Raspberry Pi.
I implemented a bash script that does most of the required setup steps by it self! The script has just been tested by myself and bugs could exist. If this is the case, please create an issue on this GitHub project! If something is unclear, please have a look at the manual setup instructions before creating a new issue.
Execute these commands in a terminal:
sudo apt-get install git
git clone https://github.com/rottaca/LEDTableEngine.git ~/LEDTableEngine
cd ~/LEDTableEngine
./scripts/setup.sh
On success:
sudo reboot
Have a look at the Application Documentation to get a summary of the available applications and how to control them.
To get the engine running, we first of all have to install a few packages:
- In order to download (and automatically update) the engine repository from GitHub, you need to have Git installed.
- To support the simulation environment of the engine, the loading of images as well as the audio output, you need to install the SDL2 library.
- To build the project you need the c++ compiler as well as CMAKE. These packages can be installed by executing the following command:
sudo apt-get install git libsdl2-dev libsdl2-image-dev g++ cmake libi2c-dev
If you are using the custom game controllers, you have to install i2c-tools. The setup instructions are summarized on Adafruit.
If everything finished successfully, you can now download the repository:
git clone https://github.com/rottaca/LEDTableEngine.git ~/LEDTableEngine
Now have a look at the configuration header configuration.hpp and adjust everything according to your setup.
Before building the project, create a build directory:
mkdir ~/LEDTableEngine/build
To build the project, execute the following commands:
cd ~/LEDTableEngine/build && cmake ..
If the CMake completes without errors, take a closer look on the command line output: Make sure that there is a line that says something like "Controller support enabled".
To build the actual framework, execute:
make
On success, we can now start the engine for the first time.
If you want to use the keyboard to control the engine (maybe just for testing), you unfortunately need root permission with the current implementation to access the keyboard device without a window manager. To do so, you need to find the actual device file that allows use to fetch key presses. Just look for a file, located at /dev/input/by-path/, that contains the characters "-kbd" in its filename by executing:
ls /dev/input/by-path/*kbd*
There are three possible scenarios:
-
The command returns a single file path. You are lucky! Replace the placeholder <KEYBOARD_DEV_FILE> in the following commands with the result of the previous command. E.g.:
/dev/input/by-path/platform-i8042-serio-0-event-kbd -
There are multiple paths returned. You have connected multiple keyboards to your computer. Remove all other keyboards from the computer and retry.
-
If the output is empty, you have no keyboards connected. Connect a (USB) keyboard to the raspberry pi and retry!
If you found your keyboard event file, go to the next section: Simulation Environment or LED-Matrix?
The actual key mapping can be changed in the configuration header file ! Here are the default settings:
Player 1
- Up: w
- Down: s
- Left: a
- Right: d
- Enter: e
- Exit: q
- A: r
- B: f
Player 2
- Up: UP
- Down: DOWN
- Left: LEFT
- Right: RIGHT
- Enter: ENTER
- Exit: BACKSPACE
- A: o
- B: l
If you use the game controllers, you no longer need root permissions but you still need the corresponding device file that gives us access to the I2C bus. The file has the path /dev/i2c-<NR>, were <NR> is replaced by a number. On my raspberry pi, I just had the /dev/i2c-1 present but if you use a different Linux distribution, it is very likely that there are multiple i2c device files. In this case, you can use the i2cdetect from i2ctools to find your controllers. Plug your game controllers in the I2C port and execute the following commands.
List all existing i2c device files:
ls /dev/i2c-*
For each printed file of the pattern /dev/i2c-<NR>, execute the following command:
sudo i2cdetect -r <NR>
For the correct I2C device file, this will print something like that (a non-empty entry in the table below for each detected controller):
pi@raspberrypi:~/LEDTableEngine $ sudo i2cdetect -r 1
WARNING! This program can confuse your I2C bus, cause data loss and worse!
I will probe file /dev/i2c-1 using read byte commands.
I will probe address range 0x03-0x77.
Continue? [Y/n] y
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: 20 21 -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --
If you found the correct i2c device file, replace the placeholder <I2C_DEVICE_FILE> with /dev/i2c-<NR> where <NR> corresponds to your correct i2c file number e.g. /dev/i2c-1
If you found your i2c device file, go to the next section: Simulation Environment or LED-Matrix?
The actual key mapping can be changed in the configuration header file ! Here are the default settings:
You can test the engine (e.g. if you haven't finished building your LED-Matrix or if something doesn't work) by using the simulation environment. Here, the final image is rendered to a window on your computer monitor instead of displaying it on the LED-Matrix. (If you don't use this feature, disable the graphical interface of your Linux environment, to save resources and computational power! But in my case (Rpi B+, CLI), the CPU usage was never above 40%).
To enable the simulation mode, just execute the following commands. Replace the placeholders as explained in the sections above!
If you started to the command line interface, you have to start a graphical environment by executing (only raspberry pi with raspbian):
startx
This should bring up a desktop environment. Now, please open a new terminal and execute the following command to go to the project build directory:
cd ~/LEDTableEngine/build
If you use the keyboard as input device, read the corresponding section above and execute the following command:
sudo ./LEDTableMain -c desktop -i keyboard -f <KEYBOARD_DEV_FILE>
If you use the game controllers as input device, read the corresponding section above and execute the following command:
./LEDTableMain -c desktop -i i2c -f <i2C_DEV_FILE>
These commands should now start the engine in simulation mode. In this mode you should see a window on your screen with a upscaled version of your LED matrix, that shows a scrolling text menu. If not, have a look at the command line output. Try to use the keyboard or the controllers to navigate around.
To render the image onto the LED matrix, you have to find the virtual serial port that corresponds to your (DIAMEX) led controller. The LED controller is required to transmit the color values to the individual LEDs. Usually, the device file is called /dev/ttyACM0 or dev/ttyUSB0 but this depends on your controller and your Linux environment. Identify the correct file by checking, which file appears after plugging in the USB-LED-Controller.
Execute the following command before and after plugging in the LED controller and look for an appearing file name (could be a big list):
ls /dev/tty*
Enter the identified device file name in the configuration.hpp of the engine and recompile the project.
If you use the keyboard as input device, read the corresponding section above and execute the following command:
sudo ./LEDTableMain -c matrix -i keyboard -f <KEYBOARD_DEV_FILE>
If you use the game controllers as input device, read the corresponding section above and execute the following command:
./LEDTableMain -c matrix -i i2c -f <i2C_DEV_FILE>
These commands should now start the engine in matrix mode. If everything works you should see your LED matrix, showing a scrolling text menu. If not, have a look at the command line output.
Obviously, we don't want to start the engine by hand all the time. It should be launched automatically after booting. Therefore I wrote a short start script, that requires minimal setup:
To select the proper input device, you have to modify the start script (scripts/start.sh):
nano ~/LEDTableEngine/scripts/start.sh
Have a look at the beginning of the file and insert your i2c device file from the section above:
i2cDev="<i2C_DEV_FILE>"
If you would like to use the keyboard as input device, leave the i2cDev variable empty and set the keyboard event file:
keyboardDev="<KEYBOARD_DEV_FILE>"
To automatically start the script after booting, we use the cron deamon, which is used to execute program's at a given time.
Edit the job list by executing:
crontab -e
This should open a file in a text editor (maybe you have to select one). After the file is opened, append the following lines to the crontab file and save it:
SHELL=/bin/sh
@reboot /bin/sh /home/pi/LEDTableEngine/start.sh
This line will ensure, that the start script is called after booting the computer (just reboot now). If an error occurs and the engine doesn't start, you can have a look at the log file, created in /home/pi/LEDTableEngine/log.txt