Contribution Manual

From ROP
Revision as of 14:30, 16 March 2014 by Tmhafkamp (Talk | contribs)
Jump to: navigation, search

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

Overview

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 many 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

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

Checklist

Personal tools
Namespaces
Variants
Actions