# kanishkasthana/chronoseq architecture

> Architecture diagram of the GitHub repository kanishkasthana/chronoseq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kanishkasthana/chronoseq
- Repository: https://github.com/kanishkasthana/chronoseq

## Overview

##### Project type and purpose
- ChronoSeq is an open-source hardware + software platform for automated microfluidic time-series sampling (wet-lab device).
- It combines:
- A host PC running Jupyter notebooks & Python code (“protocol & software”)
- Vendor pressure-controller SDK and DLL (Elveflow OB1)
- Microcontroller firmware (Arduino, ESP32, relay/servo controllers)
- Sensors (Sensirion flow sensors) and actuators (valves, servos, XY/XYZ robots)
- CAD files and assembly instructions for mechanical parts

##### File structure
- Top-level “protocol_and_software_*.ipynb” notebooks → user-facing workflow & device control
- “conda_environment_file/chrono.env.yml” → Python environment & dependencies (Elveflow64.py, numpy, etc.)
- “DLL64/” + “Elveflow64.py” → low-level Python wrapper around vendor SDK/DLL
- Multiple “*.ino” folders → Arduino and ESP32 sketches for valve controllers, droplet collectors, XY/XYZ robots, servos
- “CAD_Files/…” → mechanical models (not part of the runtime architecture but useful for assembly)
- “config/Elveflow64.py” → configuration of the pressure controller interface

##### README for additional insights
- User installs Git and Conda, clones repo with submodules, creates & activates “Chrono” conda env, then launches Jupyter
- Jupyter notebooks orchestrate device assembly, chip preparation, runtime protocols, and data-analysis steps

##### Main components & interactions
a. Host PC (Jupyter Notebook UI + Python backend)
- Runs user notebooks (ChronoSeq_Overview, protocol_and_software_for_running_chronoseq_device, etc.)
- Uses Python packages (via chrono.env.yml) including Elveflow64.py to drive pressure controller
- Opens serial ports to Arduinos/ESP32s for relay/servo commands and sensor data

b. Vendor Pressure Controller (Elveflow OB1)
- Controlled via DLL64 + Python wrapper (Elveflow64.py) over USB or Ethernet
- Applies precise pressures to microfluidic reservoirs

c. Microcontroller Fleet
- Multiple Arduino/ESP32 boards running different .ino sketches:
– Valve controller (relay_Control, relay_Control_esp32, vortextRelayControl)
– Servo controller (both_servos, servo_control)
– Droplet collector (droplet_collector)
– Plotter/XY/XYZ motion (plotter_control, doesbot, xy_robot, xyz_robot folders in CAD)
- Communicate with host via USB serial

d. Sensors & Actuators
- Sensirion LG16-1000D flow sensor housing (CAD) – provides flow feedback
- Solenoid valves, relays, servo motors – physically control fluid routing & mechanical positioning
- Microfluidic chip (CAD in “Microfluidic Chip Manufacture”) – site of injection and sampling

e. Data & Protocol Flow
- User selects/edits a notebook → Python code issues commands to pressure controller + microcontrollers
- Sensor readings return via serial → notebook captures data, plots real-time figures
- At experiment end, notebooks process and save data for downstream analysis

##### Architectural patterns & design principles
- Layered architecture:
1. Presentation: Jupyter notebooks (HTML/JS + Python)
2. Application: Python modules + Elveflow64 wrapper
3. Device drivers: USB serial to Arduino/ESP32; DLL calls to pressure controller
4. Hardware: valves, pumps, servos, sensors, microfluidic chip
- Modular firmware: each .ino sketch implements a single function (valves, motion, droplet collection)
- Configuration-driven: “config/Elveflow64.py” and conda env file isolate hardware settings and dependencies

