TILT!Audio – Page 5 – Best audio for your pinball machine

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. https://www.youtube.com/watch?v=Se2uvYuHbf0

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).

Functions

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

fadeOutID( ID, milliSeconds): fades out a specific sound (referred by ID) 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.

Shaker control with pwm

Using a Arduino mini pro as extension to a TILT!Audio board, you can easily control a shaker motor via pwm (pulse width modulation).

First we need a motor driver module that is capable of driving the high current motor power. e.g. something like this:

The picture is more or less self-explaining the only thing that need to be connected to the Arduino mini pro is the GND / PWM input.

Now looking at the Arduino mini pro we use pin 5 as pwm output and to connect to the TILT!Audio board we use the i2c bus the is controlled by the SCL / SDC pins (together with GND / Vcc of course):

Be sure to choose a 5v type for Arduino mini pro as there are also available in 3.3v but the TILT!Audio connector for the i2c bus provides 5v. Also the 5v type runs on 16Mhz instead of only 8Mhz for 3.3v with is also good.

So connections are:

From	To
TA-Board: GND	GND (right side)
TA-Board: Vcc	VCC (right side)
TA-Board: SDA	SDA (green)
TA-Board: SCL	SCL (green)
Arduino: GND	Power Driver: GND (right)
Arduino: Pin5 (PWM)	Power Driver: PWM (right)

