Code Docs

How to Layout your Ark Project

These are some best practice tips to keep your ark projects clean, shareable and understandable for all users:

YourArkProject/
│
├── robots/                     # Source code or SDKs for all robots used (e.g., Franka, Unitree, etc.)
│   └── ...                     # Each robot has its own folder or repository
│
├── sensors/                    # Source code or SDKs for all sensors used (e.g., RealSense, LiDAR)
│   └── ...                     # Each sensor has its own folder or repository
│
├── other/                      # other files such as URDFs of objects
│   └── ...                     # Each object should have its own folder for meshes and urdf
│
├── config/                     # All configuration files (organized by type)
│   ├── robots/                 # Robot-specific configuration files (e.g., joint limits, URDF paths)
│   │   └── ...
│   ├── sensors/                # Sensor-specific configuration files (e.g., calibration, topics)
│   │   └── ...
│   ├── objects/                # Object definitions used in the simulation or real world
│   │   └── ...
│   │		other/                  # Other condes configuration files
│   │   └── ...
│   └── global_config.yaml      # Global configuration file linking the setup (robot + sensor + environment)
│
├── scripts/                    # Utility scripts (non-node code, e.g., data converters, analysis tools)
│   └── ...
│
├── nodes/                      # All runtime Ark nodes (e.g., controller, perception, planner)
│   └── ...                     # Each node is a separate file or module
│
├── launch/                     # Launch files for different system configurations
│   ├── sim.yaml                # Launch configuration for simulation
│   └── real.yaml               # Launch configuration for real robot setup
│
└── README.md                   # Project overview and setup instructions

Top-Level Project Structure

• Consistency: All folder names use lowercase with underscores (snake_case) to improve readability and avoid OS-specific casing issues.
• Modularity: Separation of hardware code, configuration, runtime nodes, and utilities allows easy reuse and clarity.
• Scalability: The layout supports adding multiple robots, sensors, and environments as the system grows.

robots/

• Purpose: Stores source code or SDKs specific to each robot platform (e.g., control APIs, low-level drivers).
• Design Choice: Keeps hardware-specific dependencies isolated from the core system logic.
• Modular: Each robot can be version-controlled or developed independently.

sensors/

• Purpose: Contains codebases or APIs for sensors (e.g., cameras, LiDARs, force sensors).
• Design Choice: Mirrors the robot structure to promote consistency.
• Separation: Prevents sensor code from cluttering simulation or logic layers.

config/

• Purpose: Centralized location for all configuration files (robot, sensor, object, environment).
• Structured Subfolders:
  • robots/: Stores URDF paths, PID parameters, control limits.
  • sensors/: Stores calibration data, topics, and transform offsets.
  • objects/: Contains object descriptions for use in sim and real-world.
• global_config.yaml: Unifies the above into a master file loaded by all nodes.
• Design Choice: Encourages declarative setups for easy switching between configurations.

scripts/

• Purpose: Contains helper tools not run as Ark nodes (e.g., dataset converters, visualizers).
• Design Choice: Keeps auxiliary code separate from runtime infrastructure.
• Examples: extract_images.py, merge_logs.py, label_tool.py.

nodes/

• Purpose: Contains the core Ark nodes responsible for control, perception, planning, etc.
• Design Choice: Flat structure or subfolders based on node type for clarity (e.g., perception/, control/).
• Consistency: All nodes inherit from a common base and register automatically with the Ark registry.

launch/

• Purpose: Launch configurations to start the system in either simulation or real-world mode.
• Files:
  • sim.yaml: Loads a simulated robot, sensors, and scene.
  • real.yaml: Initializes real robot and sensor interfaces.
• Design Choice: Clearly separates test and deployment modes for reproducibility and safety.

<aside> ℹ️

Note: This layout is a suggestion but may not work for all projects and setups, so feel free to make modification on a per-project-basis

</aside>

Table of Contents