Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Clone this wiki locally
Getting started with Arbalet software in simulation or with hardware
In this step, we will get familiar with the Arbalet software environment. Although this step generally occurs after having built the table, there is no obligation since the table can be simulated. So if you're still hesitating to buy the components or are waiting for your electronic order to be shipped you can also follow this software guide and start executing applications in simulation.
Preliminary notice: version 3.x versus 4.x (aka
You might have noticed that Arbalet repositories have two branches
dev which handles respectively software version 3 and version 4. Version 3 is stable, although various improvements are pushed from time to time.
Version 4 allows more flexibility regarding software. The main difference with v3 is that software v4 is multiprocess. This feature allows running greedy apps (e.g. AI players) on light hardware (e.g. Raspberry Pi) and also fixes a pygame event bug that you might meet on Windows (causing
Arbalet not responding message) or on MacOS (causing a full crash). Instead of handling all services in a single process, work is dispatched in background server processes, that you must run by adding
-o option, e.g.
python -m arbalet.apps.tetris -o.
If you wanna code or running Windows or MacOS, v4 suits more. It will be merged in master soon after deeper tests on a few Arbalet projects.
Windows support is still experimental, but main features should work. It requires a bunch of libs and then works similarly than Linux from command line. Here are the instructions:
- Install python for Windows
- Install git for Windows
- Install pygame for Windows, the latest version for python 2.7 will be fine
Then open the "git bash prompt" from the icon in your Windows menu. It opens a prompt, with most of the built-in Unix tools installed. Continue by installing the dependencies with pip, by copy/pasting these in the Bash terminal:
pip install ipython(Press ENTER to execute the command)
You can then follow the rest of this tuto from the Bash prompt as if you were on Linux, with two remarks:
- If you get errors when cloning the repositories, please eliminate the
.gitpart in the URL and retry
- Always eliminate the
sudokeyword in commands, it does not exist on Windows
Then jump to Install the SDK and apps.
The only officially tested Linux platforms are: Ubuntu 14.04 x64, Ubuntu 16.04, Linux Mint x64, Raspbian Jessie but installation should go well for all other Linux platforms.
For Raspberry Pi
If you are installing Arbalet on a Raspbian (for Raspberry Pi 2 or 3 without using Arduino), this process will help you setting up your Pi.
The default configuration considers that you're using the
SPI MOSI (GPIO 10) pin to connect your LED strips. However you might experience artifacts (flashes) with this technique. You can modify the configuration file to use an Arduino instead, or PWM on
GPIO 18 (WIP, but requires root access).
Other Debian-based distros
For other distros connecting to hardware with Arduino, installing these packages from system repositories will make faster and easier the rest of the setup:
sudo apt-get install git python2.7 python-setuptools ipython-notebook python-pygame python-numpy python-xlib python-bottle python-opencv python-pyaudio libportaudio-dev python-dev
Install the SDK and apps
You should have cloned the repositories already, prior to firmware uploading. If not, open a terminal and type:
~ $ mkdir Arbalet && cd Arbalet ~/Arbalet $ git clone --recursive https://github.com/arbalet-project/arbasdk.git ~/Arbalet $ git clone https://github.com/arbalet-project/arbapps.git ~/Arbalet $ git clone https://github.com/arbalet-project/arbadoc.git
Then go to the SDK and install it as well as all its dependencies with
~/Arbalet $ cd arbasdk ~/Arbalet/arbasdk $ sudo python setup.py install # You will be asked for your password to install these packages)
Since applications are also installable it is easier to do it now:
~/Arbalet $ cd arbapps ~/Arbalet/arbapps $ sudo python setup.py install # You will be asked for your password to install these packages)
Installed applications will have the advantage of being executable from any directory.
Execute existing applications
Once your SDK is installed, running a game or a light animation consists into typing a Python command on the form:
python -m arbalet.apps.some.application --some-parameter=42 --hardware --no-gui
arbalet.apps.some.applicationis the hierarchical module path of the app
- Depending on the app, it may accept different optional or compulsory parameters, adding
--helpas paraamter will describe you the specific parameters of this app
- Optional parameter
-ng) tells Arbalet you don't want a simulation window to pop up
- Optional parameter
-w) tells Arbalet you want to connect to the real hardware (requires that you have built and connected it!) using the technique described in the configuration file
Concrete Examples to run applications and games
From any directory, try typing the following examples in a terminal and eventually provide some arguments to run applications and games:
python -m arbalet.apps.colorswith no argument will execute a swipe color animation in simulation only
- This app accepts a
-targument to specific the type of animation, try for instance
python -m arbalet.apps.colors -t flashes
python -m arbalet.apps.colors -t gender -w -ngwill display the app with another type called
genderto the table with no simulation view (will fail in loop if no hardware is connected)
- To get the list of accepted arguments you can tweak, add
-hto any app:
python -m arbalet.apps.colors -h
- Play Tetris in simulation:
python -m arbalet.apps.tetris
- Play Snake in simulation:
python -m arbalet.apps.snake
- Visualize an AI playing Snake in simulation:
python -m arbalet.apps.snake.ai
- Start playing a song in your favorite music player, and enjoy it on the table with the musical spectrum analyser:
python -m arbalet.apps.spectrum
- Wanna play to Guitar Hero on your Arbalet table? Play to Lights Hero, hold your keyboard as a guitar and press keys F1 to F5 when notes are coming to the bumps (based on Frets on fire:
python -m arbalet.apps.lightshero
All individual applications are located into
arbalet.apps, other binaries are present though in
arbalet.tools, such as the application sequencer that runs all apps in a loop (sort of a demo mode):
- Open the demo mode as is:
python -m arbalet.tools.sequencer. Press joystick button
backto change app or
startto reset the game
- Open the snap server for visual programming:
python -m arbalet.tools.snap
Arbalet apps can be passed arguments, specific to this app or common to all apps. The latest are:
-w: This will cause the SDK trying to connect to the physical table. Pass this argument if your laptop is directly connected to the table via USB.
-ng: By default a simulated view of the table displays on screen, whether you are connected to the physical table or not. If you do not want such simulation, pass this argument. This is useful to save CPU time or when running headless.
- (only on v4)
-o: Causes the app to also trigger background servers if you're using SDK v4 (i.e. git
devbranch). This argument is mandatory on v4 in most cases.
The following are common to all apps but less often used:
-c: If you have built a custom table you need to tell the SDK how your table geometry is with a config file. Give a file name to this argument if you do not want to use the default 150 pixels table.
-b: Attenuate the table brightness. In the dark full brightness (
-b 1.0) may be aggressive for our poor eyes, pass a float like
-b 0.15to decrease luminosity. This may crenelate the colors and produce visible defaults.
-s: This argument allow to stream the display over the network to an
Arbaserverinstance running on another laptop that is itself connected to the table. Example: A Raspberry Pi running the
Arbaserverapp is connected to the table and to your network switch. Several clients can connect to the RPi using its IP address
--server 192.168.0.11to share the table.
Arbaserveris yet experimental, currently several clients will end up to bad results.
-f: This argument specify the size of the simulated table. This is the size of a side of a single pixel. Default = 30.
For applications needing an input file (input video, song, text file, and so on), it is generally good to use the
Now I want to create my app...
To get familiar to the SDK, start by following the 3 basic tutorials. The tutorials are interactive python notebooks you could follow them online with the links below and copy/paste cells into an ipython session but you should instead go to the
arbadoc repo that you have cloned and start a notebook session from there. In short:
~ $ cd Arbalet/arbadoc/notebooks/en ~/Arbalet/arbadoc/notebooks/en $ ipython notebook # Your browser should automatically open, click on the first tutorial
We start by using Arbalet in an interactive ipython session that helps to understand all these classes presented here above, only after we package our app into a