-
Notifications
You must be signed in to change notification settings - Fork 5
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.
If you also have my game controllers from Thingiverse, you have to connect them to the I2C-GPIO pins of the Raspberry Pi.
Just type the following commands directly into your command line to setup the engine!
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
If you are using the custom game controllers, you have to install i2c-tools. The setup instructions are summarized on Adafruit. If the engine does not compile (Errors with SMBUS in their name), you also have to install the libi2c-dev files:
sudo apt-get install libi2c-dev
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 .. && 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 found in the source code (keyboardInput.cpp) or summarized here (player 1 and 2):
- Up: w/UP
- Down s/DOWN
- Left a/LEFT
- Right d/RIGHT
- Enter e/ENTER
- Exit q/BACKSPACE
- A r/o
- B f/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?
You should now see a main menu on your matrix table. The actual key mapping can be found in the source code (but also depends on the way, you soldered the buttons!): gameControllerInput.cpp Summarized here for each player:
- TODO
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 -k <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 -k <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 ./LEDMatrixTable -c matrix -i keyboard -k <KEYBOARD_DEV_FILE>
If you use the game controllers as input device, read the corresponding section above and execute the following command:
./LEDMatrixTable -c matrix -i i2c -k <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:
If you want to use the I2C controllers, you have to modify the start script (scripts/start.sh):
nano ~/LEDTableEngine/scripts/start.sh
Have a look at line 12 and insert your i2c device file from the section above:
i2cDev="\<i2C_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 edit a file in a text editor (maybe you have to select one). After the file is opened, append the following file to the crontab file and save it:
@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