GitHub action for v4l2 application testing in Renode
Topics: Open source tools, Open machine vision
Antmicro’s work with camera systems often results in new reusable tools and libraries helpful for debugging video devices and applications. Some examples of such tools for working with v4l2 pipelines such as grabthecam, farshow, pyrav4l2 and Raviewer can be found on Antmicro’s Open Source Portal.
The apps and utilities themselves, however, require testing which is tricky to automate, as it requires a camera device.
One way to perform these tests without a physical camera is to use the Vivid driver which creates a fake v4l2 node capable of streaming test patterns, while providing example v4l2 controls for virtually any control type available for v4l2. It is a great choice for testing v4l2 applications, utils and debugging tools, but in many Linux compilations it is either completely disabled or provided as a dynamic kernel module. This includes e.g. the stock machines provided by GitHub Actions, and while in many projects we use our custom-developed GitHub runners to mitigate those kinds of problems, enabling easy peripheral testing with customized kernels via simulation in any context seemed like a very useful capability.
This consideration led us to create a GitHub action capable of running a full-fledged Linux distribution with a kernel of our choice, using the Renode simulation framework.
How the Renode Linux runner action works
The newly introduced GitHub action is designed to be completely transparent to users. They are able to run their CIs as usual, but instead of executing the code directly in docker containers provided by GitHub, the execution is wrapped in a Renode environment.
Inside the action, you can use the
renode-run command which behaves similarly to the well-known
run command in GitHub Actions, letting you run single commands as well as multi-line scripts.
You can also specify a shared directory shared between the Docker container and the Renode environment (
shared-dir) for this action, where you can place the scripts you want to run.
This is how you would run a single command using the
- uses: antmicro/renode-linux-runner-action@main with: shared-dir: ./shared-dir renode-run: command_to_run
Running multiple commands works the same way as in the standard
- uses: antmicro/renode-linux-runner-action@main with: shared-dir: ./shared-dir renode-run: | command_to_run_1 command_to_run_2
The action runs the code on an emulated HiFive Unleashed platform with a RISC-V CPU, however it is the architecture-independent Linux API that is tested here.
Example use case
Since this is just a regular GitHub action, it is highly reusable. Below, as an example, we will run scripts extracted from the README for Antmicro’s pyrav4l2 tool for easily controlling v4l2 devices inside Python scripts using tuttest. Tuttest is another of Antmicro’s utilities which lets you test code embedded in tutorials and examples you provide to users to make sure they continue to run.
name: Running Python CI jobs on: push: paths: - 'pyrav4l2/**' - 'README.md' pull_request: paths: - 'pyrav4l2/**' - 'README.md' ... run-example-scripts-from-readme: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install tuttest run: pip install git+https://github.com/antmicro/tuttest.git - name: Extract example scripts from README run: python ./.github/save_examples.py README.md - name: Copy examples and pyrav4l2 to shared-dir run: | mkdir -p tests/pyrav4l2 cp -r ./pyrav4l2 setup.py ./tests/pyrav4l2 cp -r ./examples ./tests - name: Run scripts in Renode uses: antmicro/renode-linux-runner-action@main with: shared-dir: ./tests renode-run: | pip install ./pyrav4l2 for script in ./examples/*.py; do python $script; done
Then, after the script is run in Renode, the following information regarding
v4l2 is returned:
Color format: YUYV 4:2:2 Frame size: 320 x 180 Device name: vivid Driver name: vivid Device supports video capturing Frame 0: 115200 bytes Frame 1: 115200 bytes
More flexibility through testing in Renode
This action alleviates a common grievance and allows us to continuously test our open-source v4l2 apps, but its potential capabilities reach much further. Thanks to the flexibility of the Renode framework, we can not only use emulated devices (like Vivid), but also a wide variety of emulated hardware, which would allow users to test embedded Linux userspace applications with GitHub Actions, just like they would on physical hardware.
Potential further use cases for this action include testing applications that communicate with various sensors (e.g. via I2C or SPI) that use devices like watchdogs or flash, or even connect to other, completely independent devices over Bluetooth, Ethernet or other interfaces.
Whether you are interested in developing and testing applications for video devices together with Antmicro or you would like to discuss using Renode for comprehensive simulation of complex systems, feel free to contact us at firstname.lastname@example.org.