Lua Reference

Important notes

Please make sure you did not switch lua off in the config otherwise it will not work.

Also if you already have a license make sure it includes the lua runtime. Check the logfile and look out init.lua gets searched and loaded and for your lua functions being called when you trigger tests.

See the lua example videos on my youtube channel: e.g.

Global variabels

config: all the main config parameters from the raspisound.ini file as lua table. That means you can access it like config.say_version.

version: the version of the TILT!Audion firmware as string. e.g. “1.29”

musicPlayingId: the number of the currently playing background music (or 0 if none).

effectiveVolume: the effectiveVolume (overall volume).


playSound(id, volume, index): play a sound effect (or background music) from sound pack.
id: the sound effect id.
volume (optional): if set (0-30) override the standard volume from sound pack and play with given volume.
index (optional): if set, use a specfic sound file for the effect. This is only relevant, when the sound pack defines more than one sound file for this effect.

getSound( id ): returns a lua table (or nil) for the sound effect with given id. the lua table contains the properties:
name: the name of the sound effect.
samples: number if sound files for the effect (normally 1).
type: 1-6 depending on sound type: music, voice, effect ..
command: string if the effect has an command attached

getCurrentSoundPack(): returns the current sound pack as lua table.

port( pinNumber, value): set port to high or low. pinNumber is one of the valid Raspberry Pi pins the can be used for output (basically the shaker pin) or 100-115 for port extender pins. value = 0 -> LOW output, value != 0 -> HIGH output.

portseq( pinNumber, time1, time2, … ): queue a sequence of HIGH, LOW changes for a GPIO pin. pinNumber see above. time1, time2 … define the intervals in milliseconds, that will make the output go HIGH-LOW-HIGH …

send( command ): send a string command to attached device (either serial or via TCP, depending on config). Can be used with the serial media server.

sendI2C( deviceAdress, reg, data): send a command to an attached i2c device. deviceAddress is 1 Byte device address on i2c bus. reg is 1 byte register number, data is one byte data to write to register.

sendI2CW( deviceAdress, reg, data): send a command to an attached i2c device. deviceAddress is 1 Byte device address on i2c bus. reg is 1 byte register number, data is two byte data to write to register.

readI2C( deviceAdress, reg): read data from an n I2C device and returns an int.

log( logLevel, message ): logs a message into main logfile. logLevel: 1=ERROR up to 4=DEBUG, message a string with log message. NOTE: normal print output will also go to the logfile if DEBUG is switched on.

setVolume( newVolume ): set a new volume, value 0-100

decVolume(): decrease volume

incVolume(): increase volume

nextSoundSet(): cycle through installed sound packs

restart(): restart TILT!Audio firmware

reboot(): reboot the raspberry pi completely

pauseMusic(): pause background music

resumeMusic( ms ): resume pause background music and fade back in ms = milli seconds

stopMusic(): stops background music

fadeMusic( milliSeconds ): fades background music in milliSeconds

fadeOutSfx( milliSeconds): fades out sfx sounds in milliSeconds

fadeOutVoice( milliSeconds): fades out voice sounds in milliSeconds

fadeOutAllEffects( milliSeconds): fades out both woice and sfx in milliSeconds

stopAllSamples(): stops all running sound effects other than background music

omx player commands (beta)

omxPause(): pause player playback

omxAction( action ): perform an action on player. action numbers see OMXControl.h

omxSetPos( pos ): set playback position absolute in milli seconds

omxStop(): stop player playback

omxPlay( file ): play a new file

omxGetPos(): get the current playing pos in milli seconds.

omxGetStatus(): return current player status: 0 = pause, 1 = playing

Handlers (beta)

There are two special lua functions in your script recognized at startup. They are called handlers. Just put a function named timer or eventHandler and it will be called like described:

timer( millis ): this function gets called every milli second (approximately). It is run in the main loop of TILT!Audio firmware (will be changed maybe), so don’t block anything and keep the function short and fast.

eventHander( stringMessage): it the event handler feature is enabled with TILT!Audio, every time the firmware receives an event, the function gets called.

Test a TILT!Audio board

In order to test your TILTAudio board including the WPC bus interface to the pinball machine you can use an arduino mega board.

Just connect the mega with the TILT!Audio board like this:

Connections from the Arduino mega to WPC bus on TILT!Audio

Connecting also the 5v power line is optional. You need to choose either to power everything from on source or just skip the red 5v wire and power the 5v on the TA board and the Arduino separately.

For the address decoder (the smd chips) to work the raspberry pi needs to be plugged in as the 3v3 power for the decoder comes from the pi’s onboard regulator.

Also the resistor network RN3-5 must be installed, without them bus connections are not there. 12V can be skipped for testing, which means amps will not work, but you could also connect a speaker either to the PI’s audio jack directly or use the audio jack on the DAC module.

Then load the following ino script to the Arduino:

This way you can emulate sound effect commands to would normally come from the pinball machine.

I will upload a more detailed example on the github repo:

Connections needed:

