Skip to content

Latest commit

 

History

History
136 lines (108 loc) · 8.74 KB

dof-methodology.adoc

File metadata and controls

136 lines (108 loc) · 8.74 KB
Raw

DOF Methodology

First Principles

  1. OSHW should be developed in a manner like OSS

  2. The basic building block of OSHW is a component

  3. Components may be hardware or software

  4. All components must be built by someone

  5. Components may be built and acquired from a third party (designated COTS components) or built from source by the developer using them (designated as assemblies)

  6. COTS components may be open or closed source, as they are built by a third party (e.g. Aduinos are often included as open source COTS components)

  7. Assembly components must be open source, as they are built by the developer of an open source project

  8. Software components include firmware and applications (applications may run on or communicate with the OSHW project)

  9. An OSHW project depends on its components, both its COTS and Assembly components

  10. All components of an OSHW project are listed in its Bill of Materials (BoM)

  11. BoMs only define the components of the current project scope; Assembly components have their own independent BoMs

  12. OSHW (and OSS) projects must include build instructions as part of their "source"; in other words, a BoM or a collection of files with code is not sufficient to define an open source project

  13. Components may be built from other components and raw materials

  14. Raw materials must be measured and separated from their bulk supply (in some processes the act of measuring includes separation as a side effect, e.g. cooking; in other processes these are distinct steps, e.g. carpentry)

  15. Components and raw materials may be defined locally (in current project scope) or externally in their own repo (dependencies)

Derived Assumptions

  1. OSHW projects should support fork, branch, merge, and tag operations

  2. OSHW projects (like modern OSS projects) should be composable at the component level

  3. OSHW should use "packages" (think npm packages in Nodejs, gems in Ruby, and pipy modules in Python) as the unit of composition for hardware and software components

  4. A package should include

    1. BoM data

    2. Build instructions

    3. Digital design files for this package (e.g. cad files, code files)

    4. List of dependencies (hardware/software, COTS/Assemblies), if any are required

    5. List of locally defined components, if any are defined

  5. A package should support all activities related to building the project up to and including the item defined in the package. Examples include

    1. Generating BoMs for the package and its dependencies as needed

    2. Generating a purchase list to build the project defined in this package

    3. Generating build instructions for the project defined in this package (including any dependent build instructions)

  6. Therefore, every OSHW project is itself a package

  7. BoMs are generated artifacts built from package level BoM data and information from packages included as dependencies

  8. Therefore, if a component is listed in BoM data, it must have already been included as a dependency

  9. BoM data consists of

    1. Component ID - package level identifier for this component, used throughout the pacakge source to reference this component, allowing for consistent references in the event of changes to selected alternate part number

    2. Options List - list of verified/allowed/approved source IDs for component implementation (e.g. COTS options, sub-assembly); IDs correspond to ID in dependency list for this package or in the list of locally defined components (if there is a name collision between the two sources, then the locally defined component is used, this should throw a warning to the user though)

    3. Default Option Index - identifies which entry in the Options List is selected by default

    4. Quantity - number of copies of this component required to build this package, requires a unit of measure (e.g. items for a typical hardware component, physical unit for materials sold by length, weight, mass, or seat/install for software components)

    5. Name - a short, human readable descripion suitable for inclusion in documentation

    6. Notes - developer comments on this component

  10. Examples of calculated and derived information in BoM

    1. project part numbers

    2. vendor part number

    3. component type (COTS vs Assembly)

  11. Specific formats for generated BoMs are left to the discretion of DOF implementations

  12. DOF uses component data to determine type of component (COTS vs Assembly, hardware vs software) this section needs to be reworked

    1. If BoM data is present component is hardware, otherwise it is software

    2. If manufacturer data is present component is COTS, otherwise it is an Assembly

The Methodology

This methodology covers the process of documenting and sharing OSHW projects, it does not cover the art and science of design. Clearly, each decision discussed below is the result of the hard work of the developer(s) contributing to the project.

Developing Projects

All of this needs to be reworked.

Starting a Project

  1. Create directory for new project source

  2. Initialize a new package for this project in the project directory; package description must include

    1. Project name - used to identify project when included as a dependency and to reference the project in documentation source

    2. Project version - used to identify project when included as a dependency and to reference the project in documentation source

    3. Project description - short description, used to give human readable name in BoM, instructions, etc

    4. Project license - specifying a license should be considered a best practice for OSHW projects, so DOF should expect a license as part of the minimum spec for a package.

  3. Create new repository for the project

  4. Commit project directory to repository

Adding a Component to a Project

  1. If new component, follow steps for Starting a Project

  2. Add component to dependency list by its ID data

  3. Download required source for new component into dependency data (likely a folder)

  4. Add component data to BoM (id, options data, quantity, etc)

Note
 Required digital design files should be stored under a source directory in the package they belong to.
Tip
 Commit materials to repositories frequently to ensure data is available to other contributors and other projects.
Note
 Package management tools used with DOF need to include the concept of updating dependencies when new versions are released.

Generating BoMs

While BoMs are scoped at the level of the current package, it is helpful to produce a single document containing the collection of BoMs included within the project hierarchy. So, we will first discuss generating the current scope BoM and then the collection of BoMs.

Generating BoM for Current Package

Uses

  • BoM data

  • Dependency data

  • List of locally defined components

    1. Select initial part number and part number format (critical when generating overall project level part numbers)

    2. Iterate over BoM data, for each component

      1. Generate part number

      2. Select specific component source from Options List for any components with more than one option

      3. Read in component information from package for selected component source (recall locally defined components take precedence over dependencies with the same ID)

      4. Combine package level info with BoM data and other calculated values to create an entry in the BoM

    3. Write out human readable version of BoM

    4. Save a cache of full calculated/derived BoM information for use in other source materials (e.g. purchase list, build instuctions)

Generating Project BoM Collection

Uses

  • Dependency Lists

  • BoM data from packages in dependency heirarchy

    1. Generate a full project dependency list by walking the dependency graph defined by the project’s BoM data and dependency lists at all levels of the project heirarchy

    2. Create a new empty document

    3. Select part numbering scheme (e.g. per package part numbering or overall project level numbering) and part number format

    4. REWORK - not all dependencies are used, so select based on BoM data Create a new section for each package in the dependency list with BoM data (typically Hardware Assemblies), and use the package BoM data to generate its BoM in this section per above

Generating Purchase List

Uses

  • Dependency Lists

  • Generated BoM information from Project BoM collection

TODO

Note
 The purchase list only convers the full list of COTS components and their quanities. Vendor selection, cost calculations, etc are beyond the scope of DOF itself as their are countless methods that could be used to make vendor level choices. But, DOF purchase list data should support generating actual order lists. Implememtations may choose whether to provide a limited set of methods or a plug-in infrastructure to give users the ability to customize the purchasing process.

Generating Build Instructions

Uses

  • List of required components

  • Pacakges from dependencies

TODO