Microcontroller Acquisition Proxy & Data Analysis

This project provides a Python-based proxy and control interface for a microcontroller acquisition system, along with Jupyter notebook tools for analyzing the resulting data. It is designed for experiments involving multi-channel ADC data acquisition, such as cosmic ray or muon detection.

---

Table of Contents

• Features
• Requirements
• Project Structure
• Usage
  • 1. Data Acquisition with atom.py
    • Command-Line Arguments
    • Interactive CLI
    • File Naming Convention
  • 2. Data Analysis with analyze.ipynb
    • Typical Workflow
    • Analysis Functions
    • Example Usage
• Troubleshooting
• License

---

Features

• Serial communication with a microcontroller for multi-channel ADC data acquisition.
• Interactive command-line interface for sending commands and controlling acquisition.
• Automatic logging of raw data and event maxima to timestamped files.
• Jupyter notebook for data visualization, filtering, and advanced analysis.

---

Requirements

• Python 3.7+
• pyserial
• numpy
• matplotlib (for plotting in the notebook)
• Jupyter Notebook or VSCode with Jupyter extension (for analyze.ipynb)

---

Project Structure

.
├── atom.py                # Main acquisition proxy and CLI
├── analyze.ipynb          # Jupyter notebook for data analysis
├── analize.py             # Library used in the notebook
├── 2025xxxx_data*.txt     # Example data files (generated)
├── 2025xxxx_log*.txt      # Example log files (generated)
└── README.md

---

Usage

1. Data Acquisition with atom.py

The atom.py script acts as a proxy between your computer and the microcontroller, handling data acquisition, logging, and user commands. Generates two output file: data and log.

Command-Line Arguments

Run the script from your terminal:

python3 atom.py <serial_port> [options]

Arguments:

• serial_port (required): Serial port (e.g., /dev/ttyUSB0 or COM7)

Options:

• --baud: Baud rate (default: 115200)
• --log: Log file name prefix (default: acquisition_log.txt)
• --data: Data file name prefix (default: data.txt)
• --adj-stdby: Standby bias adjustment value (default: 240)
• --adj-on: On bias adjustment value (default: 220)
• --threshold: Acquisition threshold (default: 320)
• --n-samples: Number of samples per event (default: 10)

Examples:

python3 atom.py /dev/ttyUSB0 --baud 115200 --adj-on 200 --n-samples 3 --threshold 350
python3 atom.py --log 20250629_log_cal --data 20250629_data_cal --adj-on 140  --threshold 300  /dev/ttyACM0

Interactive CLI

After startup, you will enter an interactive CLI that drops you in the pause state. You can:

• Type HELP for available microcontroller commands.
• Use human-readable pin names, e.g., GPIO LED ON.
• Type stop to pause acquisition, resume to continue, exit or quit to stop and exit.

File Naming Convention

Output files are automatically named based on your parameters, e.g.:

• 20250622_data_on_200_N_3_thr_350.txt
• 20250622_acquisition_log_on_200_N_3_thr_350.txt

These files contain event maxima and logs, respectively.

---

2. Data Analysis with analyze.ipynb

The analyze.ipynb notebook provides tools for loading, visualizing, and analyzing the acquired data.

Typical Workflow

1. Open the notebook in Jupyter or VSCode.
2. Set the filename of the data file you want to analyze.
3. Load and plot the data using provided functions.
4. Process and visualize the data using various analysis functions.

Analysis Functions

• load_data(filename): Loads data from a file.
• plot_data(ch0, ch1, ch2, ch3, dt): Plots raw channel data.
• process_channels(...), process_channels_square(...), process_channels_2(...): Different ways to process and combine channel data.
• plot_2d_histogram(x, y): Plots a 2D histogram of processed data.
• filter_xy(x, y, threshold): Filters out low-amplitude events.
• fit_exponential(dt, threshold): Fits an exponential to the event time differences.

Example Usage

Below is a typical analysis cell from the notebook:

filename = "20250622_data_on_210_N_3_thr_330.txt"
ch0, ch1, ch2, ch3, dt = load_data(filename)
plot_data(ch0, ch1, ch2, ch3, dt)
x, y = process_channels(ch0, ch1, ch2, ch3)
x, y = filter_xy(x, y, threshold=0.05)
plot_2d_histogram(x, y)
x, y = process_channels_square(ch0, ch1, ch2, ch3)
x, y = filter_xy(x, y, threshold=0.05)
plot_2d_histogram(x, y)
x, y = process_channels_2(ch0, ch1, ch2, ch3)
x, y = filter_xy(x, y, threshold=0.1)
plot_2d_histogram(x, y)
fit_exponential(dt, 0.1)

You can analyze different files by changing the filename variable.

---

Troubleshooting

• Multiple triggers for a single event:
  If you observe several events in rapid succession for a single physical event (e.g., a large pulse), increase the --n-samples parameter to ensure the entire pulse is captured in one event.

• File not found:
  Ensure the filename in the notebook matches the output from your acquisition run.

• Serial port errors:
  Make sure the correct port is specified and the device is connected.

---

License

This project is provided under the MIT License. See LICENSE for details.

---