Skip to content

Software Guide

Jump to bottom
Nikogenia edited this page Jan 9, 2025 · 72 revisions

This is a big collection of various guides for different software operations. Use the links below to navigate!

Audio

Usage

Setup

  • install the latest version of OBS Studio on the Windows 11 machine
  • download the OBS profile and scene collection Space_Balloon_Audio
  • import these via the options in the menu bar
  • open settings
    • go to the Stream tab
    • replace the second slot in the streamid with the desired stream path
      • mission control publish:audiomc:maker:#PASSWORD
      • launch field publish:audiosp:maker:#PASSWORD
      • radio publish:audioradio:maker:#PASSWORD
    • visit the Audio tab
      • make sure no inputs are configured as defaults
    • click Okay to exit the settings

FFmpeg (OLD)

  • open a terminal on the Windows machine
  • install ffmpeg with winget
    winget install Gyan.FFmpeg
  • find the name of the audio device input
    ffmpeg -list_devices true -f dshow -i dummy
  • start the stream (replace #DEVICE and #PASSWORD respectively)
    ffmpeg -f dshow -i audio="#DEVICE" -acodec libopus -ab 64k -f mpegts "srt://server.balloon.nikogenia.de:8890?streamid=publish:audiomc:maker:#PASSWORD&latency=20"

Raspberry Pi

Usage guides are coming first for ease of discovery, the setup guide is following after.

Usage

  • there should be a Raspberry Pi OS Lite (64-bit) running
  • default user is maker
  • SSH access
  • the sp command does 2 things
    • change directory to the /home/maker/SpaceBalloon repository
    • execute the tool script at tools/name.sh with sudo if an argument is provided

Tool scripts are explained in the following sections.

Service Execution

  • start all services
    sp start
  • start a specific service (replace #SERVICE with the service name)
    sp start #SERVICE
  • stop all services
    sp stop
  • stop a specific service (replace #SERVICE with the service name)
    sp stop #SERVICE
  • restart all services
    sp restart
  • restart a specific service (replace #SERVICE with the service name)
    sp restart #SERVICE

Note that the prefix balloon- and suffix .service are added automatically!

Service Autostart

  • enable autostart for all services
    sp enable
  • enable autostart for a specific service (replace #SERVICE with the service name)
    sp enable #SERVICE
  • disable autostart for all services
    sp disable
  • disable autostart for a specific service (replace #SERVICE with the service name)
    sp disable #SERVICE

Note that the prefix balloon- and suffix .service are added automatically!

Environment

  • sp setup handles the following actions
    • creation of the Python virtual environment
    • installation of required packages
    • removal of old service files
    • registration of new service files
    • reloading systemd
    • service autostart
    • creation of the configuration file
  • configuration in config.yml is required afterwards (more details here)
  • the next step would be data storage initialization
  • should you change your mind sp uninstall does almost the opposite
    • removal of service files
    • reloading systemd
    • deletion of the Python virtual environment
    • deletion of the configuration file
    • deletion of the data storage

WARNING: BE AWARE OF WHAT YOU ARE DOING AND READ EVERYTHING CAREFULLY BEFORE COMMAND EXECUTION!

Data Storage

  • all data is stored in the data directory
  • sensor data is written to CSV files in sensor
  • photos and videos are available in video and the individual camera folder like cam0
  • to prepare this structure use
    sp reset
  • existing data will be all removed on reset making this a destructive action

WARNING: BE AWARE OF WHAT YOU ARE DOING AND READ EVERYTHING CAREFULLY BEFORE COMMAND EXECUTION!

Debug Utilities

  • view the latest systemd logs of a service (replace #SERVICE with the service name)
    splog #SERVICE
  • make it follow on updates (replace #SERVICE with the service name)
    splogf #SERVICE
  • go through the logs of all services one by one sp logall
  • to debug power delivery check all power rails of the Raspberry Pi using
    vcgencmd pmic_read_adc
  • I/O related system logs can be viewed with
    dmesg
  • if you have to check global logs of the whole system use \
    • sudo journalctl -b 0 for everything since this boot
    • sudo journalctl -e -b -1 for everything until last shutdown
    • add | grep #KEYWORD to filter for specific keywords
    • the option -k filters for kernel logs only

Note that the prefix balloon- and suffix .service are added automatically!

Backup

Method 1: USB drive (quite fast, recommended)

  • make sure you have physical access to the hardware
  • have an storage device formatted as exFAT prepared
  • start backup procedure
    sp backup
  • follow the instructions

Method 2: SSH over WiFi (very slow, only use if necessary)

  • open a terminal on a Windows machine connected to the network
  • make sure SSH access is possible
  • navigate to the repository and into the tools folder
  • start backup procedure
    backup.bat
  • follow the instructions

Configuration

There are a few things that can be configured through the config.yml file. To edit please use

  • sp
    to make sure you are in the repository directory
  • sudo nvim config.yml
    or
    sudo nano config.yml
    to open your preferred text editor.

Climate

sea_level_pressure: 1013.25
  • this value needs to be adjusted a few hours before launch
  • open this map
  • search for your location and read the current pressure conditions
  • set the sea level pressure in hPa (default value is 1013.25)

Sensor I2C Bus

bus:
  adc: 7
  co2: 5
  gps: 4
  magnet: 6
  • these are the I2C bus IDs of the sensors
  • they need to match the configuration in the /boot/firmware/config.txt available here
  • there is usually no need to change this

Intervals and Timeouts

interval:
  adc: 1
  climate: 1
  co2: 1
  magnet: 1
  spectral: 1
  system: 1
  • readout intervals in seconds for the sensors
  photo_offset: 4
  photo_delay: 20
  • the photo delay specifies the webcam photo interval in seconds
  • meanwhile the offset gets multiplied by the camera ID and added to a timing alignment grid in seconds
  • example with photo_offset: 4 and photo_delay: 20
    • webcam 0: now - (now % 20) + (0 * 4)
    • webcam 1: now - (now % 20) + (1 * 4)
    • webcam 2: now - (now % 20) + (2 * 4) 
  dm_debug: 10
  dm_aprs: 60
  dm_influx: 3
  cm_debug: 10
  cm_services: 3
  cm_mode: 10
  • the debug intervals specify state logging for the data manager and camera manager in seconds
  • data manager aprs represents packet sending in seconds
  • data manager influx stands for measurement upload to database in seconds
  • camera manager services is the rate at which service and uptime monitoring is updated in seconds
  • camera manager mode sets management schedules for offline and pop mode
  ping_fail: 30
  cam_cycle: 120
  live_mode_stop: 30
  • how many seconds pings need to fail for switching to offline mode
  • cycle cameras in offline and pop mode every so many seconds
  • delay webcam livestream stop for an amount of seconds to give new streams some time to intialize

Webcam Path ID

webcams:
  0: "usb-xhci-hcd.1-2"
  1: "usb-xhci-hcd.0-1.2"
  2: "usb-xhci-hcd.0-1.3"
  3: "usb-xhci-hcd.1-1.4"
  4: "usb-xhci-hcd.1-1.3"
  • these values depend on your webcam USB cable management
  • list all webcams
    v4l2-ctl --list-devices
  • copy the USB path IDs from the parentheses
  • assign them to the webcams (this isn't the device index, but the module index)
  • this is necessary because of regularly changing camera device indices

Offline and Pop Mode

mode:
  offline_auto: true
  offline_ping: "192.168.25.2"
  • automatic switching to offline mode can be toggled on and off
  • the offline ping specifies the hostname to ping with ICMP to determine connection status
  pop_auto: true
  pop_pressure: 50
  pop_altitude: 25000
  • automatic switching to pop mode can be toggled on and off
  • the maximum pressure for pop mode in hPa
  • the minimum altitude for pop mode in meters

InfluxDB

influx:
  url: "https://influx.balloon.nikogenia.de"
  org: "makerspace"
  bucket: "balloon"
  token: ""
  • access information for the InfluxDB database

Stream

stream:
  url: "srt://server.balloon.nikogenia.de:8890?streamid=publish:#PATH:#USERNAME:#PASSWORD&pkt_size=1316"
  username: "maker"
  password: ""
  • stream URL for the SRT stream to the media server
  • username and password get replaced at the placeholders

APRS

aprs:
  device: "usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_02e63ec96457ed11b7bb50ca5720eef3-if00-port0"
  src: "DN5WA-2"
  dst: "APRS-0"
  • device is used to specify the USB path ID of the PicoAPRS connected
  • use can list all device and pick the right one with
    ls -l /dev/serial/by-id/
  • src stands for the source callsign for APRS packets
  • dst stands for the destination callsign for APRS packets

Storage Box

storage:
  sensor:
    default:
      path: "./data/sensor"
  video:
    path: "./data/video"
    backups: []
  • these options are legacy and shouldn't be changed due to unfinished implementation
  remote: "hetzner:System/photo"
  • remote path with rclone remote prefix for storage box upload location
  • do not use a / at the root position

Setup

The following steps are useful to make a full production instance of the software on board.

Flashing

  • use an external computer and insert the MicroSD card
  • start Raspberry Pi Imager, select model Raspberry Pi 5, operating system Raspberry Pi OS Lite (64-bit) and your MicroSD card
  • change your settings when prompted
    • hostname:
      spaceballoon
    • username:
      maker
    • password:
      ********
    • if you won't be able to access the console directly, configure a WiFi connection first
    • timezone:
      Europe/Berlin
    • keyboard layout:
      de
  • activate SSH access in the tab Services
  • save settings and start flash
  • remove MicroSD card when finished and insert into your Raspberry Pi

Network

  • power on system
  • login to console directly or via SSH
  • open Network Manager TUI using
    sudo nmtui
    • select Edit a connection and edit Wired connection
    • profile name:
      MikroTik
    • IPv4 configuration:
      Manual
      • addresses:
        192.168.25.4
      • gateway:
        192.168.25.1
      • DNS servers:
        1.1.1.1
        8.8.8.8
    • save connection via OK
    • optionally add a few WiFi hotspots as a backup recovery method
    • go back and use Activate a connection to make sure the ethernet connection is active
  • quit menu and verify your network setup
    ifconfig

Code and Dependencies

  • add package repositories
    curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
  • install basic packages
    sudo apt install git neovim python3-dev wireguard ffmpeg ntp rclone speedtest i2c-tools
  • update packages
    sudo apt update && sudo apt upgrade
  • clone repository with
    git clone https://github.com/BOGYLI/SpaceBalloon.git
  • add the following bash alias configuration to the end of /etc/bash.bashrc 
splog() {
    sudo journalctl -o cat -e -u balloon-$1.service
}

splogf() {
    sudo journalctl -o cat -f -u balloon-$1.service
}

sp() {
    cd /home/maker/SpaceBalloon
    if [ -n "$1" ]; then
        scriptname="$1"
        shift
        sudo tools/$scriptname.sh $@
    fi
}
  • setup rclone and configure a remote called hetzner for the storage box
    sudo rclone config

Interfaces

  • append panic=10 usbcore.autosuspend=-1 to /boot/firmware/cmdline.txt to activate kernel crash recovery
  • make sure I2C is enabled by uncommenting dtparam=i2c_arm=on
  • append the following lines to /boot/firmware/config.txt to activate software I2C
dtoverlay=i2c-gpio,bus=7,i2c_gpio_sda=8,i2c_gpio_scl=7
dtoverlay=i2c-gpio,bus=6,i2c_gpio_sda=12,i2c_gpio_scl=13
dtoverlay=i2c-gpio,bus=5,i2c_gpio_sda=22,i2c_gpio_scl=23
dtoverlay=i2c-gpio,bus=4,i2c_gpio_sda=5,i2c_gpio_scl=6

dtparam=uart0=on

usb_max_current_enable=1
  • edit the bootloader with sudo rpi-eeprom-config --edit by adding the line PSU_MAX_CURRENT=5000
  • open the Raspberry Pi configuration
    sudo raspi-config
    • navigate to Interface Options > I2C
    • select YES to enable
    • quit the menu
  • write the following VPN configuration to /etc/wireguard/wg0.conf (replace #KEY1 and #KEY2 accordingly)
[Interface]
PrivateKey = #KEY1
Address = 10.25.1.2/24

[Peer]
PublicKey = #KEY2
AllowedIPs = 10.25.1.0/24,10.25.0.0/24
Endpoint = server.balloon.nikogenia.de:51820
PersistentKeepalive = 25
  • enable the Wireguard service with the following systemctl commands
sudo systemctl enable [email protected]
sudo systemctl daemon-reload
sudo systemctl start wg-quick@wg0
sudo systemctl status wg-quick@wg0
  • restart the system sudo reboot

Space Balloon Software

  • this is a quick start summary
  • all operations in detail can be lookup up in the usage guide
  • setup environment
    sp setup
  • configure config.yml with secrets (more details here)
  • create data directories
    sp reset
  • start all services
    sp startall
  • everything should be running now

Server

Both the main and OBS server are located at the Hetzner datacenter in Nürnberg.

Main Server

Usage

System Setup

First Steps

  • change the root password passwd
  • configure the keyboard layout dpkg-reconfigure keyboard-configuration
    • Generic 105-key PC
    • Other (Only, if German isn't shown)
    • German
    • Right Alt (AltGr)
    • Right Alt (AltGr)
  • update configuration with setupcon
  • set timezone timedatectl set-timezone Europe/Berlin
  • update and install packages
apt update
apt upgrade
apt install wireguard rclone
  • reboot system with reboot
  • verify login via Hetzner console is working

Wireguard

Docker

Crontab

  • execute crontab -e to open the editor and append the following tasks
0 0 * * * /root/influx/backup.sh
0 1 * * * /root/prometheus/backup.sh

Node Exporter

Rclone

Docker Setup

Dockge

Traefik

Prometheus

Influx

Grafana

MediaMTX

OBS Server

Repository | Wiki Home | Website | Youtube | TikTok

© 2024 Bodensee-Gymnasium Lindau

Clone this wiki locally