PA0:22CD0 wpc15
PA1:23CD1 wpc13
PA2:24CD2 wpc11
PA3:25CD3 wpc9
PA4:26CD4 wpc7
PA5:27CD5 wpc5
PA6:28CD6 wpc3
PA7:29CD7 wpc1
PC0:37CA0 wpc25
PC1:36CA1 wpc23
PC2:35CA2 wpc21
PC3:34CA3 wpc19
PC4:33CA4 wpc17

Quick Start

What is it?

TILT!Audio is a free time project that aims to get you a replacement for your audio board in your pinball game. It works with data east, wpc and white star games.

What do I need?

You need a board (PCB) and a couple of electronic components (SMD chips, resistors and some pre assembled modules), a raspberry pi (3B or newer recommended, but 3A and even zero also works) and a micro sd card for the software and the new sounds to use. Maybe some additional wires as you are going to get stereo sound on old wpc machines.

The PCB designs are free and you can create one or order one on your own if you like. Just checkout out Alternatively you can order a kit including all required components and a PCB in my shop.

Finally to run the software without licensing hints for more than just 10 minutes you need a license (also available in my shop).

Can I do it on my own?

Some soldering skills are required. Some basic understanding of your pinball electronics (it is not plug and play). Some computer knowledge on how to flash a micro sd card with an “image” and maybe extracting a zip file.

Step by Step

  1. Assembly: First you need o assemble the board, there are a couple of hints and also a video available on the assembly page on this website. As there were already many board revision, be sure that you only look for your board revision not older outdated ones.
  2. Prepare the micro SD Card for the pi: get a 16GB micro sd card a flash the latest image onto the card using a tool like balena etcher. Add a sound pack for your machine into the data/sound directory on the sd card. Sound packs are available from the virtual pinball community on Just look for your machines rom abbreviation (see on
  3. Optional for sd card: add an to the sd card update if there is a patch update newer that the latest image available. Latest versions see below.
  4. Check the initial setting for your machine: (only for board rev < 3.5, newer boards can skip this step): there is a jumper on the board that needs to be set to DE if your machine is data east or white star and to WPC for all wpc machines. Open the raspisound.ini file in the data/sound diectory and add one line with “vendor=0” for data east, “vendor=1” for WPC, “vendor=5” for WPC DCS and “vendor=7” for white star.
  5. Prepare speaker wiring: for old wpc machines you need to change the speaker wiring, as you will get stereo in the backbox plus mono in the cabinet (2.1 sound). see here. Lookup out for the speaker connectors on the bottom of the board and change your speaker wiring accordingly. You could also think of replacing the original speakers with better replacement ones to get even better sound (and you really should!!)
  6. Turn down the volume: before putting the board in and start up the pinball turn down the volume to almost minimal by turning to two onboard pots to the left (CCW) and then slightly back to right some degrees.
  7. Apply the raspberry pi: put the micro sd card into the pi and then put the pi upside down onto the board.
  8. Replace the sound board: pull out the old sound board from the pinball machine and replace it with the new TILT!Audio board. Note: not all the former connections are needed / are the same. For WPC the speaker wiring is changed (see 5) also the logic power connector (on the left) is not needed only the aux power J501 at the bottom.
  9. Switch on the pinball machine: for WPC boards you should see the DC power module led and in any case the led on the DAC module light up. If you installed an OLED status display shortly after boot the TILT!Audio logo should appear. After 20 seconds you should hear a boot sound.
  10. Configure via Wifi (optional): if your pi has wifi (normally always the case) after a few minutes you should see a new wifi network “TILTAUDIO”. You can connect your computer or smart phone using the password “tiltaudio” and then connect to to get to the webUI. This is only necessary if you some of the initial setup steps above did not match your machine setting or for more expert configurations. if you have the right vendor setting applied and a sound pack installed you should already be able to play your first game with new sound experience.

Latest image version is 1.34 can be downloaded here:

Latest update patch (see changelog) can be found here: please be sure to rename the zip file to before copying to the update folder onto the sd card.


I can’t hear any sound, not even boot chime.

Check speaker connection wires. Check on board pots if volume is not completely down to zero (all to the left).
If you have access to web UI goto audio device settings and try a different audio device.

I can’t hear only boot sound, but game does not start playing music or react to game play

Check if jumper setting matches your game type (see 4 above). Also check the vendor setting in the raspisound.ini file. If you have access to the web UI you can also check vendor settings on the config page.
Also check the connection of the data cable (ribbon cable).

Raspberry pi does not boot and no led is lighting up on the DAC module.

Check power supplies: on wpc check fuse. (older boards also data east). Check correct connection of power supply connectors J501 for WPC and CN2 for data east.

Data east cabinet pot for volume control does not work

Check CN3 connector to cabinet pot (top side of the board). for newer boards: is the ADC module applied? for older boards: enable_dataest_volume set to true?

I hear sound triggered in the web ui, but not in the game.

Check data connections and the jumper must be set accordingly (DE or WPC)

Please also check the FAQ.