Distributed OSHW Framework (DOF)

  1. Simmons <jrs@mach30.org> :revnumber: v0.1.6 :revdate: 8/6/2021

Introduction

Mach 30 launched Open Design Engine (ODE) in 2012. Since then we have run our own OSHW projects on ODE, observed other groups host OSHW projects on ODE and other sites, and held numerous conversations on and offline about the nature of hosting OSHW projects. Our conclusion after all these years and experience is the same one we held back in 2012: the OSHW community is still searching for a project hosting solution that meets the needs of hardware projects (where documentation is part of the source code).

What has changed is our approach to addressing OSHW project hosting. This time we are starting with the development of a tool independent methodology for developing and sharing OSHW, the Distributed OSHW Framework (DOF). What do we mean by methodology?

The Distributed OSHW Framework will be a systematic approach identifying:

  • What needs to be shared

  • How it should be shared

  • The relationships between the various kinds of shared content

Note how developing a methodology is different from identifying best practices, covering case studies, and creating definitions. A methodology is something one follows; it is a fully defined process. And by targeting tool independence, we can aim for developing a solution that will stand the test of time, just as version control methods have lasted through cvs, svn, and now git.

The Pillars of the DOF

The Distributed OSHW Framework (DOF) is built upon 4 pillars. All design decisions for DOF are ultimately derived from one or more of these pillars.

1: OSHW Definition

OSHW projects should be developed and shared in accordance to the OSHW Definition.

2: OSHW Certification

OSHW projects should be developed and shared in accordance to the OSHW Certification process.

3: OSHW should be like OSS

Open Source Hardware should be like Open Source Software to the greatest degree possible (e.g. sharing, development, licensing).

4: OSHW Source Definition

The source of an OSHW project is its: Bill of Materials Data (list of components and counts covering all parts which must be purchased to build the project), Assembly Instructions (complete list of instructions to build the project from its purchased parts), and Supporting Documentation (e.g. design files, schematics, operating instructions)

Methodology Documentation

The methodology is being modeled in a series of YAML files under the architecture folder. A script is then used to generate this readme and the DOF architecture document (located in the dist folder). See the docs folder for material on the format of the architecture YAML files.

Please feel free to join the conversation by posting questions/comments as issues in the DOF repository.

Mach 30 Related Projects
Sources of Inspiration
  • Howstr - A project by Matthew Maier to capture how to capture, share, and discover tangible projects

Further Reading

Stakeholder Needs

The development of the Distributed OSHW Framework (DOF) is guided by a series of stakeholder needs, listed below.

Stakeholder Need 1: OSHW Definition

OSHW projects should be developed and shared in accordance to the OSHW Definition.

Stakeholder Need 2: OSHW Certification

OSHW projects should be developed and shared in accordance to the OSHW Certification process.

Stakeholder Need 3: OSHW should be like OSS

Open Source Hardware should be like Open Source Software to the greatest degree possible (e.g. sharing, development, licensing).

Stakeholder Need 4: OSHW Source Definition

The source of an OSHW project is its: Bill of Materials Data (list of components and counts covering all parts which must be purchased to build the project), Assembly Instructions (complete list of instructions to build the project from its purchased parts), and Supporting Documentation (e.g. design files, schematics, operating instructions)

User Stories

DOF’s stakeholder needs are then used to identify a series of user stories which then lead to design decisions captured in data structure and activity definitions.

User Story 1: Branch OSHW

As a OSHW Developer I want to use branches in the development of OSHW so that I can modify the project source in parallel lines of development.

Example: Creating a v1 branch to preserve and maintain v1 source as part of OSHW certification compliance. New development can then happen on trunk or a v2 branch.

User Story 2: Fork OSHW

As a OSHW Developer I want to fork OSHW projects so that I can modify the project source in my own epository.

Example: Forking a project to customize its design for my own purposes (e.g. swapping out a controller board, adjusting it to fit me).

User Story 3: Merge OSHW

As a OSHW Developer I want to merge project source so that I can integrate changes from a branch or fork into my current source.

Example: Incorporating suggested source changes from a contributor who forked the project to develop a new feature for the project.

User Story 4: Composition of OSHW

As a OSHW Developer I want to include external projects as elements of my project so that I can build upon previous engineering effort (my own or others’).

Example: Using an Arduino Uno as the controller board for an OSHW robot project.

Data Structures

This section covers each data structure type in the Distributed OSHW Framework (DOF).

Component

Purpose: Represents the smallest logical element in an OSHW project. A Component may be a project in its own right (with a sub-component hierarchy) or may be nested as a sub-component in the "source" of another component.

