Contribution Manual

From ROP
(Difference between revisions)
Jump to: navigation, search
(Hosting Design Files)
(Hosting Design Files)
Line 105: Line 105:
 
== Hosting Design Files ==
 
== Hosting Design Files ==
  
It is highly recommended to host your design files on the ROP repository. Please [http://www.roboticopenplatform.org/contact contact the ROP webmaster] for an account. The ROP repository is running \href{http://subversion.apache.org/}{Apache Subversion}, so you will be asked to install a client. In the case yuor design files are hosted elsewhere it is in any case highly recommended to use a version-controlled repository.
+
It is highly recommended to host your design files on the ROP repository. Please [http://www.roboticopenplatform.org/contact contact the ROP webmaster] for an account. The ROP repository is running [http://subversion.apache.org/ Apache Subversion], so you will be asked to install a client. In the case yuor design files are hosted elsewhere it is in any case highly recommended to use a version-controlled repository.
  
 
Especially in hosting your design files it is of importance to have them properly structured and arranged into subfolders. The following directory tree is recommended:
 
Especially in hosting your design files it is of importance to have them properly structured and arranged into subfolders. The following directory tree is recommended:

Revision as of 14:38, 16 March 2014

Contents


Introduction

This manual was written with the purpose of facilitating the contribution process to ROP. ROP was launched to become a central place for the exchange of robotic hardware designs through embedded wiki pages. Comparable to open source software, companies and research institutions can release their robot hardware design on ROP under an open hardware license. The essence of sharing open-source hardware is sharing the design files, but there are many other hardware design-related files that can decrease the development efforts required to build a robot. Please note that you are not required to post all files discussed below, but the more you contribute, the faster your design will be adopted by the community. The contents of this document are mainly based on a work of the Open Source Hardware Association (OSHWA) on the best practices for sharing open-source hardware.

Preparing the contribution of your project

For the sake of a neat and tidy wiki, you are encouraged to prepare as much information as possible before posting to the wiki, and uploading as much as possible at once. The following section gives a guideline for some of the files and descriptions you should consider sharing on ROP. For your convenience a checklist for the possible elements of a robotics project is included.

Elements of a ROP contribution

This section describes some of the files you should consider sharing when publishing your project on ROP.

Summary

The project description should include a brief summary describing the robot's identity and purpose. Furthermore please provide hyperlinks to:

  • Author: the author's website
  • License: the license your project is published under
  • Hardware: the hardware repository
  • Software: the software respository

Overview

Figure 1: PBS example

The project description should include a clear description of the robot functionality and an overview of the robot layout. A component hierarchy or product breakdown structure is also very beneficial for the comprehensibility of the robot structure, see Figure 1 for an example.

Specifications

A list of specifications should be included with the project description, preferably partitioned in accordance with the robot component division. The specifications can include, but are not limited to:

  • Construction: Overall dimensions, weight etc.
  • Electrical: Batteries, motors etc.
  • Computers and processors used etc.
  • Communication: Network technology used etc.
  • Sensors: E.g. audio or vision components
  • Software: Operating system etc.
  • Degrees of Freedom: DOFs of respective components

Design Files

Sharing the original design files is the core practice of open-source hardware development. This is important because the original design files constitute the source code for the hardware. To maximize the ability of others to view and edit the source files, it is recommended to use free open-source software to create the original designs. All design files should be version controlled.

In addition to the original design files, it is often helpful to share your design in additional, more accessible and commonly used interchange and export formats. Moreover it can also be helpful to share ready-to-view outputs that can easily be viewed by end users such as a PDF of a technical drawing or a 3D viewer of the robot design.

Examples of design files you should consider including are:

  • 3D CAD designs
    • Assemblies and parts
    • 3D designs ready for e.g. 3D printing, molding etc.
    • Component libraries e.g. fastener libaries
    • Formats: native, STEP, STL
  • 2D CAD drawings
    • 2D designs ready for e.g. laser cutting
    • Formats: native, DXF, SVG, PDF
  • Circuit board CAD files
    • Electrical schemes
    • PCB layouts
    • Formats: native, PDF
  • Electrical wiring
    • Cable layouts, connector pinouts etc.
    • Formats: native, PDF
  • Technical drawings
    • Engineering drawings showing dimensions and tolerances
    • Exploded views
    • Formats: native, PDF
  • Machining code
    • Code for machining a part
    • Formats: e.g. G-code, STEP-NC, STL

Bill of Materials

Figure 1: PBS example

It is very important to provide a separate Bill of Materials (BOM) in addition to the design files for the community to easily reproduce your robot design. The BOM - see Figure 2 - is a list of the assemblies, components and parts needed to build the robot. Include as much useful infomation as possible, such as:

  • Item number (in robot component hierarchy)
  • Short part description
  • Quantity
  • Supplier and part number
  • Costs
  • Raw materials (if to be manufactured)

Make sure that it is easy to tell which item in the bill of materials corresponds to which component in your design files. It would be wise to name e.g. the CAD files in accordance with the BOM item numbers and descriptions. Furthermore try to build up the BOM according to the component hierarchy and to include diagrams indicating which part goes where, all for the sake of clarity.

Software and Firmware

Any software or firmware code required to operate your robot should be shared so the community can modify it along with their hardware modifications. Proper documentation of the code significantly improves the probability that your code will be adapted and further developed by the community, so please include as much and clear as possible documentation. It would also be helpful to provide information on the the stability and robustness of the software.

Instructions and Documentation

Photos

Including photos of your robotic project helps people to understand what your project is. Try to include photos of the overall robot and details from multiple viewpoints and at various stages of assembly to facilitate those striving to reproduce the robot.

Publishing on ROP

Registering

Wiki Style Guide

Once your account has been activated you can create pages on the wiki. To ensure a consistent style and layout throughout the wiki, you are asked to follow a style guide, which can be found here.

Hosting Design Files

It is highly recommended to host your design files on the ROP repository. Please contact the ROP webmaster for an account. The ROP repository is running Apache Subversion, so you will be asked to install a client. In the case yuor design files are hosted elsewhere it is in any case highly recommended to use a version-controlled repository.

Especially in hosting your design files it is of importance to have them properly structured and arranged into subfolders. The following directory tree is recommended:

  • Bill Of Materials
  • Electrical Designs
    • Circuit Boards
      • Schemes
        • <<Native Format>>
        • PDF
      • PCB Layouts
        • <<Native Format>>
        • PDF
    • Wiring Schemes
      • <<Native Format>>
      • PDF
  • Instructions
    • Assembly Instructions
    • Manufacturing Instructions
    • User Manuals
  • License
  • Mechanical Designs
    • 3D CAD Models
      • <<Native Format>>
      • STEP
    • Technical Drawings
      • <<Native Format>>
      • PDF
    • Manufacturing Files
      • 2D Cuttable Files
        • <<Native Format>>
        • PDF
      • 3D Printable Files
        • <<Native Format>>
        • STL
    • Machining Code
  • Photos
    • Parts
    • Assembled
  • Software
    • Code
    • Documentation

Licensing

Checklist

Personal tools
Namespaces
Variants
Actions