Contributing to OOMWOO

Thanks for your interest. OOMWOO is an open-source robot vacuum you build yourself, and it's at a very early stage. That's the best time to get involved, the foundations are still being laid and your input can shape the direction.

The project is built module by module so many people can work in parallel. Browse the module list in the README, and see ARCHITECTURE.md for how the pieces fit together.

Ways to help right now

You don't need to be a roboticist to contribute:

Ideas and feedback — open a Discussion about features, design choices, or what would make you build one.
Code — firmware, ROS2 packages, Home Assistant integration.
Hardware — 3D-printable chassis design, mechanical parts, PCB.
Documentation — build guides, wiring diagrams, troubleshooting notes.
Testing — once there's something to build, real-world build reports are gold.
Spread the word — star the repo, share your build, post a demo.

Getting started

Pick a module. Browse the module list in the README and choose a hardware or software module. Software and simulation modules can start immediately; hardware modules wait on the interface specs in ARCHITECTURE.md. Read the module's README.md so you know the contract.
Start a conversation first. Claim or ask about the module in its Issue or Discussion before writing code, so we align on the approach and avoid wasted effort.
Build it in your own repo. For code and simulation modules, develop your package in your own public repository — you own it, version it, and keep the credit. Build against the ROS2 interface contract in SOFTWARE_INTERFACES.md so your work stays interoperable with other modules. (Docs and small reference material are handled differently — see below.)
Submit a pointer PR. Add a link to your repo in the module's entry with a one-line description. It's small, easy to review, and lets several implementations of the same module sit side by side. Keep the PR focused.
Iterate in the open. Modules are swappable — the best implementation surfaces over time, with the maintainer having the last call. A design that isn't selected is still a useful fallback.

How contributions are structured

OOMWOO keeps the core small and lets the community grow around it:

Canonical / reference code stays first-party. oomwoo-one (robot description + sim), oomwoo-install (dev environment), and the kaiaai_* packages are maintained by the project so the out-of-the-box build always works.
Module implementations (code) live in your repo. You build a competing implementation of a module — a sim, a navigation stack, a behavior — in your own repository and submit a link. The project features accepted work from the module's page, credited to you. When a contribution is featured, we pin a specific commit or tag (and may fork it into the makerspet org) so the reference build stays reproducible even if the upstream repo moves.
Docs, specs and small reference material stay in-tree. Part specifications, datasheets, STEP-model sourcing notes, PCB notes, and benchmarks are lightweight and best kept alongside the project — contribute those under contributions/<module>/<your-username>/ as files in a PR.

Why links for code? You keep ownership, credit, and freedom to iterate; the project stays lean and avoids absorbing third-party code and its licensing; and multiple implementations of a module can coexist and be compared. The shared SOFTWARE_INTERFACES.md contract is what keeps independently-built modules compatible.

Hardware contributions

For CAD and mechanical work, please include source files (not just exported STLs) where possible, so others can modify your design. Note the tool and version you used. If your change affects the bill of materials, mention it in the PR. Each hardware module must stay within the mechanical/electrical interfaces in ARCHITECTURE.md.

Safety: battery, charging, motor-driver, and mains-adjacent modules require a maintainer safety review before merge. Include a hazard note in your submission.

Code style

Conventions are still being established. For now: keep it simple, readable, and consistent with the surrounding code. ROS2 packages should follow standard ROS2 layout and naming. We'll formalize linting and style as the codebase grows.

Licensing

By contributing, you agree that your contributions are licensed under the project's Apache License 2.0. Hardware design files will be released under an open hardware license (to be finalized); contributions of hardware files are made on that same open basis.

Community and conduct

Be respectful, helpful, and welcoming. We want OOMWOO to be an easy, friendly place for makers of every skill level. Harassment or hostility isn't tolerated.

Questions? Open a Discussion or join us on Discord.

5.4 KiB Raw Permalink Blame History