{"id":30104090,"url":"https://github.com/alh477/fungivue","last_synced_at":"2025-08-09T22:15:02.064Z","repository":{"id":308812179,"uuid":"1034186868","full_name":"ALH477/FungiVue","owner":"ALH477","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-08T02:43:27.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-08T04:15:09.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ALH477.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T01:58:17.000Z","updated_at":"2025-08-08T02:43:30.000Z","dependencies_parsed_at":"2025-08-08T04:15:12.777Z","dependency_job_id":"bfc607fe-3c67-4896-994c-8cb587e4bd03","html_url":"https://github.com/ALH477/FungiVue","commit_stats":null,"previous_names":["alh477/fungivue"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ALH477/FungiVue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FFungiVue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FFungiVue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FFungiVue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FFungiVue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ALH477","download_url":"https://codeload.github.com/ALH477/FungiVue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FFungiVue/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269646984,"owners_count":24453110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-09T22:15:00.546Z","updated_at":"2025-08-09T22:15:02.049Z","avatar_url":"https://github.com/ALH477.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FungiVue: Open-Source Ultrasound Mushroom Growth Imaging Kit\n\n![FungiVue Logo](https://www.publicdomainpictures.net/pictures/190000/velka/chibi-mushroom-vector.jpg)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-blue.svg)](https://github.com/ALH477/FungiVue)\n[![Issues](https://img.shields.io/github/issues/ALH477/FungiVue)](https://github.com/ALH477/FungiVue/issues)\n[![Forks](https://img.shields.io/github/forks/ALH477/FungiVue)](https://github.com/ALH477/FungiVue/forks)\n[![Stars](https://img.shields.io/github/stars/ALH477/FungiVue)](https://github.com/ALH477/FungiVue/stargazers)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Architecture](#architecture)\n- [Hardware Requirements](#hardware-requirements)\n- [Assembly Instructions](#assembly-instructions)\n- [Software Setup](#software-setup)\n  - [Prerequisites](#prerequisites)\n  - [Cloning the Repository](#cloning-the-repository)\n  - [Arduino Setup](#arduino-setup)\n  - [Python Script Setup](#python-script-setup)\n  - [Optional: NixOS Configuration](#optional-nixos-configuration)\n  - [Optional: Docker Setup](#optional-docker-setup)\n  - [Vue.js Webapp Setup](#vuejs-webapp-setup)\n  - [NGINX Configuration for Webapp Hosting](#nginx-configuration-for-webapp-hosting)\n- [Usage](#usage)\n- [Advanced Configuration](#advanced-configuration)\n- [Troubleshooting](#troubleshooting)\n- [Examples and Demos](#examples-and-demos)\n- [Contributions](#contributions)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Overview\n\nFungiVue 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.\n\nThe 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.\n\nThis 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.\n\n**Project Goals**:\n- Promote accessible biohacking tools.\n- Demonstrate low-cost ultrasound principles.\n- Integrate hardware, software, and AI for educational insights.\n- Support hobbyists, educators, and researchers in mycology.\n\nFor a quick start, see the [Installation and Setup Guide](docs/installation_guide.md) (separate document in the repo).\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Ultrasound Imaging** | Non-invasive A-scan style imaging using HC-SR04 or similar transducers for depth and growth monitoring. |\n| **Multi-Sensor Integration** | Includes temperature/humidity (DHT22) and optional bio-electric signals for comprehensive data. |\n| **Duo-Cluster Processing** | Two Raspberry Pi Zero 2W units for load balancing: one for data acquisition, one for web hosting/ML. |\n| **Machine Learning** | Lightweight TensorFlow Lite model for growth predictions (e.g., mycelium expansion rate). |\n| **Vue.js Dashboard** | Responsive webapp for viewing time-lapse scans, predictions, and real-time data. |\n| **Portability Options** | NixOS for declarative setups, Docker for containerized environments. |\n| **No Soldering Required** | Plug-and-play assembly with jumper wires and USB connections. |\n| **Extensibility** | Modular code; easy to add features like email alerts or cloud syncing. |\n\n## Architecture\n\nThe system follows a layered architecture:\n\n1. **Hardware Layer**: Arduino Uno/Nano collects raw data from sensors (ultrasound, DHT22, bio-electrodes) and sends it via serial to the Raspberry Pi.\n2. **Data Acquisition Layer**: Python script on one Pi processes serial data, generates images/plots, and runs ML inferences.\n3. **Processing/Storage Layer**: Duo-cluster setup allows distributed tasks; data saved as images/JSON in a shared directory.\n4. **Presentation Layer**: Vue.js SPA served by NGINX on the second Pi, fetching and displaying scan results via static files or simple API.\n5. **Optional Layers**: NixOS for reproducible environments, Docker for cross-platform testing.\n\n**Data Flow**:\n- Sensors → Arduino Sketch → Serial → Python Script → Images/JSON → Vue.js Webapp (via NGINX).\n\nThis design ensures efficiency on low-power hardware like Pi Zero 2W (512MB RAM, 1GHz CPU).\n\n## Hardware Requirements\n\nRefer to `docs/parts_list.md` for sourcing and costs. Key components:\n\n- **Raspberry Pi Zero 2W (x2)**: For duo-cluster; handles processing and web hosting.\n- **Arduino Uno or Nano (x1)**: Sensor controller.\n- **Ultrasonic Transducers (x2)**: HC-SR04 or equivalents (40kHz-1MHz range).\n- **DHT22 Sensor (x1)**: Temperature and humidity monitoring.\n- **Bio-Electric Electrodes (x2, optional)**: For mycelium electrical signals.\n- **USB Hub**: For stacking Pis.\n- **MicroSD Cards (x2, 16GB+)**: For OS installation.\n- **Miscellaneous**: Jumper wires, power supplies, enclosure (e.g., 3D-printable box), coupling gel for transducers.\n\nTotal estimated cost: $150-200.\n\n## Assembly Instructions\n\n1. **Duo-Cluster Setup**:\n   - Insert flashed MicroSD cards into each Pi.\n   - Connect Pis via USB hub (one as host, one as peripheral via OTG).\n   - Power on and verify networking (e.g., ping between static IPs like 192.168.0.1 and 192.168.0.2).\n\n2. **Sensor Connections**:\n   - On Arduino:\n     - Transducer 1: Trig → Pin 9, Echo → Pin 10, VCC → 5V, GND → GND.\n     - DHT22: Data → Pin 2, VCC → 5V, GND → GND.\n     - Electrodes (optional): To Analog Pin A1.\n   - Connect Arduino to host Pi via USB.\n\n3. **Chamber Assembly**:\n   - Place transducers facing the substrate in an airtight box.\n   - Apply coupling gel to transducers for improved signal quality.\n   - Route wires out securely to maintain humidity.\n\n**Photos/Diagrams**: See `docs/assembly_diagrams.md` (add if creating visuals).\n\n**Test**: Power on; use `lsusb` on Pi to confirm Arduino detection.\n\n## Software Setup\n\n### Prerequisites\n\n- **Operating System**: Raspberry Pi OS (Lite recommended for efficiency) or NixOS for declarative setups.\n- **Software**:\n  - Arduino IDE (free from arduino.cc).\n  - Python 3.8+ (with numpy, matplotlib, tensorflow-lite, serial).\n  - Node.js/npm (for Vue.js development).\n  - NGINX (for webapp hosting).\n- **Tools**: Computer with SD card reader, internet access.\n\n### Cloning the Repository\n\nClone the repo to your Pi or development machine:\n\n```\ngit clone https://github.com/ALH477/FungiVue.git\ncd FungiVue\n```\n\nInstall base dependencies for non-NixOS systems (e.g., Raspberry Pi OS):\n\n```\nsudo bash scripts/install-linux-deps.sh\n```\n\nThis installs git, Python, pip, Arduino tools, and required Python libraries.\n\n### Arduino Setup\n\n1. **Install Arduino IDE** or CLI on your computer or Pi.\n2. **Upload the Sketch**:\n   - Open `src/arduino/ultrasound_sketch.ino` in Arduino IDE.\n   - Select board (Uno/Nano) and port (e.g., `/dev/ttyUSB0`).\n   - Upload the sketch.\n   - Alternatively, use Arduino CLI on Pi:\n     ```\n     arduino-cli upload -p /dev/ttyUSB0 --fqbn arduino:avr:uno src/arduino/ultrasound_sketch.ino\n     ```\n\nThe 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.\n\n### Python Script Setup\n\n1. **Configure**:\n   - 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).\n   - Dependencies (numpy, matplotlib, serial, tensorflow-lite) are installed via `install-linux-deps.sh`.\n\n2. **Test**:\n   ```\n   python3 src/python/imaging_script.py\n   ```\n   - Reads serial data from Arduino.\n   - Generates A-scan plots (saved as `scan.png` in `/var/www/scans/`).\n   - Runs ML predictions for growth rates.\n   - Outputs data to console and optional CSV.\n\n3. **Background Execution**:\n   - Use `screen` for detached sessions:\n     ```\n     screen -S fungivue python3 src/python/imaging_script.py\n     ```\n   - Or create a systemd service (see [Installation Guide](docs/installation_guide.md)).\n\n4. **Output Configuration**:\n   - Modify script to save images/JSON to `/var/www/scans/` for webapp access:\n     ```\n     sudo mkdir -p /var/www/scans\n     sudo chown -R pi:www-data /var/www/scans\n     ```\n   - Add JSON output (e.g., `scans.json`) listing images: `[{ \"url\": \"/scans/scan_001.png\", \"name\": \"Scan 001\", \"timestamp\": \"2025-08-07T12:00:00\" }]`.\n\n### Optional: NixOS Configuration\n\nFor reproducible, declarative setups:\n1. Flash NixOS image for Raspberry Pi (from nixos.org).\n2. Customize `nix/configuration.nix` using:\n   ```\n   bash scripts/prepare-config.sh\n   ```\n   - Prompts for features like Docker, graphics, or PipeWire.\n3. Copy to `/etc/nixos/` on the Pi.\n4. Apply:\n   ```\n   sudo bash scripts/apply-nixos-config.sh\n   ```\n   Or: `nixos-rebuild switch`.\n\nNixOS handles dependencies declaratively, ensuring consistency across builds.\n\n### Optional: Docker Setup\n\nFor portable, containerized environments:\n1. Build:\n   ```\n   docker build -t fungivue -f docker/Dockerfile .\n   ```\n2. Run, mounting Arduino device:\n   ```\n   docker run -it --device /dev/ttyUSB0 fungivue\n   ```\n3. Mount volumes for persistent data (e.g., `/var/www/scans`).\n\nThe Dockerfile uses a lightweight Debian base with pre-installed dependencies.\n\n### Vue.js Webapp Setup\n\nThe 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.\n\n1. **Create Project**:\n   - Install Vue CLI:\n     ```\n     sudo npm install -g @vue/cli\n     ```\n   - Create app:\n     ```\n     vue create fungi-vue-app\n     cd fungi-vue-app\n     npm install axios\n     ```\n\n2. **App Code (`src/App.vue`)**:\n   ```vue\n   \u003ctemplate\u003e\n     \u003cdiv id=\"app\"\u003e\n       \u003ch1\u003eFungiVue Ultrasound Scan Dashboard\u003c/h1\u003e\n       \u003cp\u003eDisplaying latest mushroom growth scans\u003c/p\u003e\n       \u003cdiv v-if=\"scans.length \u003e 0\" class=\"scan-grid\"\u003e\n         \u003cdiv v-for=\"(scan, index) in scans\" :key=\"index\" class=\"scan-item\"\u003e\n           \u003cimg :src=\"scan.url\" :alt=\"scan.name\" width=\"300\" /\u003e\n           \u003cp\u003e{{ scan.name }} - Timestamp: {{ scan.timestamp }}\u003c/p\u003e\n         \u003c/div\u003e\n       \u003c/div\u003e\n       \u003cp v-else\u003eNo scans available yet.\u003c/p\u003e\n       \u003cbutton @click=\"refreshScans\"\u003eRefresh Scans\u003c/button\u003e\n     \u003c/div\u003e\n   \u003c/template\u003e\n\n   \u003cscript\u003e\n   import axios from 'axios';\n\n   export default {\n     data() {\n       return {\n         scans: [],  // Array of { url: '/scans/scan_001.png', name: 'Scan 001', timestamp: '2025-08-07' }\n       };\n     },\n     mounted() {\n       this.loadScans();\n     },\n     methods: {\n       async loadScans() {\n         // For static files, hardcode or fetch from a JSON endpoint\n         // Example: Assume a backend API at /api/scans returns JSON\n         try {\n           const response = await axios.get('/api/sc evidences');\n           this.scans = response.data;\n         } catch (error) {\n           console.error('Error loading scans:', error);\n           // Fallback to static list if no API\n           this.scans = [\n             { url: '/scans/scan_001.png', name: 'Scan 001', timestamp: new Date().toISOString() },\n             // Add more as needed\n           ];\n         }\n       },\n       refreshScans() {\n         this.loadScans();\n       }\n     }\n   };\n   \u003c/script\u003e\n\n   \u003cstyle\u003e\n   .scan-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; }\n   .scan-item { border: 1px solid #ccc; padding: 10px; text-align: center; }\n   \u003c/style\u003e\n   ```\n\n3. **Main Entry (`src/main.js`)**:\n   ```javascript\n   import { createApp } from 'vue';\n   import App from './App.vue';\n\n   createApp(App).mount('#app');\n   ```\n\n4. **Build for Production**:\n   ```\n   npm run build\n   ```\n   Outputs static files to `dist/`.\n\n5. **Deploy**:\n   ```\n   sudo mkdir -p /var/www/fungi-vue\n   sudo cp -r dist/* /var/www/fungi-vue/\n   sudo chown -R www-data:www-data /var/www/fungi-vue\n   ```\n\n6. **Integration with Python**:\n   - Modify `imaging_script.py` to generate `scans.json` in `/var/www/scans/`:\n     ```python\n     import json\n     # After saving scan.png\n     scan_data = [{\"url\": \"/scans/scan_001.png\", \"name\": \"Scan 001\", \"timestamp\": \"2025-08-07T12:00:00\"}]\n     with open('/var/www/scans/scans.json', 'w') as f:\n         json.dump(scan_data, f)\n     ```\n   - Alternatively, run a Flask server for dynamic `/api/scans` (requires `pip install flask`).\n\n### NGINX Configuration for Webapp Hosting\n\n1. Install NGINX:\n   ```\n   sudo apt install nginx -y\n   ```\n\n2. Create config (`/etc/nginx/sites-available/fungi-vue`):\n   ```\n   server {\n       listen 80;\n       server_name localhost;\n\n       root /var/www/fungi-vue;\n       index index.html;\n\n       location / {\n           try_files $uri $uri/ /index.html;\n       }\n\n       location /scans/ {\n           alias /var/www/scans/;\n           autoindex on;\n       }\n\n       location /api/ {\n           proxy_pass http://localhost:5000/;  # If using Flask for dynamic API\n           proxy_set_header Host $host;\n           proxy_set_header X-Real-IP $remote_addr;\n       }\n   }\n   ```\n\n3. Enable and restart:\n   ```\n   sudo ln -s /etc/nginx/sites-available/fungi-vue /etc/nginx/sites-enabled/\n   sudo rm /etc/nginx/sites-enabled/default\n   sudo nginx -t\n   sudo systemctl restart nginx\n   ```\n\n4. Access: Open `http://\u003cpi-ip-address\u003e` in a browser to view the dashboard.\n\n## Usage\n\n1. **Prepare Substrate**: Inoculate mushroom substrate in the chamber.\n2. **Start System**:\n   - Power on Pis and Arduino.\n   - Run Python script: `python3 src/python/imaging_script.py` (or via systemd/screen).\n3. **View Results**: Access the Vue.js dashboard at `http://\u003cpi-ip\u003e` to see scan images and predictions.\n4. **Refresh**: Click \"Refresh Scans\" to update the view.\n\n**Duo-Cluster**:\n- Pi 1: Runs Arduino and Python script for data acquisition.\n- Pi 2: Hosts NGINX and Vue.js app, fetching data from shared `/scans/` (via NFS or rsync).\n\n## Advanced Configuration\n\n- **ML Customization**: Replace `growth_model.tflite` with a custom-trained model (train on growth datasets using TensorFlow).\n- **Dynamic API**: Add Flask to `imaging_script.py` for real-time `/api/scans` endpoint.\n- **Networking**: Use NFS for shared `/scans/` across Pis:\n  ```\n  sudo apt install nfs-kernel-server\n  # Configure /etc/exports and mount on second Pi\n  ```\n- **Security**: Enable HTTPS with Let's Encrypt:\n  ```\n  sudo apt install certbot python3-certbot-nginx\n  sudo certbot --登\n  ```\n- **Extensions**: Add camera module for visual overlays, email alerts via SMTP, or cloud syncing to Google Drive.\n\n## Troubleshooting\n\n- **No Arduino Data**: Check port (`dmesg | grep tty`), baud rate (9600), group (`dialout` via `usermod -aG dialout pi`).\n- **Webapp Fails**: Inspect browser console; verify `/var/www/fungi-vue` paths and permissions (`chown www-data`).\n- **Low Performance**: On Pi Zero, reduce ML batch size; check `free -h` or `htop`.\n- **No Scans Displayed**: Ensure `imaging_script.py` writes to `/var/www/scans/`; check JSON format.\n- **NixOS Errors**: Run `nixos-rebuild switch --show-trace`; verify config syntax.\n\nLogs: Check `/var/log/nginx/error.log` or Python stdout.\n\n## Examples and Demos\n- **Demo Video**: [Placeholder for YouTube link].\n\n## Contributions\n\nContributions are welcome! Fork the repo, create issues/PRs for:\n- Cost optimizations (e.g., cheaper transducers).\n- New sensors (e.g., CO2 monitors).\n- UI enhancements (e.g., real-time charts).\nFollow code style: ESLint for JS, Black for Python. Use issue templates in repo.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\nCopyright (c) 2025 [DeMoD LLC].\n\n## Acknowledgments\n\n- Inspired by biohacking and mycology communities.\n- Thanks to NewPing, DHT, Vue.js, and TensorFlow Lite developers.\n- Gratitude to contributors and testers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Ffungivue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falh477%2Ffungivue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Ffungivue/lists"}