1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
title: skdb open source hardware specification
version: 0.0.0
maintainers:
- ben lipkowitz <fenn@users.sourceforge.net>
- bryan bishop <kanzure@gmail.com>
urls:
- http://gnusha.org/skdb/
copyright:
copyright 2011 ben lipkowitz. this document may be freely copied provided
it is not modified. if you wish to change the spec, please submit your
changes to the maintainer for inclusion.
todo:
- bills of materials (BOMs)
- CAD file formats
- QR codes
introduction:
this specification describes a valid skdb package.
skdb is a packaging system for hardware projects, based upon the idea of
automatically downloading all of the source information needed to produce a
particular artifact in the physical world.
"apt-get for hardware" refers to an analogy commonly employed to describe
skdb or the utility of packages.
definitions:
source file:
the preferred data format for modification. for example the python
script that generated an SVG file, or simply the SVG file if it was
created manually in a drawing program. most commonly, CAD.
package:
a collection of source files sufficient to reproduce a particular
artifact or collection of artifacts in the real world
artifact:
a physical device or substance created for a particular purpose, for
example a bolt, a laptop
project:
people, institutions, and existing body of work created to further some
specific set of goals. in this context, the project is typically
upstream developers who created the data in the package.
maintainer:
a software developer who ensures data and metadata completeness and
fidelity to original design intent, and compatibility between packages
unit:
an invariant representation of a particular objective measurement of an
artifact or naturally occurring phenomenon, for example a meter or a
radian
uncertainty:
the range of possible actual values for any given measurement, limited
by the precision and accuracy of the measuring equipment or
experimental setup
ontology:
a particular way of describing things, their characteristics, and their
relationships. a good ontology is consistent and unambiguous, and are
often hierarchical with no circular definitions. there may exist many
possible ontologies for describing the same thing, for example a cat
may be considered as either a mammal, a domestic parasite, or a
portable hand warmer.
dependency:
a reference to a required package necessary for the dependent package
to work
data format:
package:
a package consists of a git repository containing at minimum a metadata
file. other source files such as cad files, generator scripts, and
source data are recommended. generated files such as renderings,
stereolithography meshes, and toolpaths (g-code) may also be included,
but not without the source files and instructions to re-generate them.
package names:
- a package name must contain only upper and lower case letters, numbers,
and the dash ("-") character.
- a package name must be unique by not being in use by another package
yaml files:
- yaml files shall be written in valid yaml 1.2 format (see
http://www.yaml.org/spec ). yaml data should generally be in fully
expanded (indentation-based) flow style unless the folded (explicit
delimiter json-style) flow style significantly improves readability.
- use a consistent style and ordering when making changes to yaml files
so that diffs show only the relevant change. do not overwrite
existing hand-written yaml files with computer generated yaml unless
making significant changes to the structure of the data. if you have
an overwhelming urge to reformat the file, do so in a separate commit
without making any other changes to the data.
- do not use tab characters.
- use unix style line endings.
- try to stick to a maximum of 80 columns text width.
- when in doubt, use the same formatting style as the rest of the file.
- data in yaml files is intended to be loaded directly into objects in
one step, with data descriptor tags causing the resulting object to be
cast as one type or another. ideally there will be no post-processing
required after loading the yaml file, given that all of the data types
are defined in the context used to load the yaml file,which is
normally python. data types may (and should) be defined in external
source code files. however, one goal is to be able to process metadata
files without downloading the complete contents of each package, so
tags which are defined by code in that package should include a tab
description section at the beginning of the metadata file which looks
like '
!!python/object:skdb.tag_hack
tags:
- "!your_data_type"
- "!your_other_data_type"
---
'
this is likely to change when we find a better way to do it.
metadata:
required:
- metadata files shall be named "metadata.yaml"
- package data begins with the "!package" tag and has the following
fields
- maintainer: package maintainer name and contact info, in IETF RFC 2822
name-addr format, like 'Bryan Bishop <kanzure@gmail.com>'
- license: package license. this license applies to all files in the
package not otherwise labeled. if particular files in the package
have a different license, it should be noted in the files section.
- licenses shall be a string consisting of one of the following:
- a creative commons short license name ("CC-BY-SA-3.0") from the
list of choices at http://creativecommons.org/licenses/ i
strongly encourage you not to use any of the "non-commercial"
flavored licenses because of their ambiguity
- a gnu short license name ("GPLv3") from
http://www.gnu.org/licenses/
- "other" and include the text of the license in the file named
"LICENSE"
- if a license string ends with the "+" (plus) character, it will
be taken to mean "or any later version of the same license".
- urls: a list of urls pointing to more information about the artifact
- name: package name, which should be the same as the name of the git
repository (sans ".git") and containing working directory.
- created: date created in ISO 8601 "yyyy-mm-dd" date format
("hh:mm:ssZ" UTC time optional)
- version: version number of the package, in major.minor.bugfix
notation. after backwards-incompatible changes the major version
number must be incremented.
- short description: a concise single-line description of the project
up to 140 characters in length.
- description: a short (one or two paragraph) description of the
project. the first line can be the value of 'short description'.
- classes: lists of data types the package makes use of, as a mapping
with the key corresponding to the name of the package which defines
those data types.
' threads:
- Thread'
in this case we need the package 'threads' to define the 'Thread' data
type.
- dependencies:
- software: a list of other packages this package needs in order to
function.
- files: a list of files in the package
optional:
- updated: date last modified in ISO 8601 date format, UTC time
note that if this field exists, it is mandatory to set it to the
current time after modifying any of the package contents. this is
best accomplished with post-commit hooks.
- dependencies:
- build: a tree of possible sets of processes and packages used in
the manufacturing of the artifact, not including the manufacture
of any components which are included from other packages. for a
complex end product made from off the sheft components, this will
be mostly assembly processes like press fit or fastening. the
format of this will likely change.
- use: a tree of possible sets of processes and packages required
for using the artifact. more on this later.
- template:
if a package contains data for a family of parts, it is helpful to
describe the general form of the interfaces for a given part. is it
a mechanical part? an electrical connector? if the units match up
properly, there is a chance that the part does what you want and it
worth downloading for a look. to support this functionality, a
template part with the same set of interfaces as any given part in
the family is provided in the metadata file.
external:
- size: the size of the package (including the metadata file)
- md5sum: the md5 sum of the package tarball
- latest: the sha1 latest commit hash
|
