OSH Documentation Standard for Fab City OS

Reasoning

The Design Passport needs a definition/standard for OSH documentation.

Requirements

1. Entails everything needed in order to manufacture the product.
2. Is structured in a way that the design passport can reference it.
3. Can be displayed as a product in an E-Commerce Store.

assigned to @mikelovic

@mikelovic , @pieterhijma , @hoijui : could you improve this issue?

changed the description

assigned to @pieterhijma and unassigned @mikelovic

changed the description

mentioned in issue #20 (closed)

changed the description

from pieter hiejma: " we have to define a set of assumptions, also in relation with req 2: how can the design passport reference it The kickoff meeting discussion with Andrea and Adam was very useful for my understanding: I think we can assume a git repository, structured in a way that satisfies whatever we decide on req 1. We can reference a specific commit and Andrea and Adam suggested that each commit will be signed by the designer to make sure that each contribution on the design is counted. This raises the questions how we should sign these contributions, do we want PGP or does FabCityOS provide a way to sign and resolve identities. I guess so. Req 3 is easy: we just decide that the repo has a picture. "

changed the description

marked this issue as related to #20 (closed)

I propose (for version 0.1) because we don't have a fully documented openlab starterkit repo yet:

req 1: Choose a standard, such as OKH or the DIN spec, or use an existing well documented repo For later versions, we have to discuss with Daniele and Mohammed (can someone invite them into software/ so I can reference them?)

req 2: Discuss with @Adam-Dyne and Andrea and @jaromil how the design passport will reference it. Probably the easiest is to rely on a git repo and track commits. Indeed identity and how commits are assigned needs to be resolved. Perhaps interesting to present the problem of attaching value to a commit on a design to Lynn and/or Bob in the main group. (As an example, what is the value of a commit that changes a typo vs. one that give a new fancy feature).

req 3: No problem at all, we simply define that it requires (a set of) picture(s).

Version 0.1 is here https://gitlab.fabcity.hamburg/software/wp4-os-tools/task-1-automated-documentation/oshd-standard/-/blob/main/OSHD%20for%20FCOS%20standard%200.1.md Please continue discussion there

Since we don't have a fully documented openlab starterkit example yet, I propose to use (for version 0.1) the repo LibreSolar from @mikelovic as a blueprint for the standard of OSH documentation.

changed title from Draft OSH Documentation Standard for Fab City OS 0.1 to OSH Documentation Standard for Fab City OS 0.1

added Digital Federated Network Manufacturing Interface labels

added Fab City Software Kit + 1 deleted label

marked this issue as related to #26 (closed)

changed title from OSH Documentation Standard for Fab City OS 0.1 to OSH Documentation Standard for Fab City OS

Hi @andrea_dintino, This is a discussion about hardware documentation in Fab City OS. Benedikt moved it to a new repo as per #19 (comment 894).

For completeness, this is the repo he is referring to: OSHD Standard for FCOS

@benedikt @pieterhijma regarding req.2: the absolute easiest for us is that the info you want in the product passport are provided as a JSON file. The JSON in turn can contain a bunch of data in it (such as author, license, date, preferredManufacturingProcess, preferredManufacturingMaterial, etc) as well as one ore more links to the repo (down to the specific commit) or the license. One good way to work on this is start drafting a JSON file and start a discussion around it.

Reg. signatures: we can do them in Zenroom, in various shapes and forms. Reg. resolving: I'm not sure what you mean? I imagine that if you're looking for design "12345" from "John Doe", there will be an API returning that, and the same API can also show you the product passport along with the relevat blockchain entries for it.

@andrea_dintino, In my comment I talk about "identity and how commits are assigned needs to be resolved". I mean with that the problem of identity in the federated system and matching this identity with the commits of an open source hardware (or software) git repo. I'm reacting to point 2 of the README as Benedikt formulated it: The requirement that the design passport is structured in a way that it can reference the OSH documentation.

Potentially OSH has many contributors all over the world. Using a specific design tracked with a design passport should allow contributors to be compensated in some way. There are various problems with this. How can we assign specific contributions to a person, what is the federated identity of this person. Can we match the federated identify of this person with specific commits. Other problems are: how do we value these contributions and how do we divide the compensation among the contributors.

Regarding that file: Could that be the RDF version of an OKH file, serialized in the JSON-LD (RDF) format? @andrea_dintino

@hoijui yes, JSON-LD could be an option. We're using JSON-LD in our W3C-VC signature (you can see it in apiroom.net under "examples", towards the end of the list).

Not familiar with OKH and RDF, it seems to me OKH is stored as YAML, if that's the case a conversion to JSON is trivial (we may be able to implement it in Restroom-mw ).

The best would be to provide us the draft of a sample file, to start looking at it.

ahh great! :-) I had a short look at the VC example but.. I am not at all into zenroom and.. I mean.. don't want to get into it right now (also time wise), but if it works, great! :-)

Yes, the "old"/current OKH (v1.0.0) is a YAML manifest-file in the repo, but the new/next OKH (LOSHv1) uses TOML manifest files in the project repo, but On the crawler/DB side we translate it into RDF, which we consider to be the actual data that everyone should consume.

@hoijui update: JSON-LD is fine as long as it's precomposed, cause Zenroom can not process a stream of input but only a file. Generally speaking, any JSON is fine for us to work with.

OKH as it is now, surely misses some things, but I am part of the .. mainly two man team working on it, and even if something is not yet in the standard, we could define it in our own sub-standard for Fab City OS (as in: additional fields), without violating the standard.

@lynnfoster and @bhaugen This is one of the issues where we discuss OSH documentation in relation to FabCity OS. This is another issue where we discuss this: https://gitlab.fabcity.hamburg/software/wp4-os-tools/task-1-automated-documentation/oshd-standard/-/issues/3. In today's meeting I promised to provide background info on open source hardware, I will do that in this issue: https://gitlab.fabcity.hamburg/software/wp4-os-tools/task-1-automated-documentation/oshd-standard/-/issues/5

For anyone interested, I created a file background-osh.md with some interesting background information on OSH. This is in the other repo: https://gitlab.fabcity.hamburg/software/wp4-os-tools/task-1-automated-documentation/oshd-standard

added Epic label