Repos structure update

[BotshareAI]

OpenAMRobot: Repository Structure

Separated Hardware (HW) and Software (SW) Repositories for Mobile Platform and Humanoid

Purpose

This document defines a clean, scalable, and professional GitHub repository structure for the OpenAMRobot organization.

Goals:

• Clear separation between Software (SW) and Hardware (HW)
• Support for multiple robot product families
• Shared ecosystem without duplication
• Easy onboarding for developers, partners, and contributors
• Long-term maintainability for open-source and commercial use

This structure inherits the original ecosystem concept and formalizes the HW / SW split per product.

---

1. GitHub Organization: Top-Level Structure

openAMRobot/
│
├── .github/
│
├── openamrobot-manifest
├── openamrobot-docs
├── openamrobot-comm
├── openamrobot-interfaces
├── openamrobot-ui
│
├── openamr-platform-sw
├── openamr-platform-hw
│
├── openamh-humanoid-sw
├── openamh-humanoid-hw

Core philosophy:

• Shared ecosystem repositories define contracts, interfaces, and tooling
• Product repositories contain only product-specific content
• Hardware and Software are always separated
• Simulation lives in Software repositories, firmware lives in Hardware repositories

---

2. Shared Ecosystem Repositories

These repositories are product-agnostic and must remain stable across all robots.

---

2.1 openamrobot-manifest

Single entry point for developers and CI

Purpose:

• Reproducible workspace setup
• Defines compatible repository sets per product
• Replaces monolithic repositories

openamrobot-manifest/
├── manifests/
│ ├── openamr_platform.repos
│ ├── openamh_humanoid.repos
│ └── full_system.repos
│
├── docker/ or .devcontainer/
├── scripts/
│ ├── install_deps.sh
│ ├── build_ros2.sh
│ ├── run_sim.sh
│ └── run_real.sh
│
├── README.md
├── CONTRIBUTING.md

---

2.2 openamrobot-docs

Single source of truth for documentation

openamrobot-docs/
├── docs/
│ ├── getting_started/
│ ├── architecture/
│ ├── safety/
│ ├── comm/
│ ├── interfaces/
│ ├── ui/
│ ├── openamr_platform/
│ ├── openamh_humanoid/
│ └── troubleshooting/
│
├── compatibility_matrix.md
├── hardware_revision_matrix.md
├── mkdocs.yml
├── README.md

---

2.3 openamrobot-comm

Canonical communication and safety contract

Purpose:

• Prevent protocol drift
• Central definition of safety, faults, and system states

openamrobot-comm/
├── spec/
│ ├── protocol_overview.md
│ ├── frame_catalog.md
│ ├── fault_codes.md
│ ├── safety_states.md
│ └── versioning.md
│
├── reference/
│ ├── c/
│ ├── cpp/
│ └── python/
│
├── tools/
├── tests/
├── README.md

---

2.4 openamrobot-interfaces

Shared ROS 2 messages and conventions

openamrobot-interfaces/
├── openamrobot_msgs/
│ ├── msg/
│ ├── srv/
│ ├── action/
│ ├── CMakeLists.txt
│ └── package.xml
│
├── conventions/
│ ├── frames_and_units.md
│ ├── topic_naming.md
│ └── qos_profiles.md
│
├── README.md

---

2.5 openamrobot-ui

Unified operator UI (capability-driven)

openamrobot-ui/
├── ros2/
├── web/
├── api/
├── docs/
├── scripts/
├── README.md

---

3. Product Repositories: Hardware / Software Split

Each robot family has two repositories:

• *-sw – ROS 2, simulation, configuration, CI
• *-hw – CAD, electronics, firmware, manufacturing

---

3.1 OpenAMR Mobile Platform: Software

Repository: openamr-platform-sw

openamr-platform-sw/
├── ros2/
│ ├── src/
│ │ ├── openamr_description
│ │ ├── openamr_bringup
│ │ ├── openamr_control
│ │ ├── openamr_drivers
│ │ └── openamr_navigation
│ │
│ ├── launch/
│ └── config/
│ └── variants/
│ ├── jazzy/
│ ├── humble/
│ └── sim/
│
├── sim/
│ ├── worlds/
│ ├── models/
│ └── launch/
│
├── tools/
├── .github/workflows/
├── CODEOWNERS
├── CONTRIBUTING.md
├── README.md

---

3.2 OpenAMR Mobile Platform: Hardware

Repository: openamr-platform-hw

openamr-platform-hw/
├── hardware/
│ ├── cad/
│ ├── drawings/
│ ├── bom/
│ ├── assembly/
│ └── revisions/
│
├── electronics/
│ ├── schematics/
│ ├── pcb/
│ ├── fabrication/
│ ├── bringup/
│ └── revisions/
│
├── firmware/
│ ├── common/
│ ├── platform_mcu/
│ └── variants/
│
├── manufacturing/
├── tools/
├── .gitattributes
├── CODEOWNERS
├── README.md

---

3.3 OpenAMH Humanoid: Software

Repository: openamh-humanoid-sw

openamh-humanoid-sw/
├── ros2/
│ ├── src/
│ │ ├── openamh_description
│ │ ├── openamh_bringup
│ │ ├── openamh_control
│ │ ├── openamh_drivers
│ │ ├── openamh_moveit
│ │ └── openamh_locomotion
│ │
│ ├── launch/
│ └── config/
│
├── sim/
│ ├── worlds/
│ ├── models/
│ └── launch/
│
├── tools/
├── CODEOWNERS
├── CONTRIBUTING.md
├── README.md

---

3.4 OpenAMH Humanoid – Hardware

Repository: openamh-humanoid-hw

openamh-humanoid-hw/
├── hardware/
│ ├── cad/
│ ├── drawings/
│ ├── bom/
│ ├── assembly/
│ └── revisions/
│
├── electronics/
│ ├── schematics/
│ ├── pcb/
│ ├── fabrication/
│ ├── bringup/
│ └── revisions/
│
├── firmware/
│ ├── common/
│ ├── joint_controllers/
│ ├── sensor_boards/
│ └── variants/
│
├── manufacturing/
├── tools/
├── .gitattributes
├── CODEOWNERS
├── README.md

---

4. Naming and Governance Rules

Repository naming:

• Shared repositories: openamrobot-*
• Mobile platform repositories: openamr-platform-*
• Humanoid repositories: openamh-humanoid-*

Mandatory folders:

• Software repositories: ros2/, sim/, tools/
• Hardware repositories: hardware/, electronics/, firmware/

Git LFS policy (hardware repositories only):

• CAD: .step, .stl, .iges
• EDA: .kicad_pcb, .kicad_sch
• Large PDFs and renders

---

5. Benefits

• Clear ownership boundaries
• No protocol or interface duplication
• Clean CI and automation paths
• Scales cleanly to new robot families
• Industry-grade open-source structure
• Ready for research, education, and commercial deployment