Skip to content

Software tutorials

Jump to bottom Edit New page
Yoan Mollard edited this page Dec 29, 2017 · 18 revisions

Getting started with Arbalet software in simulation or with hardware

Introduction

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 master vs dev branches)

You might have noticed that Arbalet repositories have two branches master and 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 --standalone or -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.

Install procedure

Windows

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:

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 .git part in the URL and retry
  • Always eliminate the sudo keyword in commands, it does not exist on Windows

Then jump to Install the SDK and apps.

Linux

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 pip:

~/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

General form

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

In short:

  • arbalet.apps.some.application is the hierarchical module path of the app
  • Depending on the app, it may accept different optional or compulsory parameters, adding --help as paraamter will describe you the specific parameters of this app
  • Optional parameter --no-gui (same as -ng) tells Arbalet you don't want a simulation window to pop up
  • Optional parameter --hardware (same as -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.colors with no argument will execute a swipe color animation in simulation only
  • This app accepts a -t argument to specific the type of animation, try for instance python -m arbalet.apps.colors -t flashes
  • python -m arbalet.apps.colors -t gender -w -ng will display the app with another type called gender to 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 -h to 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 back to change app or start to reset the game
  • Open the snap server for visual programming: python -m arbalet.tools.snap

Arguments

Arbalet apps can be passed arguments, specific to this app or common to all apps. The latest are:

  • --hardware or -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.
  • --no_gui or -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) --standalone or -o: Causes the app to also trigger background servers if you're using SDK v4 (i.e. git dev branch). This argument is mandatory on v4 in most cases.

The following are common to all apps but less often used:

  • --config or -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.
  • --brightness or -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.15 to decrease luminosity. This may crenelate the colors and produce visible defaults.
  • --server or -s: This argument allow to stream the display over the network to an Arbaserver instance running on another laptop that is itself connected to the table. Example: A Raspberry Pi running the Arbaserver app 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.11 to share the table. Arbaserver is yet experimental, currently several clients will end up to bad results.
  • --factor_sim or -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 --input and -i flags.

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 Application class.

Add a custom footer
Add a custom sidebar
Clone this wiki locally