##### Detail
- Call out the conda environment as a dependency block

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        UI["Jupyter Notebook UI"]:::ui
    end

    subgraph "Application Layer"
        Env["Conda Environment File"]:::app
        Config["Elveflow64 Configuration"]:::app
        PythonWrapper["Elveflow64 Python Wrapper"]:::app
    end

    subgraph "Communication Layer"
        SDK["DLL64 (Elveflow SDK)"]:::comm
        Serial["USB Serial (COMx)"]:::comm
        Ethernet["USB/Ethernet"]:::comm
    end

    subgraph "Hardware Layer"
        Pressure["Pressure Controller (Elveflow OB1)"]:::hw
        subgraph "Microcontrollers"
            AVR["Arduino Valve Controller"]:::hw
            ESP["ESP32 Valve Controller"]:::hw
            Vortex["Vortex Relay Controller"]:::hw
            Servo1["Servo Controller"]:::hw
            Servo2["Both Servos Controller"]:::hw
            Droplet["Droplet Collector MCU"]:::hw
            Doesbot["Doesbot Robot MCU"]:::hw
            Plotter["Plotter/XY Robot MCU"]:::hw
        end
        Sensor["Sensirion Flow Sensor"]:::hw
        Chip["Microfluidic Chip"]:::hw
    end

    UI -->|"runs notebook"| PythonWrapper
    PythonWrapper -->|"imports config"| Config
    PythonWrapper -->|"uses environment"| Env
    PythonWrapper -->|"calls SDK"| SDK
    SDK -->|"via USB/Ethernet"| Pressure

    PythonWrapper -->|"serial commands"| Serial
    Serial --> AVR
    Serial --> ESP
    Serial --> Vortex
    Serial --> Servo1
    Serial --> Servo2
    Serial --> Droplet
    Serial --> Doesbot
    Serial --> Plotter

    Sensor -->|"flow data"| Serial
    Serial -->|"data back"| PythonWrapper
    PythonWrapper -->|"plots results"| UI

    Pressure -->|"apply pressure"| Chip
    AVR -->|"control valves"| Chip
    ESP -->|"control valves"| Chip
    Vortex -->|"control valves"| Chip
    Servo1 -->|"actuate servos"| Chip
    Servo2 -->|"actuate servos"| Chip
    Droplet -->|"collect samples"| Chip
    Doesbot -->|"move chip"| Chip
    Plotter -->|"move chip"| Chip

    click UI "https://github.com/kanishkasthana/chronoseq/blob/master/ChronoSeq_Overview.ipynb"
    click Env "https://github.com/kanishkasthana/chronoseq/blob/master/conda_environment_file/chrono.env.yml"
    click Config "https://github.com/kanishkasthana/chronoseq/blob/master/config/Elveflow64.py"
    click PythonWrapper "https://github.com/kanishkasthana/chronoseq/blob/master/Elveflow64.py"
    click SDK "https://github.com/kanishkasthana/chronoseq/tree/master/DLL64/"
    click AVR "https://github.com/kanishkasthana/chronoseq/blob/master/relay_Control/relay_Control.ino"
    click ESP "https://github.com/kanishkasthana/chronoseq/blob/master/relay_Control_esp32/relay_Control_esp32.ino"
    click Vortex "https://github.com/kanishkasthana/chronoseq/blob/master/vortextRelayControl/vortextRelayControl.ino"
    click Servo1 "https://github.com/kanishkasthana/chronoseq/blob/master/servo_control/servo_control.ino"
    click Servo2 "https://github.com/kanishkasthana/chronoseq/blob/master/both_servos/both_servos.ino"
    click Droplet "https://github.com/kanishkasthana/chronoseq/blob/master/droplet_collector/droplet_collector.ino"
    click Doesbot "https://github.com/kanishkasthana/chronoseq/blob/master/doesbot/doesbot.ino"
    click Plotter "https://github.com/kanishkasthana/chronoseq/blob/master/plotter_control/plotter_control.ino"
    click Sensor "https://github.com/kanishkasthana/chronoseq/tree/master/CAD_Files/Sensirion LG16-1000D Flow Sensor/"
    click Chip "https://github.com/kanishkasthana/chronoseq/tree/master/CAD_Files/Microfluidic Chip Manufacture/"

    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
    classDef app fill:#90ee90,stroke:#333,stroke-width:1px
    classDef comm fill:#ffa500,stroke:#333,stroke-width:1px
    classDef hw fill:#d3d3d3,stroke:#333,stroke-width:1px
```
