# FlippR Driver
This is a driver written to control Zaccaria pinball machines from the 2nd Generation. It controls the hardware that can be found in the [[flippr-circuit|https://gitlab.rhetenor.de/rhetenor/flippr-circuit]] repository.

An example game implementation for the Zaccaria Pinball Champ '82 can be found at [[flippr-game|https://gitlab.rhetenor.de/rhetenor/flippr-game]].

## Build Instructions
By default a static library gets build together with a networking target which enables communication over a UNIX Socket, for possible games.

### Dependencies
 * wiringPi [^1]
 * Boost: program_options thread timer chrono filesystem
 * libthread

 [^1]: Please note that wiringPi is deprecated and may not work on future releases of raspbian and most probably not on a Raspberry Pi5 and future versions.

### Build
To build the flippr-driver library run the following commands:
```sh1
$ mkdir flippr-code/Flippr-Driver/build
$ cd flippr-code/FlippR-Driver/build
$ cmake ..
$ make
```
This will create you the static-library file: _flippr-code/FlippR-Driver/bin/libFlippR-Driver.a_

The library uses wiringPi Pin numbering important for the config files

We added a script /usr/bin/reset_flippr this can be found in the repo and must be chosen in /etc/rc.local. It prevents the solenois from burning!

#### Build Options
 * `-DCROSS_COMPILE` Cross compile for raspberry pi. Default: Off
 * `-DBUILD_SHARED_LIB` Build a shared library. Default: Off
 * `-DENABLE_TESTING` Enables Tests after build. Default: On
 * `-DBUILD_NETWORKING` Builds the networking target binary. Default: On
 * `-DBUILD_CLI` Build a basic TUI to control the flipper by hand. Default: Off


 ## Usage
 ### Configuration
 The driver must be configured according to your needs and machine through JSON files. 
 
 Exemplary Files that describe this can be found in [[json_example|https://gitlab.rhetenor.de/rhetenor/flippr-code/src/branch/master/FlippR-Driver/contrib/json_example]]. 
 The Readme there contains all necessary information about the specific files.

### Networking
 When built with the networking target (default), the driver is accessible via two UNIX Domain Socket through a simple HTTP/REST API. 
 The sockets can be found either in the folder specified through the env variable `XDG_RUNTIME_DIR` or if it is not set in `/tmp`.

The sockets are:

* `S.flippR_driver.in`: All input events that occure on the pinball machine get pushed there.
* `S.flippr_driver.out`: With this socket the driver can be controlled.
 
An example connector writtin in Python can be found in the TUI [[FlippR_Networking.py|https://gitlab.rhetenor.de/rhetenor/flippr-code/src/branch/master/cli/FlippR_Networking.py]]

In the following subsection the API is described.

#### Output Socket
The following GET commands are understood by the Output Socket:

##### Solenoids

 * `/solenoids`: Returns all available solenoids
 * `/solenoids/ + name + /trigger`: Triggers the solenoid with the given name

##### Sounds

 * `/sounds`: Returns all available sounds
 * `/sounds/ + name + /play`: Plays the sound with the given name

##### Lamps

 * `/lamps`: Returns all available lamps
 * `/lamps/ + name + /activate`: Activates the lamp with the given name
 * `/lamps/ + name + /deactivate`: Deactivates the lamp with the given name
 * `/lamps/ + name + /status`: Returns the status of the lamp (active/inactive)

##### Displays

 * `/displays`: Returns all available displays
 * `/displays/ + name + /write_score/ + score`: Writes the given number to the display
 * `/displays/ + name + /write_content/ + content`: Writes the given content to the display

##### Flippers

 * `/flippers/ + name + /activate`: Activates the flippers (top or bottom)
 * `/flippers/ + name + /deactivate`: Deactivates the flippers (top or bottom)

#### Input Socket

The input socket events are character terminated with a 0x02 byte [^2] and contain the JSON events defined in the `Input Matrix Config`:
```
{
    "name": string,
    "address": number,
    "priority": number
}
```

[^2]: This should be 0x03 ETX (End of text)