Distributed OSHW Framework (DOF)

Unresolved directive in DOF.adoc - include::../README.adoc[]

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.	Creating a package.json file
version	string		Version number of the component’s source. Format = x.x.x per semantic versioning guidelines.	Creating a package.json file About semantic versioning
description	string		Human readable representation of the component’s name. Typically used in rendered documentation referencing the component.	Creating a package.json file
license	string		List of licenses used within the component’s source. Format = SPDX license expression.	Using SPDX License List "short identifiers” in source files
author	string		Identifies author (e.g. owner of source intellectual property). Format (email and website are optional)= Author Name <email address> (website URL)	Creating a package.json file
dependencies	dictionary	string	Per NPM/Yarn. Key = dependency name. Value = Semantic versioning version string.	Creating a package.json file
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}}
interfaces: {{interfaces}}

Table 2. Component List Item Specification
Field	Type	Item Type	Description
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.
interfaces	dictionary	3-DataStructures/6-InterfaceListItem.yaml'	Listing of interfaces for the part or tool. Key = interface’s id. Value = interface’s key data.

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

Interface List Item

Purpose: Identifies an interface on a part or tool.

Interface List Item Template

id: {{id}}
description: {{description}}
descriptionLong: {{descriptionLong}}

Table 6. Interface List Item Specification
Field	Type	Description
id	string	Inteface’s ID. Format = single word, only lowercase letters, and may contain hyphens and underscores.
description	string	Human readable name for the interface.
descriptionLong	string	Computed value = "{{id}}:\ {{description}}". Used as shortcut in documentation.