https://github.com/alh477/fungivue
https://github.com/alh477/fungivue
Last synced: 12 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/alh477/fungivue
- Owner: ALH477
- License: mit
- Created: 2025-08-08T01:58:17.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-08-08T02:43:27.000Z (12 months ago)
- Last Synced: 2025-08-08T04:15:09.810Z (12 months ago)
- Language: Nix
- Size: 35.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
Awesome Lists containing this project
README
# FungiVue: Open-Source Ultrasound Mushroom Growth Imaging Kit
[](https://opensource.org/licenses/MIT)
[](https://github.com/ALH477/FungiVue)
[](https://github.com/ALH477/FungiVue/issues)
[](https://github.com/ALH477/FungiVue/forks)
[](https://github.com/ALH477/FungiVue/stargazers)
## Table of Contents
- [Overview](#overview)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Hardware Requirements](#hardware-requirements)
- [Assembly Instructions](#assembly-instructions)
- [Software Setup](#software-setup)
- [Prerequisites](#prerequisites)
- [Cloning the Repository](#cloning-the-repository)
- [Arduino Setup](#arduino-setup)
- [Python Script Setup](#python-script-setup)
- [Optional: NixOS Configuration](#optional-nixos-configuration)
- [Optional: Docker Setup](#optional-docker-setup)
- [Vue.js Webapp Setup](#vuejs-webapp-setup)
- [NGINX Configuration for Webapp Hosting](#nginx-configuration-for-webapp-hosting)
- [Usage](#usage)
- [Advanced Configuration](#advanced-configuration)
- [Troubleshooting](#troubleshooting)
- [Examples and Demos](#examples-and-demos)
- [Contributions](#contributions)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Overview
FungiVue is an open-source, cost-efficient DIY hardware and software kit designed for non-invasive ultrasound imaging of mushroom (mycelium) growth. This project combines affordable off-the-shelf components with modular software to enable real-time monitoring, data visualization, and basic machine learning predictions for growth patterns. It's ideal for educational purposes in biohacking, mycology, and STEM, allowing users to build a functional ultrasound scanner for under $200.
The system uses a duo-cluster of Raspberry Pi Zero 2W boards for distributed processing, an Arduino for sensor data acquisition, and ultrasound transducers for imaging. Data is processed via Python scripts, with optional ML integration using TensorFlow Lite. Results are visualized through a lightweight Vue.js webapp served via NGINX, providing a user-friendly dashboard for scan results.
This repository provides all necessary code, configurations, and documentation. The project is modular, expandable (e.g., add cameras or more sensors), and licensed under MIT for unrestricted use, modification, and distribution.
**Project Goals**:
- Promote accessible biohacking tools.
- Demonstrate low-cost ultrasound principles.
- Integrate hardware, software, and AI for educational insights.
- Support hobbyists, educators, and researchers in mycology.
For a quick start, see the [Installation and Setup Guide](docs/installation_guide.md) (separate document in the repo).
## Key Features
| Feature | Description |
|---------|-------------|
| **Ultrasound Imaging** | Non-invasive A-scan style imaging using HC-SR04 or similar transducers for depth and growth monitoring. |
| **Multi-Sensor Integration** | Includes temperature/humidity (DHT22) and optional bio-electric signals for comprehensive data. |
| **Duo-Cluster Processing** | Two Raspberry Pi Zero 2W units for load balancing: one for data acquisition, one for web hosting/ML. |
| **Machine Learning** | Lightweight TensorFlow Lite model for growth predictions (e.g., mycelium expansion rate). |
| **Vue.js Dashboard** | Responsive webapp for viewing time-lapse scans, predictions, and real-time data. |
| **Portability Options** | NixOS for declarative setups, Docker for containerized environments. |
| **No Soldering Required** | Plug-and-play assembly with jumper wires and USB connections. |
| **Extensibility** | Modular code; easy to add features like email alerts or cloud syncing. |
## Architecture
The system follows a layered architecture:
1. **Hardware Layer**: Arduino Uno/Nano collects raw data from sensors (ultrasound, DHT22, bio-electrodes) and sends it via serial to the Raspberry Pi.
2. **Data Acquisition Layer**: Python script on one Pi processes serial data, generates images/plots, and runs ML inferences.
3. **Processing/Storage Layer**: Duo-cluster setup allows distributed tasks; data saved as images/JSON in a shared directory.
4. **Presentation Layer**: Vue.js SPA served by NGINX on the second Pi, fetching and displaying scan results via static files or simple API.
5. **Optional Layers**: NixOS for reproducible environments, Docker for cross-platform testing.
**Data Flow**:
- Sensors → Arduino Sketch → Serial → Python Script → Images/JSON → Vue.js Webapp (via NGINX).
This design ensures efficiency on low-power hardware like Pi Zero 2W (512MB RAM, 1GHz CPU).
## Hardware Requirements
Refer to `docs/parts_list.md` for sourcing and costs. Key components:
- **Raspberry Pi Zero 2W (x2)**: For duo-cluster; handles processing and web hosting.
- **Arduino Uno or Nano (x1)**: Sensor controller.
- **Ultrasonic Transducers (x2)**: HC-SR04 or equivalents (40kHz-1MHz range).
- **DHT22 Sensor (x1)**: Temperature and humidity monitoring.
- **Bio-Electric Electrodes (x2, optional)**: For mycelium electrical signals.
- **USB Hub**: For stacking Pis.
- **MicroSD Cards (x2, 16GB+)**: For OS installation.
- **Miscellaneous**: Jumper wires, power supplies, enclosure (e.g., 3D-printable box), coupling gel for transducers.
Total estimated cost: $150-200.
## Assembly Instructions
1. **Duo-Cluster Setup**:
- Insert flashed MicroSD cards into each Pi.
- Connect Pis via USB hub (one as host, one as peripheral via OTG).
- Power on and verify networking (e.g., ping between static IPs like 192.168.0.1 and 192.168.0.2).
2. **Sensor Connections**:
- On Arduino:
- Transducer 1: Trig → Pin 9, Echo → Pin 10, VCC → 5V, GND → GND.
- DHT22: Data → Pin 2, VCC → 5V, GND → GND.
- Electrodes (optional): To Analog Pin A1.
- Connect Arduino to host Pi via USB.
3. **Chamber Assembly**:
- Place transducers facing the substrate in an airtight box.
- Apply coupling gel to transducers for improved signal quality.
- Route wires out securely to maintain humidity.
**Photos/Diagrams**: See `docs/assembly_diagrams.md` (add if creating visuals).
**Test**: Power on; use `lsusb` on Pi to confirm Arduino detection.
## Software Setup
### Prerequisites
- **Operating System**: Raspberry Pi OS (Lite recommended for efficiency) or NixOS for declarative setups.
- **Software**:
- Arduino IDE (free from arduino.cc).
- Python 3.8+ (with numpy, matplotlib, tensorflow-lite, serial).
- Node.js/npm (for Vue.js development).
- NGINX (for webapp hosting).
- **Tools**: Computer with SD card reader, internet access.
### Cloning the Repository
Clone the repo to your Pi or development machine:
```
git clone https://github.com/ALH477/FungiVue.git
cd FungiVue
```
Install base dependencies for non-NixOS systems (e.g., Raspberry Pi OS):
```
sudo bash scripts/install-linux-deps.sh
```
This installs git, Python, pip, Arduino tools, and required Python libraries.
### Arduino Setup
1. **Install Arduino IDE** or CLI on your computer or Pi.
2. **Upload the Sketch**:
- Open `src/arduino/ultrasound_sketch.ino` in Arduino IDE.
- Select board (Uno/Nano) and port (e.g., `/dev/ttyUSB0`).
- Upload the sketch.
- Alternatively, use Arduino CLI on Pi:
```
arduino-cli upload -p /dev/ttyUSB0 --fqbn arduino:avr:uno src/arduino/ultrasound_sketch.ino
```
The sketch uses NewPing and DHT libraries to collect ultrasound distance, temperature, humidity, and optional bio-electric data, sending it via serial (9600 baud) every second.
### Python Script Setup
1. **Configure**:
- Ensure `src/python/imaging_script.py` points to the correct serial port (default: `/dev/ttyUSB0`) and TensorFlow Lite model (`growth_model.tflite`, assumed in repo).
- Dependencies (numpy, matplotlib, serial, tensorflow-lite) are installed via `install-linux-deps.sh`.
2. **Test**:
```
python3 src/python/imaging_script.py
```
- Reads serial data from Arduino.
- Generates A-scan plots (saved as `scan.png` in `/var/www/scans/`).
- Runs ML predictions for growth rates.
- Outputs data to console and optional CSV.
3. **Background Execution**:
- Use `screen` for detached sessions:
```
screen -S fungivue python3 src/python/imaging_script.py
```
- Or create a systemd service (see [Installation Guide](docs/installation_guide.md)).
4. **Output Configuration**:
- Modify script to save images/JSON to `/var/www/scans/` for webapp access:
```
sudo mkdir -p /var/www/scans
sudo chown -R pi:www-data /var/www/scans
```
- Add JSON output (e.g., `scans.json`) listing images: `[{ "url": "/scans/scan_001.png", "name": "Scan 001", "timestamp": "2025-08-07T12:00:00" }]`.
### Optional: NixOS Configuration
For reproducible, declarative setups:
1. Flash NixOS image for Raspberry Pi (from nixos.org).
2. Customize `nix/configuration.nix` using:
```
bash scripts/prepare-config.sh
```
- Prompts for features like Docker, graphics, or PipeWire.
3. Copy to `/etc/nixos/` on the Pi.
4. Apply:
```
sudo bash scripts/apply-nixos-config.sh
```
Or: `nixos-rebuild switch`.
NixOS handles dependencies declaratively, ensuring consistency across builds.
### Optional: Docker Setup
For portable, containerized environments:
1. Build:
```
docker build -t fungivue -f docker/Dockerfile .
```
2. Run, mounting Arduino device:
```
docker run -it --device /dev/ttyUSB0 fungivue
```
3. Mount volumes for persistent data (e.g., `/var/www/scans`).
The Dockerfile uses a lightweight Debian base with pre-installed dependencies.
### Vue.js Webapp Setup
The Vue.js webapp is a single-page application (SPA) built with Vue 3, displaying scan results (images and predictions) in a responsive dashboard. It uses Axios for fetching data and is served statically via NGINX for efficiency on Pi Zero 2W.
1. **Create Project**:
- Install Vue CLI:
```
sudo npm install -g @vue/cli
```
- Create app:
```
vue create fungi-vue-app
cd fungi-vue-app
npm install axios
```
2. **App Code (`src/App.vue`)**:
```vue
FungiVue Ultrasound Scan Dashboard
Displaying latest mushroom growth scans
![]()
{{ scan.name }} - Timestamp: {{ scan.timestamp }}
No scans available yet.
Refresh Scans
import axios from 'axios';
export default {
data() {
return {
scans: [], // Array of { url: '/scans/scan_001.png', name: 'Scan 001', timestamp: '2025-08-07' }
};
},
mounted() {
this.loadScans();
},
methods: {
async loadScans() {
// For static files, hardcode or fetch from a JSON endpoint
// Example: Assume a backend API at /api/scans returns JSON
try {
const response = await axios.get('/api/sc evidences');
this.scans = response.data;
} catch (error) {
console.error('Error loading scans:', error);
// Fallback to static list if no API
this.scans = [
{ url: '/scans/scan_001.png', name: 'Scan 001', timestamp: new Date().toISOString() },
// Add more as needed
];
}
},
refreshScans() {
this.loadScans();
}
}
};
.scan-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; }
.scan-item { border: 1px solid #ccc; padding: 10px; text-align: center; }
```
3. **Main Entry (`src/main.js`)**:
```javascript
import { createApp } from 'vue';
import App from './App.vue';
createApp(App).mount('#app');
```
4. **Build for Production**:
```
npm run build
```
Outputs static files to `dist/`.
5. **Deploy**:
```
sudo mkdir -p /var/www/fungi-vue
sudo cp -r dist/* /var/www/fungi-vue/
sudo chown -R www-data:www-data /var/www/fungi-vue
```
6. **Integration with Python**:
- Modify `imaging_script.py` to generate `scans.json` in `/var/www/scans/`:
```python
import json
# After saving scan.png
scan_data = [{"url": "/scans/scan_001.png", "name": "Scan 001", "timestamp": "2025-08-07T12:00:00"}]
with open('/var/www/scans/scans.json', 'w') as f:
json.dump(scan_data, f)
```
- Alternatively, run a Flask server for dynamic `/api/scans` (requires `pip install flask`).
### NGINX Configuration for Webapp Hosting
1. Install NGINX:
```
sudo apt install nginx -y
```
2. Create config (`/etc/nginx/sites-available/fungi-vue`):
```
server {
listen 80;
server_name localhost;
root /var/www/fungi-vue;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /scans/ {
alias /var/www/scans/;
autoindex on;
}
location /api/ {
proxy_pass http://localhost:5000/; # If using Flask for dynamic API
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
3. Enable and restart:
```
sudo ln -s /etc/nginx/sites-available/fungi-vue /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
```
4. Access: Open `http://` in a browser to view the dashboard.
## Usage
1. **Prepare Substrate**: Inoculate mushroom substrate in the chamber.
2. **Start System**:
- Power on Pis and Arduino.
- Run Python script: `python3 src/python/imaging_script.py` (or via systemd/screen).
3. **View Results**: Access the Vue.js dashboard at `http://` to see scan images and predictions.
4. **Refresh**: Click "Refresh Scans" to update the view.
**Duo-Cluster**:
- Pi 1: Runs Arduino and Python script for data acquisition.
- Pi 2: Hosts NGINX and Vue.js app, fetching data from shared `/scans/` (via NFS or rsync).
## Advanced Configuration
- **ML Customization**: Replace `growth_model.tflite` with a custom-trained model (train on growth datasets using TensorFlow).
- **Dynamic API**: Add Flask to `imaging_script.py` for real-time `/api/scans` endpoint.
- **Networking**: Use NFS for shared `/scans/` across Pis:
```
sudo apt install nfs-kernel-server
# Configure /etc/exports and mount on second Pi
```
- **Security**: Enable HTTPS with Let's Encrypt:
```
sudo apt install certbot python3-certbot-nginx
sudo certbot --登
```
- **Extensions**: Add camera module for visual overlays, email alerts via SMTP, or cloud syncing to Google Drive.
## Troubleshooting
- **No Arduino Data**: Check port (`dmesg | grep tty`), baud rate (9600), group (`dialout` via `usermod -aG dialout pi`).
- **Webapp Fails**: Inspect browser console; verify `/var/www/fungi-vue` paths and permissions (`chown www-data`).
- **Low Performance**: On Pi Zero, reduce ML batch size; check `free -h` or `htop`.
- **No Scans Displayed**: Ensure `imaging_script.py` writes to `/var/www/scans/`; check JSON format.
- **NixOS Errors**: Run `nixos-rebuild switch --show-trace`; verify config syntax.
Logs: Check `/var/log/nginx/error.log` or Python stdout.
## Examples and Demos
- **Demo Video**: [Placeholder for YouTube link].
## Contributions
Contributions are welcome! Fork the repo, create issues/PRs for:
- Cost optimizations (e.g., cheaper transducers).
- New sensors (e.g., CO2 monitors).
- UI enhancements (e.g., real-time charts).
Follow code style: ESLint for JS, Black for Python. Use issue templates in repo.
## License
MIT License. See [LICENSE](LICENSE) for details.
Copyright (c) 2025 [DeMoD LLC].
## Acknowledgments
- Inspired by biohacking and mycology communities.
- Thanks to NewPing, DHT, Vue.js, and TensorFlow Lite developers.
- Gratitude to contributors and testers.