Component Template
name: {{name}}
version: {{version}}
description: {{description}}
license: {{license}}
author: {{author}}
dependencies: {{dependencies}}
components: {{components}}
parts: {{parts}}
functions: {{functions}}
tools: {{tools}}
precautions: {{precautions}}
assemblySteps: {{assemblySteps}}
Table 1. Component Specification
Field Type Item Type Description Source

name

string

Source representation of the component’s name. Format = single word, only lowercase letters, and may contain hyphens and underscores.

version

string

Version number of the component’s source. Format = x.x.x per semantic versioning guidelines.

description

string

Human readable representation of the component’s name. Typically used in rendered documentation referencing the component.

license

string

List of licenses used within the component’s source. Format = SPDX license expression.

author

string

Identifies author (e.g. owner of source intellectual property). Format (email and website are optional)= Author Name <email address> (website URL)

dependencies

dictionary

string

Per NPM/Yarn. Key = dependency name. Value = Semantic versioning version string.

components

dictionary

Component

Listing of sub-components directly owned by this component. Key = sub-component’s name. Value = sub-component’s data structure.

parts

dictionary

Component List Item

Listing of the component’s parts (and substitutions) defined as sub-components. Key = part’s id. Value = part’s key data.

functions

list

Function

Listing of component functions.

tools

dictionary

Component List Item

Listing of the required tools (and substitutions) defined as sub-components. Key = tool’s id. Value = tool’s key data.

precautions

list

string

Listing of caution statements (e.g. safety warnings) for the component.

assemblySteps

list

Activity Step

Sequence of steps required to assemble the component.

Component List Item

Purpose: Identifies a part or tool used in the fabrication of the component. Parts and tools are defined by their source material in the components list.

Component List Item Template
id: {{id}}
description: {{description}}
descriptionLong: {{descriptionLong}}
descriptionSelected: {{descriptionSelected}}
quantity: {{quantity}}
quantityUnits: {{quantityUnits}}
options: {{options}}
selectedOption: {{selectedOption}}
notes: {{notes}}
Table 2. Component List Item Specification
Field Type Item Type Description Source

id

string

Part’s ID (or part number). Format = single word, only lowercase letters, and may contain hyphens and underscores.

description

string

Human readable name for the part (not name of the selected component for this part).

descriptionLong

string

Computed value = "{{id}}:\ {{description}}". Used as shortcut in documentation.

descriptionSelected

string

Computed value = "{{id}}:\ {{description}} ({{selectedOption.description}} v{{selectedOption.version}})"

quantity

number

Defines how much of the item is required (whole number or real number depending on item)

quantityUnits

string

Unit of measure for the specified quantity. When specifiying units for whole components use "part".

options

list

string

List of component names defining available substitutions for the part or tool.

selectedOption

integer

Specifies the selected option from the list of component options.

notes

string

Developer comments on this part or tool.

Activity Step

Purpose: Defines a single step in an activity, e.g. assembly instructions.

Activity Step Template
summary: {{summary}}
requiredParts: {{requiredParts}}
requiredTools: {{requiredTools}}
details: |
  {{details}}
Table 3. Activity Step Specification
Field Type Item Type Description Source

summary

string

Brief overview of the step (optional if step includes details). Can be used as a heading in documentation rendered from the step.

requiredParts

list

string

Optional list of part IDs needed to complete this step.

requiredTools

list

string

Optional list of tool IDs needed to complete this step.

details

string

Multiline formatted text string defining the details of the step (optional if step includes summary). Format is up to user (e.g. list, ordered list, narrative text, some combination).

Parameter

Purpose: Defines a data structure for an input or output of a component function.

Parameter Template
name: {{name}}
description: {{description}}
type: {{type}}
units: {{units}}
defaultValue: {{defaultValue}}
constraints: {{constraints}}
Table 4. Parameter Specification
Field Type Item Type Description Source

name

string

Source representation of the parameter’s name. Format is C-style variable naming convention

description

string

Human readable representation of the parameter’s name. Typically used in rendered documentation referencing the parameter.

type

string

Parameter type, may be a base type (e.g. string, int) or a path to a Data Structure

units

string

Unit of measure for the specified quantity.

defaultValue

string

String representation of default parameter value.

constraints

list

string

Each item in the list defines a restriction of the values the parameter may store (e.g., ⇐ 10, enums = 3.14, 42, 1701).

Function

Purpose: Defines a data structure for a component function.

Function Template
name: {{name}}
description: {{description}}
inputs: {{inputs}}
outputs: {{outputs}}
Table 5. Function Specification
Field Type Item Type Description Source

name

string

Source representation of the function’s name. Format is C-style function declaration naming convention

description

string

Human readable representation of the function’s name. Typically used in rendered documentation referencing the function.

inputs

list

Parameter

Listing of acceptable input parameters by this function.

outputs

list

Parameter

Listing of expected output parameters from this function.