monocoque/README.md

# Monocoque
```
___   |/  /____________________________________ ____  ______ 
__  /|_/ /_  __ \_  __ \  __ \  ___/  __ \  __ `/  / / /  _ \
_  /  / / / /_/ /  / / / /_/ / /__ / /_/ / /_/ // /_/ //  __/
/_/  /_/  \____//_/ /_/\____/\___/ \____/\__, / \__,_/ \___/ 
                                           /_/
```
Cross Platform device manager for driving and flight simulators, for use with common simulator software titles.

📚 **Documentation:** [spacefreak18.github.io/simapi/](https://spacefreak18.github.io/simapi/)

## Features
- Updates at 60 frames per seconds.
- Modular design for support with various titles and devices.
- Supports bass shakers, tachometers, several wheels, simlights, simwind etc, through usb and arduino serial.
- Tachometer support is currently  limited to the Revburner model. Supports existing revburner xml configuration files.
- Includes utility to configure revburner tachometer
- Can send data to any serial device. So far only tested with arduino. Includes sample arduino sketch for sim lights, simwind, and simhaptic effects for motors.
- Convincing shaker effects for noise tranducers for wheel slip, wheel lock, and abs, as well as engine rpm and gear shifts.
- Choice of Portaudio or Pulseaudio (libpulse) backend.

## Quick Install

**One-Line Installation:**
```bash
curl -fsSL https://raw.githubusercontent.com/Spacefreak18/monocoque/master/install.sh | bash
```

**Or download and review first:**
```bash
wget https://raw.githubusercontent.com/Spacefreak18/monocoque/master/install.sh
chmod +x install.sh
./install.sh
```

**TUI Manager:**
After installation, use the interactive manager:
```bash
monocoque-manager
```

**Supported Distributions:**
- ✅ Arch Linux (with AUR support)
- ✅ Debian/Ubuntu  
- ✅ Fedora/RHEL/CentOS
- ✅ openSUSE

For manual installation or troubleshooting, see [HOW-TO-USE.md](HOW-TO-USE.md).

## Supported Games ( see [simapi](https://github.com/spacefreak18/simapi) for more details of what is supported from each sim )
  - Using [SimSHMBridge](https://github.com/spacefreak18/simshmbridge)
    - Asseto Corsa
    - Assetto Corsa Competizione
    - Project Cars 2 (untested)
    - Automobilista 2
  
  - Using [scs-sdk-plugin](https://github.com/jackz314/scs-sdk-plugin/releases)
    - Euro Truck Simuator 2
    - American Truck Simulator

  - Using [rfactor 2 plugin](https://github.com/schlegp/rF2SharedMemoryMapPlugin_Wine)
    - RFactor 2

  - Using UDP
    - Automobilista 2
    - Project Cars 2 (untested)

## Dependencies
- libserialport - arduino serial devices
- hidapi - usb hid devices
- portaudio - sound devices (haptic bass shakers)
- libpulse - sound devices (haptic bass shakers)
- libuv base event loop
- libxml2
- argtable2
- libconfig
- xdg-basedir
- lua
- [slog](https://github.com/kala13x/slog) (static)
- [simshmbridge](https://github.com/spacefreak18/simshmbridge) - for sims that need shared memory mapping like AC and Project Cars related.
- [simapi](https://github.com/spacefreak18/simapi)
```
pacman -Syu git cmake pulse-native-provider libxdg-basedir libserialport libconfig libuv argtable hidapi lua
```

## Building
This code depends on the shared memory data headers in the simapi [repo](https://github.com/spacefreak18/simapi). When pulling lastest if the submodule does not download run:
```
git submodule sync --recursive
git submodule update --init --recursive
```

Then to compile simply:
```
mkdir build; cd build
cmake ..
make
```

to use the pulseaudio backend use this cmake command
```
cmake -DUSE_PULSEAUDIO=YES ..
```
## Bass Shaker Sound Devices

When using pulseaudio it is necesarry to provide a devid in the configuration. This command should list available sound cards with the "Name" being the "devid" needed in the monocoque config.
```
pactl list sinks | grep -E -i 'index:|name:' -A 4
```
One can generate sample sine waves at specific frequency on a specific channel on a specific sound card with this command (change -d to the Name of your desired target card and change 440 to any frequency)
```
ffmpeg -f lavfi -i "sine=f=440" -af "pan=7.1|c1=c0" -f wav pipe:1 | paplay --no-remap --no-remix -d alsa_output.pci-0000_00_1b.0.analog-stereo --volume=65536 -n "Monocoque" --stream-name="Haptic Test"
```
(BE CAREFUL!!! AS THIS SETS THE MAXIMUM STREAM VOLUME!!! the -n and --stream-name are optional but it helps you identify the stream in pavucontrol)
The channel map from the pactl command is the order of channels. Change c1 in this above command to the desired output channel.

The effects generated by monocoque should match the effects generated by this ffmpeg command. The frequency will differ slightly due to having to [fit in the buffer size](https://stackoverflow.com/questions/40078417/how-to-calculate-minimum-cycles-of-sine-wave-to-have-integer-n-cycles-in-a-buffe)
(monocoque lowers the target frequency until it fits in the audio buffer).

## Using Arduino Devices

Currently Monocoque supports simwind and shiftlights through the included arduino sketches which have been tested on Uno boards. The simwind controller requires a Motor shield.

There are included Makefiles for each controller. For now, the makefiles expect the device to be attached at /dev/ttyACM0. So unplug both controllers, and then plug in just the
controller you're updating to ensure the correct controller is at /dev/ttyACM0.

To compile and upload these sketches, the Makefiles use arduino-cli. Unfortunately it seems some distributions such as debian do not include this in the repositories. If this is
the case follow the install instructions here:
```
https://arduino.github.io/arduino-cli/0.35/installation/
```
You may have to download the core libraries, it will prompt you to do so if you do not have them and you go further
```
arduino-cli core install arduino:avr
```
Then for shiftlights navigate to included shiftlight directory ( be sure only the shiftlight controller is plugged into the machine and is available at /dev/ttyACM0 ) and

```
arduino-cli lib install FastLED
make
```
Then for simwind navigate to the included simwind directory ( be sure only the simwind controller is plugged into the machine and is available at /dev/ttyACM0 ) and
```
ARDUINO_LIBRARY_ENABLE_UNSAFE_INSTALL=true arduino-cli lib install --git-url https://github.com/adafruit/Adafruit_Motor_Shield_V2_Library.git
ARDUINO_LIBRARY_ENABLE_UNSAFE_INSTALL=true arduino-cli lib install --git-url https://github.com/adafruit/Adafruit_BusIO.git
make
```

### Uploading sketch to Arduino Uno
```
cd ../src/arduino/{simwind/shiftlights/simhaptic} # Depending on the controller you have.
make  # Make sure serial connection is the same as on the host pc and it have the right group permission to access the device without root
```

### SimHaptic Ardunio Motor Connection
- Acc Pedal Motor to be connected to M1 
- Brake Pedal Motor to be connected to M3
- you can actually connect the motors how you wish, but you'd have to make the appropriate changes to the config and to the arduino sketch.

## Getting car tyre diameter for rumbles to work
- User needs to start monocoque and drive the new car straight at 70 kmph and then stop steering, acc or brake input 

## User Setup Guide
See the dedicated [How To](HOW-TO-USE.md) for detailed instructions to set up and run 'monocoque`

## Testing
```
./monocoque test -vv # Make sure that ~/.config/monocque/monocoque.config only contains the devices you have connected.
```

### Static Analysis
```
    mkdir build; cd build
    make clean
    cmake -Danalyze=on ..
    make
```

### Valgrind
```
    cd build
    valgrind -v --leak-check=full --show-leak-kinds=all --suppressions=../.valgrindrc ./monocoque play
```

### Logs file location
`~/.cache/monocoque/*.log`

## Join the Discussion
[Sim Racing Matrix Space](https://matrix.to/#/#simracing:matrix.org)

## ToDo
 - add option to specify frame rate
 - add ability to set frame rate per effect
 - add frequency cap (low pass filter) to sound haptic effects
 - add road and kerb sound haptic effects
 - windows port
 - more memory testing
 - cleanup tests which are basically just copies of the example from their respective projects
 - much, much more