Now we create a script for the Arduino mini pro like this (see https://github.com/sker65/tiltaudio-extensions). We start with initial setup stuff:

#include <Wire.h>

#define I2C_MSG_IN_SIZE    2
#define I2C_MSG_OUT_SIZE   4
#define I2C_ADDRESS 0x61
#define PWM_PIN 5

void setup() {
  // init i2c bus
  Wire.begin(I2C_ADDRESS);
  Wire.onReceive(receiveEvent);
  // not used Wire.onRequest(requestEvent);
  // init PWN output
  pinMode(PWM_PIN, OUTPUT);
}

#include <Wire.h>

#define I2C_MSG_IN_SIZE 2

#define I2C_MSG_OUT_SIZE 4

#define I2C_ADDRESS 0x61

#define PWM_PIN 5

void setup() {

// init i2c bus

Wire.begin(I2C_ADDRESS);

Wire.onReceive(receiveEvent);

// not used Wire.onRequest(requestEvent);

// init PWN output

pinMode(PWM_PIN, OUTPUT);

}

First thing we do is switch shaker on, off and set speed (within a limited range to not make to pinball machine jump):

int currentSpeed = 1;
int maxSpeed = 20;

void off() {
   analogWrite( PWM_PIN, 0 );
}

void on() {
   analogWrite( PWM_PIN, currentSpeed );
}

void setSpeed( int speed ) {
  if( speed > 0 && speed <= maxSpeed ) {
    currentSpeed = speed;
  }
  on();
}

int currentSpeed = 1;

int maxSpeed = 20;

void off() {

analogWrite( PWM_PIN, 0 );

}

void on() {

analogWrite( PWM_PIN, currentSpeed );

}

void setSpeed( int speed ) {

if( speed > 0 && speed <= maxSpeed ) {

currentSpeed = speed;

}

on();

}

Second we wire these functions to i2c control:

void receiveEvent(int count)
{
  if (count == I2C_MSG_IN_SIZE)
  {
    byte cmd = Wire.read();
    byte value = Wire.read();
    switch( cmd ) {
      case 0x01:
        on();
        break;
      case 0x02:
        off();
        break;
      case 0x03:
        setSpeed(value);
        break;
      default:
        // unknown command
    }
  }
}

void receiveEvent(int count)

{

if (count == I2C_MSG_IN_SIZE)

{

byte cmd = Wire.read();

byte value = Wire.read();

switch( cmd ) {

case 0x01:

on();

break;

case 0x02:

off();

break;

case 0x03:

setSpeed(value);

break;

default:

// unknown command

}

And additionally we can create “sequences”. A sequence would play back some schema of on and off or speed up and speed downs. The idea is to define a sequence as 3 integers: command byte, value, interval in milliseconds. We define these commands:

0x00: stop -> end of the sequence
0x01: switch on, value -> speed
0x02: switch off, value -> don’t matter
0x03: ramp up, value -> target speed at end of interval

We delegate playing those sequences to the Arduino and later just trigger it from the TILT!Audio board by sending some command to the i2c bus:

#define END 0x00
#define ON 0x01
#define OFF 0x02
#define RAMP 0x03
#define SETSPEED 0x04
#define PLAYSEQ 0x05

int sequences[] = { ON, 5, 500, OFF, 0, 500, ON, 5, 500, END };
int* seqPtr = NULL;

unsigned long nextAction = 0; // timer marker for next action
float rampInc;                // speed incs for ramps in steps
int rampNo = 0;               // counts number of step in ramp phase

void loop() {
  unsigned long now = millis();
  if( now > nextAction ) {

    // ramp active
    if( rampNo > 0 ) {
      nextAction = now + 50;
      setSpeed( currentSpeed + rampInc );
      rampNo--;
    } else {
      // read next command from sequence
      int cmd = *seqPtr++;
      if( cmd == END ) {
        seqPtr = NULL; // end of sequence
        nextAction = 0;
      } else {
        int val = *seqPtr++;
        int delay = *seqPtr++;
        nextAction = now + delay;
        switch(cmd) {
          case ON:  setSpeed(val); break;
          case OFF: off(); break;
          case RAMP:
            rampNo = delay / 50; // inc every 50ms
            nextAction = now + 50;
            rampInc = (val - currentSpeed) / (float) rampNo; 
        }
      }
    }
  }
}

#define END 0x00

#define ON 0x01

#define OFF 0x02

#define RAMP 0x03

#define SETSPEED 0x04

#define PLAYSEQ 0x05

int sequences[] = { ON, 5, 500, OFF, 0, 500, ON, 5, 500, END };

int* seqPtr = NULL;

unsigned long nextAction = 0; // timer marker for next action

float rampInc; // speed incs for ramps in steps

int rampNo = 0; // counts number of step in ramp phase

void loop() {

unsigned long now = millis();

if( now > nextAction ) {

// ramp active

if( rampNo > 0 ) {

nextAction = now + 50;

setSpeed( currentSpeed + rampInc );

rampNo--;

} else {

// read next command from sequence

int cmd = *seqPtr++;

if( cmd == END ) {

seqPtr = NULL; // end of sequence

nextAction = 0;

} else {

int val = *seqPtr++;

int delay = *seqPtr++;

nextAction = now + delay;

switch(cmd) {

case ON: setSpeed(val); break;

case OFF: off(); break;

case RAMP:

rampNo = delay / 50; // inc every 50ms

nextAction = now + 50;

rampInc = (val - currentSpeed) / (float) rampNo;

}

And again create a function that triggers the sequence playback and wire it to i2c control:

void playSequence( int startIndex ) {
  if( startIndex >= 0 && startIndex < sizeOfSequences ) {
    seqIdx = startIndex;
    nextAction = millis();
  }
}

// add another case in receiveEvent

      case PLAYSEQ:
        playSequence(value);
        break;

void playSequence( int startIndex ) {

if( startIndex >= 0 && startIndex < sizeOfSequences ) {

seqIdx = startIndex;

nextAction = millis();

}

// add another case in receiveEvent

case PLAYSEQ:

playSequence(value);

break;

Find the complete example on github.

To get an idea, how it finally will play all together I did a test installation:

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:

void setup() {
   // set gpio mode
   DDRC = 255; // switch port c completely to output
   DDRA = 255; // switch port a completely to output
   PORTA = 255; // high
   PORTC = 255; // high
   pinMode(LED_BUILTIN, OUTPUT);
}
int data[] = { 0x01, 0x20, 0, 0 };
int ledState = 0;
void play(int start, int end ) {
   for( int i = start; i <= end; i++ ) {
     delayMicroseconds(900);
     PORTA = data[i];
     PORTC = 0b01011100;      // sound address + rw = low, with wden high
     delayMicroseconds(20);
     PORTC = 0b00011100;      // sound address + rw = low, with wden low
     delayMicroseconds(30);
     PORTC = 0b01011100;      // sound address + rw = low, with wden high
   }
}
void toggleLed() {
   digitalWrite(LED_BUILTIN, ledState);
   ledState = !ledState;
}

void loop() {
  play(0,1);
  delay(2000);
  toggleLed();
  data[2] = random(4);
  data[3] = random(256);
  play(2,3);
  delay(4000);
}

void setup() {

// set gpio mode

DDRC = 255; // switch port c completely to output

DDRA = 255; // switch port a completely to output

PORTA = 255; // high

PORTC = 255; // high

pinMode(LED_BUILTIN, OUTPUT);

}

int data[] = { 0x01, 0x20, 0, 0 };

int ledState = 0;

void play(int start, int end ) {

for( int i = start; i <= end; i++ ) {

delayMicroseconds(900);

PORTA = data[i];

PORTC = 0b01011100; // sound address + rw = low, with wden high

delayMicroseconds(20);

PORTC = 0b00011100; // sound address + rw = low, with wden low

delayMicroseconds(30);

PORTC = 0b01011100; // sound address + rw = low, with wden high

}

void toggleLed() {

digitalWrite(LED_BUILTIN, ledState);

ledState = !ledState;

}

void loop() {

play(0,1);

delay(2000);

toggleLed();

data[2] = random(4);

data[3] = random(256);

play(2,3);

delay(4000);

}

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: https://github.com/sker65/tiltaudio-extensions

Connections needed:

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