Overview

On this page you find the instructions on how to install the App. Both for End-Users and Developers.

Prerequisites

• Raspberry Pi 3 | 4 | 5 with Raspbian Bookworm

Normal Installation

Installing V-Link is straightforward. All you need to do is download the Install.sh from the current release and execute it. Simply run the following commands in a terminal:

wget "https://github.com/BoostedMoose/v-link/releases/download/v3.0.1/Install.sh"
sudo chmod +x Install.sh
sudo ./Install.sh

What is being installed?

The installer performs several tasks to set up your Raspberry Pi and save you from the hassle of doing it manually. In detail, it does the following:

• Downloads V-Link and unzips it to ~/v-link
• Creates a virtual environment and installs the necessary Python packages
• Downloads and installs the custom DTOverlay for the V-Link HAT
• Writes the config to /boot/firmware/config.txt
• Creates a service to autostart the app
• Sets up permissions

Once you've run the installer and the Raspberry Pi has been configured, there is no need to run the installer again! If you experience any issues with the app, they can only be related to the files in the ~/v-link folder or your settings files.

If you wish to reinstall the app, simply remove the existing files by running these commands:

sudo rm -rf ~/v-link
sudo rm -rf ~/.config/v-link

mkdir ~/v-link

Afterwards, you just need to download the .zip from the latest release again and unzip it into the ~/v-link folder that you created with the last command.

The only thing you are missing now are the Python packages:

cd ~/v-link
python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

Afterwards you can launch the app again. It will created the configuration folder automatically.

python ~/v-link/V-Link.py --h (This flag shows all available options)

Dev Installation

When you want to install V-Link in the development environment, it's just as simple. I recommend first using the installer mentioned above to setup the Pi. Afterwards you can run the following commands:

git clone https://github.com/BoostedMoose/v-link.git
cd v-link
python -m venv venv
source /home/$USER/v-link/venv/bin/activate
pip install -r requirements.txt
cd frontend
npm i & npm run build

cd /home/$USER/v-link/frontend
npm run vite

cd /home/$USER/v-link
python V-Link.py --vite

Node v18.12.1
NPM 8.19.2

Further setup

When installing everything manually you need to set up certain features. Below you can find a list of commands to enable all necessary ports and access rights:

Enabling CAN:

sudo ip link set can1 type can bitrate 500000
sudo ip link set up can1

sudo ip link set can2 type can bitrate 125000
sudo ip link set up can2

Enabling uiinput & vcan:

sudo modprobe uinput
sudo modprobe vcan

Rules for /etc/udev/rules.d/42-v-link.rules:

SUBSYSTEM=="usb", ATTR{idVendor}=="1314", ATTR{idProduct}=="152*", MODE="0660", GROUP="plugdev"
KERNEL=="ttyS0", MODE="0660", GROUP="plugdev"
KERNEL=="uinput", MODE="0660", GROUP="plugdev"

Entries for boot/firmware/config.txt

These are the entries for /boot/firmware/config.txt:

[V-LINK RPi3]

#Enable GPIO 0&1
disable_poe_fan=1
force_eeprom_read=0

#Enable devicetree overlays
dtoverlay=disable-bt
enable_uart=1

dtparam=i2c_arm=on
dtoverlay=v-link
dtoverlay=mcp2515-can1,oscillator=16000000,interrupt=24
dtoverlay=mcp2515-can2,oscillator=16000000,interrupt=22

#Configure IGN logic
dtoverlay=pi3-disable-bt
dtoverlay=gpio-poweroff,gpiopin=0

#No Splash on boot
disable_splash=1

[V-LINK RPi4]

#Enable GPIO 0&1
disable_poe_fan=1
force_eeprom_read=0

#Enable devicetree overlays
dtparam=spi=on
enable_uart=1
dtparam=i2c_arm=on

dtoverlay=v-link
dtoverlay=uart3
dtoverlay=mcp2515-can1,oscillator=16000000,interrupt=24
dtoverlay=mcp2515-can2,oscillator=16000000,interrupt=22

#Configure IGN logic
dtoverlay=pi3-disable-bt
dtoverlay=gpio-poweroff,gpiopin=0

#No Splash on boot
disable_splash=1

[V-LINK RPi5]

#Enable GPIO 0&1
disable_poe_fan=1
force_eeprom_read=0

#Enable devicetree overlays
dtparam=spi=on
enable_uart=1
dtparam=i2c_arm=on

dtoverlay=v-link
dtparam=uart0=on
dtoverlay=uart2-pi5
dtoverlay=mcp2515-can1,oscillator=16000000,interrupt=24
dtoverlay=mcp2515-can2,oscillator=16000000,interrupt=22

#Configure IGN logic
dtoverlay=pi3-disable-bt
dtoverlay=gpio-poweroff,gpiopin=0

#No Splash on boot
disable_splash=1

Custom Overlays

The app uses custom Devicetree Overlays. You can find them here. The overlays need to be copied to /boot/firmware/overlays.

Making changes

The app is generally divided into two parts: the Frontend and the Backend.

The Frontend is the interface you see when you launch the app. It's a web app running in a frameless Chromium window. Files related to the frontend can be found in the corresponding folder. The frontend is developed with React.js.

The Backend serves the frontend and handles low-level communication with the Raspberry Pi, such as talking to the HAT and various modules. This is where all the data is processed and passed around. The backend is written in Python.

Communication between the backend and frontend is done through Socket.IO.

If you make any changes to the frontend, you will see them directly when you run the app with the --vite flag. However, testing your app in a production environment requires bundling it. You can find a handy script in the .dev folder of the repository. Using it will bundle your files into a .zip located in v-link/dist. You can then use this .zip to overwrite the files of the installed app in ~/v-link, as described above.

Uninstalling

cd ~/v-link/
sudo chmod +x Uninstall.sh
./Uninstall.sh

The Uninstall.sh script removes entries from the following location. This is only supported from 2.2.0 onwards. Earlier installations need to be removed manually.

/etc/udev/rules.d/
/etc/xdg/autostart/
/etc/network/interfaces
/home/$USER/.config
/boot/firmware/config.txt
/etc/systemd/system/
/etc/sudoers.d/