Skip to main content

​
Overview

This guide will walk you through setting up PhysisLab on your computer. The installation process varies depending on which experiments you plan to run:
  • Camera-based experiments: Python + OpenCV setup
  • Microcontroller experiments: Arduino IDE + ESP32 setup
  • Audio-based experiments: Python + audio libraries
You can install only what you need, or complete the full setup for all experiment types.

​
Step 1: Python Environment Setup

1

Install Python

Download and install Python 3.8 or higher from python.orgVerify installation:
python --version
# Should output: Python 3.8.x or higher
On some systems, you may need to use python3 instead of python:
python3 --version
2

Create a Virtual Environment (Recommended)

Navigate to your PhysisLab project directory and create an isolated Python environment:
# Create virtual environment
python -m venv physislab-env

# Activate on Windows
physislab-env\Scripts\activate

# Activate on macOS/Linux
source physislab-env/bin/activate
When activated, your terminal prompt will show (physislab-env).
3

Install Required Python Packages

Install all required libraries using pip:
# Core computer vision and scientific computing
pip install opencv-python numpy scipy matplotlib

# Audio processing (for sound-based experiments)
pip install sounddevice

# Serial communication (for ESP32 oscilloscope/generator)
pip install pyserial

# Optional: WebSocket support
pip install websocket-client
Verify OpenCV installation:
python -c "import cv2; print(cv2.__version__)"
# Should output version number (e.g., 4.8.0)
4

Test Camera Access

Ensure Python can access your webcam:
import cv2

cap = cv2.VideoCapture(0)
if cap.isOpened():
    print("Camera detected successfully!")
    ret, frame = cap.read()
    if ret:
        print(f"Frame size: {frame.shape}")
        print(f"FPS: {cap.get(cv2.CAP_PROP_FPS)}")
else:
    print("Cannot access camera")
cap.release()
Save this as test_camera.py and run:
python test_camera.py

​
Step 2: Arduino IDE Setup for ESP32

Skip this section if you’re only doing camera-based experiments.
1

Install Arduino IDE

Download and install Arduino IDE 2.0 or later from arduino.ccAlternative: Advanced users can use PlatformIO with VS Code.
2

Add ESP32 Board Support

Open Arduino IDE and add ESP32 boards:
  1. Go to File → Preferences (or Arduino IDE → Settings on macOS)
  2. In “Additional Board Manager URLs”, add:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
  1. Click OK
  2. Go to Tools → Board → Boards Manager
  3. Search for “esp32”
  4. Install “esp32” by Espressif Systems (latest version)
Installation may take several minutes as it downloads toolchains and libraries.
3

Select ESP32 Board

After installation:
  1. Go to Tools → Board → esp32
  2. Select your board model:
    • ESP32 Dev Module (most common)
    • ESP32-WROOM-DA Module
    • Or your specific board variant
  3. Connect ESP32 via USB
  4. Select the correct port under Tools → Port
    • Windows: COM3, COM4, etc.
    • macOS: /dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART
    • Linux: /dev/ttyUSB0 or /dev/ttyACM0
4

Install Required Arduino Libraries

For experiments using sensors, install libraries via Library Manager:
  1. Go to Tools → Manage Libraries (or Sketch → Include Library → Manage Libraries)
  2. Search and install:
    • Adafruit VL53L0X (for kinematics with time-of-flight sensor)
// Free fall experiments use only built-in libraries
#include <Arduino.h>

#define PIN_INICIO 18
#define PIN_FIN    5

// Uses ESP32 FreeRTOS and hardware timers
void setup() {
  Serial.begin(115200);
  pinMode(PIN_INICIO, INPUT_PULLUP);
  pinMode(PIN_FIN, INPUT_PULLUP);
}
5

Test ESP32 Connection

Upload a simple test sketch:
  1. Open File → Examples → 01.Basics → Blink
  2. Modify the LED pin if needed (usually GPIO 2):
#define LED_PIN 2

void setup() {
  pinMode(LED_PIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_PIN, HIGH);
  delay(1000);
  digitalWrite(LED_PIN, LOW);
  delay(1000);
}
  1. Click Upload (arrow button)
  2. Watch for “Connecting…” message - you may need to press BOOT button on ESP32
  3. After upload, the onboard LED should blink
Upload Issues?
  • Press and hold BOOT button during “Connecting…”
  • Try a different USB cable (data-capable, not charge-only)
  • Install CP210x or CH340 USB drivers if port doesn’t appear
  • Reduce upload speed: Tools → Upload Speed → 115200

​
Step 3: Download PhysisLab Source Code

1

Clone or Download Repository

Option A: Using Git (Recommended)
git clone https://github.com/yourusername/PhysisLab.git
cd PhysisLab
Option B: Download ZIP
  1. Download the repository as ZIP from GitHub
  2. Extract to your desired location
  3. Navigate to the extracted folder
2

Explore Project Structure

The PhysisLab repository is organized by experiment type:
PhysisLab/
├── FreeFall/
│   ├── freeFallCam/              # Camera-based free fall
│   │   ├── FreeFallCam.py        # Main script
│   │   ├── capturar.py           # Video capture utility
│   │   └── ...
│   ├── Micro-procesador/         # ESP32-based timing
│   │   ├── FreeFallEpsfreeRTOSFunciona/
│   │   │   └── FreeFallEpsfreeRTOSFunciona.ino
│   │   └── ...
│   └── FreeFallPython-Sonido/    # Audio-based detection
│       ├── deteccion_por_sonido.py
│       └── ...
├── Pendulo/
│   └── analisis.py               # Pendulum tracking and analysis
├── Masa-Resorte/
│   └── analisis.py               # Spring-mass system analysis
├── MovimientoParabolico/
│   └── analisis.py               # Projectile motion tracking
├── Kinemactic/
│   ├── kinematicCam/             # Camera-based kinematics
│   ├── VL53_filtros/             # VL53L0X sensor code
│   └── ultraSonido_filtros/      # Ultrasonic sensor code
└── osciloscopioygeneradordeSeñales/
    ├── Serial/                   # Serial communication version
    └── websocket/                # WebSocket version

