Skip to content

Usage

Wi-Fi vs RPi Hotspot

To connect to the Raspberry Pi via SSH or open the web app in a browser, both your device and the RPi need to be connected to the same network. You have three main options:

  1. Wi-Fi network that both your device and the RPi are connected to.
  2. Hotspot from your device that the RPi is connected to.
  3. Hotspot from the RPi that your device is connected to.

The RPi can usually only be used either as wireless client (connects to network with internet access) or as access point (creates own hotspot without internet access). For an unsupported experimental workaround, check the RaspAP Docs.

If you don't need internet access on your RPi (e.g. during fieldwork), there are some advantages of letting the RPi create a hotspot: Any device can connect to it and open the web app, which can be useful if multiple people want to set up camera traps in the field. Also this option is more reliable than letting the RPi connect to a hotspot from your device (every device is different!).

With the default startup configuration, the RPi will automatically start a hotspot as fallback mechanism when no configured Wi-Fi network is available (SSID and password = hostname).

Web App

With the web app, you can view the OAK camera live stream including detected and tracked insects in the browser-based user interface (based on NiceGUI). It also allows real-time camera control (e.g. setting manual focus) and customization of all configuration parameters, as well as selecting the active config that is used by both the web app and the recording script. When using the web app in the field while setting up your camera trap, you can also save deployment metadata, such as location and background setting. The Advanced section includes current system info (e.g. temperature, CPU/RAM usage), viewing of log files and an integrated Terminal.

First navigate to the insect-detect directory:

cd insect-detect

Run the web app with:

uv run webapp

Use one of the links that is shown in the Terminal to open the web app in your browser. If the hostname-based link does not work, use the IP address instead. Always use the link with the IP address if your device is connected to the RPi hotspot, this should be http://10.42.0.1:5000 if not using https, or https://10.42.0.1:8443 if https is enabled.

Stop the web app with the Stop App button or by pressing Ctrl+C in the Terminal.

Recording Script

The recording script can be used for fully automated insect monitoring in autonomous camera trap deployments. All configuration parameters can be customized in the web app or by directly modifying the config.yaml file. You can generate multiple custom configuration files and select the active config either in the web app or by modifying the config_selector.yaml.

First navigate to the insect-detect directory:

cd insect-detect

Run the capture script with:

uv run capture

Stop the script by pressing Ctrl+C in the Terminal.

Processing Pipeline

  • A custom insect detection model is run in real time on device (OAK) and uses a continuous stream of downscaled frames as input.
  • An object tracker uses the bounding box coordinates of detected insects to assign a unique tracking ID to each individual present in the frame and track its movement through time.
  • The tracker + model output from inference on downscaled frames is synchronized with MJPEG-encoded high-resolution frames (default: 3840x2160 px) on device (OAK).
  • The full frames are saved to the microSD card at the configured capture intervals while an insect is detected (triggered capture) and independent of detections (timelapse capture).
  • Corresponding metadata from the detection model and tracker output is saved to a metadata .csv file for each detected and tracked insect (including timestamp, label, confidence score, tracking ID, tracking status and bounding box coordinates).
  • The bounding box coordinates can be used to crop detected insects from the corresponding full frames and save them as individual .jpg images. Depending on the post-processing configuration, the original full frames are optionally deleted to save storage space.
  • If a power management board (e.g. Witty Pi 4 L3V7) is connected and enabled in the configuration, intelligent power management is activated which includes battery charge level monitoring with conditional recording durations.
  • With the default configuration, running the recording consumes around 4.2 W of power.

Depending on the specific requirements of your field deployment, different behaviours can be configured in the startup settings that are run after each boot:

Use Case 1: Interactive

If you deploy the camera trap for only one recording session, e.g. while doing other field work in parallel, you might want to just run the web app automatically after boot to save deployment metadata and/or modify configuration parameters. Click the Start Rec button in the web app after everything is set up to start the recording script manually.

startup:
  hotspot_setup:
    enabled: true
  network_setup:
    enabled: true
  auto_run:
    enabled: true
    primary: webapp
    fallback: null
    delay: 180

Use Case 2: Autonomous

For long-term field deployment, you want to run the recording script automatically after each boot. Please make sure to modify and save all relevant configuration parameters either beforehand or when setting up the camera trap.

startup:
  hotspot_setup:
    enabled: true
  network_setup:
    enabled: true
  auto_run:
    enabled: true
    primary: capture
    fallback: null
    delay: 180

Use Case 3: Hybrid

There might be scenarios where you want to optionally connect to the web app after a scheduled wake-up time, e.g. to modify settings or check log files. For this use case, you can set webapp as primary auto-run script and capture as fallback script. If no user interaction (opening the web app in your browser) is detected for the configured delay time, the web app will be terminated and the recording script will be started automatically.

startup:
  hotspot_setup:
    enabled: true
  network_setup:
    enabled: true
  auto_run:
    enabled: true
    primary: webapp
    fallback: capture
    delay: 180

Troubleshooting

If you run into any problems while using the insect-detect software, please create an issue.

RuntimeError: X_LINK_DEVICE_ALREADY_IN_USE 
RuntimeError: Failed to connect to device, error message: X_LINK_DEVICE_ALREADY_IN_USE

If you run into the error shown above, the most common cause is that a previously started script is already communicating with the OAK camera. Show all running processes by starting the process manager htop:

htop

If you see one of the Python scripts in the list of processes, you can hit F9 with the script selected. This will open the SIGTERM option and by confirming with Enter the process will be stopped. Close htop by pressing Q and you should now be able to connect to the OAK camera again.

Couldn't read data from stream: 'frame' (X_LINK_ERROR) 
RuntimeError: Communication exception - possible device error/misconfiguration. Original message 'Couldnt read data from stream: 'frame' (X_LINK_ERROR)'

If you run into the error shown above, the most common cause is a loose USB cable between OAK camera and Raspberry Pi. Other reasons can be a damaged cable or Micro-USB adapter. Please make sure to exclude these reasons, e.g. by testing a different cable and/or adapter.