Skip to content

Getting started

Jump to bottom
tuvabjornberg edited this page Aug 8, 2024 · 16 revisions

Feeling overwhelmed and lost? Don't fret! Here is the complete startup guide for the beamforming repo and the complete digital signal processing of audio sampling.

Prerequisites

Cloning repositories

This repo, beamforming-lk, should be cloned.

git clone https://github.com/acoustic-warfare/beamforming-lk.git

Docker

Download Docker using the apt-repository.

Files

For running with FPGAs and arrays live, bitstream file and ps.elf from FPGA-sampling releases need to be downloaded and placed into boot/tftp.

The release we recommend (end of summer 2024) is Distributed.

Realtime Kernel

It is also good to have a realtime kernel. see https://ubuntu.com/pro.

When you have a real time kernel:

sudo addgroup realtime
sudo usermod -a -G realtime $(whoami)

Then edit the limit configuration /etc/security/limits.conf

# /etc/security/limits.conf
@realtime     soft    rtprio          99
@realtime     soft    priority        99
@realtime     soft    memlock     102400
@realtime     hard    rtprio          99
@realtime     hard    priority        99
@realtime     hard    memlock     102400

Configuration

Specific configurations for developers is found in each header file.

Configurations may need to be done for realtime audio playing in the src/audio/daemon.conf file. The current standards should work for most machines. If you are not running the project in the provided docker container, replace the current /etc/pulse/daemon.conf with the above file, daemon.conf.

Building and Running prerequisites - Docker container

Automatic

By running the script start.h the prerequisites and Docker container are set up, built and run automatically.

./start.sh

If you are encountering permission issues, ex. "permission denied while trying to connect to the Docker daemon socket at...", give docker some permissions: sudo chmod 666 /var/run/docker.sock

Manual

The project may also be compiled and executed inside a Docker environment manually. A working Docker installation is required and Docker without root privileges is recommended. You might also need to disconnect any ethernet cables if docker is unable to git clone during the setup.

To build the container run the following command:

docker build -t beamformer .

To run the container run the following command:

docker run -v $(pwd):/usr/src/app -e DISPLAY=$DISPLAY -it --network=host -v /tmp/.X11-unix:/tmp/.X11-unix -e PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native -v ${XDG_RUNTIME_DIR}/pulse/native:${XDG_RUNTIME_DIR}/pulse/native -v /run/dbus:/run/dbus --device /dev/snd beamformer bash

Local

If not wanting to use a Docker container, all prerequisites need to be fetched and downloaded manually. A hint of which packages and repos need to be installed can be seen in the Dockerfile.

Building the project

Automatic

The ./start.sh script builds everything for you!

Manual

Create the required build directory

mkdir build

Change directory to build/

cd build

Generate the Makefile

cmake ..

Build the program

make

Running the project

The project is run with:

./beamformer

but needs to be run with arguments to configure crucial parameters.

To see the possible arguments ./beamformer -h

Usage: ./beamformer [--help] [--version] [--camera VAR] [--ip-address VAR] [--audio VAR] [--mimo] [--record] [--mimo-res VAR] [--tracking] [--verbose] [--fov VAR] [--fps] [--logo] [--debug] [--port VAR]... [--wara-ps] [--miso]

Optional arguments:
  -h, --help     shows help message and exits 
  -v, --version  prints version information and exits 
  --camera       Camera option, default is false [nargs=0..1] [default: "false"]
  --ip-address   IP address [nargs=0..1] [default: "10.0.0.1"]
  --audio        Audio option, port nr [nargs=0..1] [default: 0]
  --mimo         MIMO option 
  --mimo-res     MIMO Resolution [nargs=0..1] [default: 100]
  --tracking     Tracking option 
  --verbose      Program output 
  --fov          Field of view [nargs=0..1] [default: 180]
  --fps          Program FPS 
  --logo         Use logo 
  --debug        Debug mode 
  --port         PORT numbers [may be repeated]
  --wara-ps      Use WARA PS 
  --miso         MISO Mode, needs to be combined with --audio 'portnr'

Example runs

The following command will run the MIMO algorithm and overlay the tracking (gradient ascend). It has two FPGAS connected which has the port nrs 21876 and 21875. It will also play the realtime audio from the FPGA with the port 21875 (as well as save the sound as files).

./beamformer --mimo --tracking --port 21876 --port 21875 --audio 21875

The order of the ports should reflect the order of the arrays/FPGAs.

Recordning

Press 'r' on the heatmap to start recording it. Press 'r' aging to end it.

Exiting

Press 'q' on the heatmap to exit the program.

Usage

Offline usage

You may want to test the system without an FPGA and arrays connected, look at the udp/ directory's README.md for further information. The recommended method is described under the UDP-Replaying section.

Booting the FPGA to run with arrays (realtime)

A simple TFTP boot server is given in the directory boot/. This must be built manually. See boot/README.md for more information.

Set up the hardware according to the User Manual.

Once the boot Docker container (for boot) is running, turn on the FPGAs and the beamforming program should proceed.

Documentation

You may see a structural documentation of the project by building the Doxygen page which will generate a documentation page at doc/html/index.html

make doc
Clone this wiki locally