​
Step 4: Verify Installation

1

Test Camera-Based Experiment

Run the free fall camera detection script:
cd FreeFall/freeFallCam
python FreeFallCam.py
Expected behavior:
  1. Camera window opens showing live feed
  2. Press SPACE to capture a snapshot
  3. Select ROI (region of interest) for the colored object
  4. Click two horizontal lines for start/end detection
  5. System begins tracking
Verify:
  • Color detection works (green circle on object)
  • Line crossing is detected
  • Data is saved to datos_tiempo.txt
2

Test ESP32 Firmware (If Applicable)

Upload and test a microcontroller experiment:
  1. Open FreeFall/Micro-procesador/FreeFallEpsfreeRTOSFunciona/FreeFallEpsfreeRTOSFunciona.ino
  2. Upload to ESP32
  3. Open Tools → Serial Monitor (set to 115200 baud)
  4. Connect IR sensors to pins 18 and 5
  5. Trigger sensors (break beam)
Expected output:
INICIO: 12345678 us
FIN: 12678901 us
DELTA = 333223 us
3

Test Audio Detection (If Applicable)

Run the sound-based detection:
cd FreeFall/FreeFallPython-Sonido
python deteccion_por_sonido.py
Expected behavior:
  1. Lists available audio devices
  2. System arms after 2.5 seconds
  3. RMS level bar shows microphone input
  4. Detects two impact events
  5. Displays Δt (time difference)
Test with hand claps before using actual experiment.
4

Run Analysis Script

Test data analysis with a complete experiment:
cd Pendulo
python analisis.py
Required:
  • Video file of pendulum motion
  • Follow prompts to select frames and ROIs
Output:
  • Position, velocity, and angle plots
  • Period and gravitational acceleration measurement
  • Saved figures: fig1_posicion_velocidad.png, fig2_angulo.png, fig3_trayectoria.png

​
Common Installation Issues

Problem: cap.isOpened() returns FalseSolutions:
  1. Try different camera indices:
cap = cv2.VideoCapture(0)  # Try 0, 1, 2, etc.
  1. Check camera permissions (macOS/Linux)
  2. Close other applications using the camera
  3. On Linux, install v4l-utils:
sudo apt install v4l-utils
v4l2-ctl --list-devices
Problem: No serial port shows up in Arduino IDESolutions:
  1. Install USB drivers:
  2. Try a different USB cable (must support data transfer)
  3. Check Device Manager (Windows) or ls /dev/tty* (macOS/Linux)
  4. Try a different USB port (USB 2.0 ports may work better)
Problem: Adafruit_VL53L0X.h: No such file or directorySolution:
  1. Verify library installation: Tools → Manage Libraries
  2. Search “VL53L0X” and install Adafruit VL53L0X
  3. Also install dependency: Adafruit Unified Sensor
  4. Restart Arduino IDE
  5. Check installation path:
    • Windows: Documents\Arduino\libraries\Adafruit_VL53L0X
    • macOS: ~/Documents/Arduino/libraries/Adafruit_VL53L0X
Problem: sounddevice cannot find audio inputSolutions:
  1. List available devices:
import sounddevice as sd
print(sd.query_devices())
  1. Set device index explicitly:
DEVICE_INDEX = 1  # Change to your device number
  1. On Linux, install PortAudio:
sudo apt install portaudio19-dev python3-pyaudio
Problem: ModuleNotFoundError: No module named 'cv2' even after installationSolutions:
  1. Ensure you’re using the correct Python:
which python  # macOS/Linux
where python  # Windows
  1. Install with full path:
/usr/bin/python3 -m pip install opencv-python
  1. Check if using virtual environment:
# Activate it first
source physislab-env/bin/activate
pip install opencv-python

​
Optional: Advanced Setup

​
Install Jupyter Notebook for Interactive Analysis

pip install jupyter notebook matplotlib
jupyter notebook
Create notebooks to explore data interactively: 
import numpy as np
import matplotlib.pyplot as plt

# Load experimental data
data = np.loadtxt('datos_pendulo.txt')
t = data[:, 0]
theta = data[:, 3]

plt.plot(t, np.degrees(theta))
plt.xlabel('Time (s)')
plt.ylabel('Angle (degrees)')
plt.show()

​
GPU-Accelerated OpenCV (Optional)

For faster processing on systems with NVIDIA GPUs: 
# Uninstall CPU version
pip uninstall opencv-python

# Install GPU version
pip install opencv-contrib-python
Requires CUDA toolkit installation.

​
Next Steps

Run Your First Experiment

Start with the free fall camera experiment

Camera Tracking Guide

Learn how to calibrate cameras and track objects

Data Analysis

Understanding the analysis scripts and results

Experiments Overview

Explore all available experiments
Installation Complete! You’re now ready to perform physics experiments with PhysisLab. Each experiment folder contains specific instructions and README files with additional details.

Build docs developers (and LLMs) love

Get started for freeTalk to us