Development
This document will help you set up your development environment for both the Streamer and Viewer components.
If you are just a regular user, you can skip this section.
Reference Implementations¶
For a quick start into the codebase, we have collected a couple of reference implementations. Reviewing these commits commits will help you understand how to implement new features:
- Trigger an action from the WebUi
- Send a command from Viewer to streamer
- Add a new setting to the streamer config
- Add a tab to the Viewer Menu
Viewer¶
You can develop on any OS, though Linux is the prefered option. Make sure you have Python Version >=3.11.4 installed.
We recommend using pyenv for managing Python versions:
sudo apt install libssl-dev libbz2-dev liblzma-dev libncurses-dev libreadline-dev libsqlite3-dev tk-dev
curl -fsSL https://pyenv.run | bash
pyenv install 3.11.9
pyenv global 3.11.9
python --version
Info: You may need some dependencies, which are documented here for pyenv: https://github.com/pyenv/pyenv/wiki
Clone the repo and create a virtual environment:
git clone git@github.com:stylesuxx/v3xctrl.git
cd v3xctrl
python -m venv ./venv
source ./venv/bin/activate
Install 3rd party libraries:
- libcairo2
On Debian (and derivates) run:
Install python dependencies and run the GUI:
pip install -r ./build/requirements/viewer.txt
cd src
python -m v3xctrl_ui.main
# Run with debug logs enabled
python -m v3xctrl_ui.main --log DEBUG
Windows 11¶
NOTE: None of the project’s developers use Windows. We cannot offer detailed support for Windows development.
Windows setup is more cumbersome and should only be used if you’re comfortable troubleshooting on your own.
Use pyenv-win and follow the PowerShell-based installation path (tested). You may need to allow script execution:
Then follow the same steps as above to fetch the repo, install dependencies, and run the GUI.
To activate the venv you have created you need to run the activate file that has been created within the scripts folder. (instead of source ./venv/bin/activate)
Architecture¶
The viewer is one of the more complex parts architecture wise and is split up into multiple folders for easier contextualization:
- core: The core components "glue" together all the elements, telemetry context, general app state and the renderer all live here.
- menu: Functionality related to the menu and it's tabs. If you want to add more settings, this is the place you should be looking in
- network: Video receiver and control channel live here - this is by far the most complex part of the viewer. If you want to add an alternate video receiver, this would be the correct place.
- osd: Functionality related to the on-screen-display, widgets and telemetry parsing functionality. If you want to add telemetry or change how OSD elements look, this is the correct folder.
- utils: Shared functionality that is not easy to assign to any specific category above, small helper functions that are used here and there.
Streamer¶
For development, it’s strongly recommended to use the provided custom PiOS image as a starting point.
Setup¶
By default the /root and / partitions are mounted read-only. To build or install on the Streamer, you need to temporarily switch to read-write mode:
This change is persistent until you switch back to read-only mode and requires a reboot to take effect.
When you’re done, don’t forget to revert to read-only mode:
Building¶
You can build the .deb package in two ways:
- Build on your dev machine and copy it to the Streamer (recommended: faster, less hassle)
- Build directly on the RPi
Building on Dev Machine¶
Ensure your Streamer is in RW mode before installing the package.
It is assumed you use some Debian based Linux distribution, otherwise you will have to prepare the dependencies on your own.
On your dev machine install pre-requisites:
Build deb package:
Once dependencies are installed you can use this instead to build
Quick build-and-copy one-liner:
sudo ./build/build-in-chroot.sh && scp ./build/tmp/dependencies/debs/v3xctrl.deb v3xctrl@v3xctrl01.local:/home/v3xctrl
On the Streamer, remove the old version and install the new one:
Build flashable image
You may also build a flashable image after you have built the .deb package
Build on RPi¶
Install git, clone the repo, and run the installer script:
sudo apt update
sudo apt install git -y
git clone git@github.com:stylesuxx/v3xctrl.git
./bash/install.sh
After installation, you should be able to access the config web interface at:
Update¶
To update the package later, you can skip setup steps and only rebuild/install:
Custom Python¶
The installation provides a custom Python environment isolated from the system Python. It has its own interpreter and pip:
Modem setup¶
Plug in your modem. It should appear as an RNDIS network device.
Check with:
If you don’t see the device, check the kernel log:
Serial Console (optional but recommended)¶
Note: Already enabled when using our custom image.
For easier debugging, enable a serial login console:
Navigate to Interface Options -> Serial Port -> Would you like a login shell to be accessible over serial? -> Yes -> OK -> Finish.
Now you can connect via a USB-to-serial adapter for direct console access.
Helper scripts¶
The bash directory contains GStreamer helper scripts for testing the video pipeline. You can use these transmitters and receivers to produce a test video stream similar to the live client stream.
Logging¶
Switching from RO to RW mode also enables persistent systemd logging.
List boot logs:
To view the boot log of a specific boot:
journalctl -b $BOOT_ID --no-pager
journalctl -b 0 --no-pager # Current
journalctl -b -1 --no-pager # Previous boot
Tests¶
Run tests:
# All
python -m pytest tests
# Just ui
python -m pytest tests/v3xctrl-ui
# Just server
python -m pytest tests/v3xctrl_control
Automatically re-run tests on file changes:
Run tests with coverage and show missing lines: