shoal

Fish that eat pollution and report what they see.

An open-source distributed water remediation and monitoring system based on biomimetic fish that metabolize aquatic pollutants for power.

A swarm of small soft-bodied fish forages contaminated waterways. Their guts are microbial fuel cell stacks seeded with substrate-specific consortia. They eat hydrocarbons and dissolved organics for power, mechanically capture microplastics and heavy metals for return-to-dock disposal, and continuously map water quality. Docks are passive benthic installations that recharge the fish, swap their cartridges, aggregate captured waste, and offload data to shore.

→ Documentation: https://openie-dev.github.io/shoal/ → Architecture spec: ARCHITECTURE.md

Repository structure

shoal/
├── ARCHITECTURE.md       canonical full-system spec
├── index.md              site landing page
├── docs/                 site nav pages (fish, dock, cartridges, ...)
│
├── chassis/              mechanical CAD, hull, propulsion
│   ├── chassis-A-thunniform/
│   └── chassis-B-bistable/
│
├── gut/                  MFC cartridge — design, biology, manufacturing
│   ├── shell/            cartridge mechanical
│   ├── stack/            anode/cathode/membrane spec
│   ├── consortia/        microbial protocols per pollutant target
│   └── seeding/          dock-side reseeding procedures
│
├── soc/                  shoal-soc RTL, simulation, tooling
├── firmware/             on-fish firmware
├── dock/                 dock hardware + firmware
├── fleet/                cloud + dock-side fleet management
├── sim/                  simulation (Stonefish + plume models + RL training)
└── data/                 schemas, reference datasets, pollution maps

Licenses

Surface	License	File
Hardware	CERN-OHL-S 2.0	LICENSE-HARDWARE
Software	Apache 2.0	LICENSE-SOFTWARE
Documentation	CC-BY-SA 4.0	LICENSE-DOCS
Datasets	CC0 1.0	(per-dataset metadata)

Contributing

The highest-leverage contributions:

• Biology. A better consortium for a target pollutant directly improves every fish in every shoal.
• Sensors. Better detection of low-concentration target pollutants (BTEX, PAH, PFAS, microplastics, dissolved metals).
• Power. Anode materials, membrane chemistries, low-Vin boost converters that improve net energy harvest.
• Cognition. Plume-tracking policies that work in real intermittent-signal field conditions.
• Deployments. Run a shoal in your watershed. Publish what happens. The dataset is the contribution.

See docs/governance.md for how decisions get made.

Building the docs site locally

bundle install
bundle exec jekyll serve

Then open http://localhost:4000/shoal/.

The site auto-deploys to GitHub Pages on push to main via .github/workflows/pages.yml.

On the OpenIE stack

shoal lives in the OpenIE open-source ecosystem alongside openloco and is a validation workload for the OpenIE silicon, energy, compute, and corridor stacks. See docs/governance.md and ARCHITECTURE.md §1.4.