Skip to content

README.md

Latest commit

 

History

History
123 lines (98 loc) · 5.59 KB

README.md

File metadata and controls

123 lines (98 loc) · 5.59 KB

MicroPython based NMR Spectrometer Control Firmware

A standalone, high-fidelity controller for Earth's Field Nuclear Magnetic Resonance (EFNMR) spectroscopy, built for the Raspberry Pi Pico (RP2040).

This repository contains a professional-grade controller that implements deterministic pulse sequencing and high-speed data acquisition. By offloading critical timing tasks to the RP2040's hardware accelerators (PIO and DMA), the system overcomes the inherent jitter of interpreted MicroPython to maintain the phase coherence required for precision NMR experiments.

Copyright Firmware GUI

Table of Contents

Key Features

  • Microsecond-Accurate Sequencing: Implements CPMG and FID sequences using PIO assembly to ensure deterministic pulse timing.
  • High-Speed Data Acquisition: Achieves 500ksps ADC sampling via a jitter-free DMA hardware pipeline.
  • Real-Time Signal Processing: Desktop GUI features DC offset removal, Hanning windowing, zero-filling, and FFT spectroscopy.
  • Advanced Relaxation Analysis: Automated T2 relaxation fitting for CPMG echo trains.
  • Rx/Tx Isolation: Hardware-level control for receiver isolation during high-power excitation pulses.

User Interface

Free Induction Decay (FID)

FID FID_FFT

Carr-Purcell-Meiboom-Gill (CPMG)

CPMG T2_Analysis CPMG_FFT

System Architecture

graph TD
    subgraph PC ["PC (Python GUI)"]
        GUI[gui.py] -->|Commands: FID/CPMG| Serial[Serial Communication]
        Serial -->|Raw ADC Data| GUI
        GUI -->|Signal Processing| FFT[FFT Analysis]
        GUI -->|Signal Processing| T2[T2 Relaxation Fitting]
        GUI -->|Visualization| Plots[Matplotlib/CustomTkinter]
    end

    subgraph Pico ["RP2040 (MicroPython)"]
        Serial <-->|USB Serial| PicoSerial[main.py]
        PicoSerial -->|Parameters| Sequencer[PIO State Machine]
        Sequencer -->|Timing| TX[Pulse Pin: GP16]
        Sequencer -->|Logic| Switch[Isolation Switch: GP22]
        PicoSerial -->|Trigger| Coil[Polarisation Relay: GP26]
        PicoSerial -->|DMA Config| ADC_HW[ADC DMA Pipeline]
        ADC_HW -->|Buffer| RAM[Bytearray Buffer]
        RAM -->|Serialized CSV| PicoSerial
        
        TX -.->|RF Pulse| Hardware[NMR Hardware]
        Coil -.->|Polarise| Hardware
        Hardware -.->|Signal| ADC_In[ADC Input: GP28]
        ADC_In --> ADC_HW
    end
Loading

Technical Stack

Component Technology Rationale
Firmware MicroPython (RP2) Rapid development with hardware access.
Sequencing PIO Assembly Hard-real-time deterministic execution.
GUI CustomTkinter Modern, stylish interface built on Tkinter.
Processing NumPy / SciPy Industry-standard libraries for FFT and fitting.
Plotting Matplotlib Flexible, high-quality technical visualisations.

Key Design Decisions

Decision Rationale
Hardware DMA Eliminates CPU-induced sampling jitter during high-speed ADC capture.
select.select Enables efficient, non-blocking monitoring of multiple streams without high CPU usage.
CustomTkinter Provides a modern visual aesthetic while maintaining the portability of Python.
PIO sideset Guarantees pin transitions occur exactly on instruction cycles for pulse precision.

Challenges and Lessons Learnt

The implementation of hardware-level logic (PIO and DMA) presented the most significant technical hurdle. Configuring registers and writing assembly required a steep learning curve compared to standard high-level Python.

Lesson learnt: Attempting to implement hardware-level features quickly without a deep conceptual understanding can lead to complex debugging cycles. In future iterations, more time would be allocated to the fundamental study of the RP2040 hardware manual before implementation to streamline the development process.

Installation and Usage

Prerequisites

  • PC: Python 3.8 or higher.
  • Pico: Raspberry Pi Pico (RP2040) with MicroPython installed.

PC Setup

  1. Clone the repository locally.
  2. Install required dependencies: 
    pip install customtkinter pyserial numpy matplotlib scipy
  3. Launch the application: 
    python gui.py

Pico Setup

  1. Connect the Raspberry Pi Pico via USB.
  2. Flash main.py to the device as the root script.

License

Copyright

Copyright (c) 2026 Sajid Ahmed. All Rights Reserved.

This repository is a Proprietary Project.

While I am a strong supporter of Open Source Software, this specific codebase represents a significant personal investment of time and effort and is therefore provided with the following restrictions:

  • Permitted: Viewing, forking (within GitHub only), and local execution for evaluation and personal, non-commercial usage only.
  • Prohibited: Modification, redistribution, commercial use, and AI/LLM training.

For the full legal terms, please see the LICENSE file.