Fwd: open hardware documentation survey
Bryan Bishop
From: Matt Maier <blueb...@gmail.com>
Date: Thu, Mar 21, 2013 at 7:01 PM
Subject: [Discuss] open hardware documentation survey
To: The Open Source Hardware Association Discussion List <dis...@lists.oshwa.org>
Hey guys,
I'm really looking forward to attending the documentation jam. In my humble opinion documentation is exactly the discussion that the community needs to be having right now.
In fact, I was already working towards that (great minds think alike). This is the website I just launched (beta) to attempt to move towards fulfilling the idea of a "Github for hardware."
www.wareium.com
To summarize, the way I see it we need a schema for tying together different files and information that define projects. That will probably get complicated so we'll also need a software engine to put a GUI between the user and the schema.
By way of a requirements analysis for those the schema, the engine, and wareium, I've put together a survey to be sent out to the whole community. It doesn't have a name yet. I'm leaning towards The Open Hardware Toolbox Survey, or something along those lines.
https://docs.google.com/forms/d/1nwxZryqUvI4OHU-Zd-vUrbJLqFtRJmxa-SnH1sNkrSM/viewform
I would like to get your input on the draft version of the survey itself as well as any ideas regarding a good, clear name for the survey. The results will be particularly useful with the document jam coming up soon.
Thanks for your time and attention,
Matthew Maier
_______________________________________________
discuss mailing list
dis...@lists.oshwa.org
http://lists.oshwa.org/listinfo/discuss
--
- Bryan
http://heybryan.org/
1 512 203 0507
Bryan Bishop
Amazing that seemingly all attempts at standardization efforts these days start with "so I just started a NEW website" (with some funky domain/URL no one will remember)...
There have been so many "github for hardware" attempts that it's really funny at this point. Most of them don't even support git support. Some of them decided to just use github's api. Others have just had marketing pages. Most of the proposals are ignored by (nearly) everyone and never reviewed.
Matt Maier
cheers,
John Griessen
> Can you suggest why they failed
that is free-and-open. Google sketchup gets attention, but mostly
because Google is big, rather than that sketchup is good. Sketchup
is just a vendor lock in app like Autocad, with a seemingly zero
dollar price.
But what about when it goes away? I'm hoping GPL freecad http://free-cad.sourceforge.net/
will evolve enough to be used. GPL OpenSCAD is looking good to me, but would send most
windows users reeling and snickering that is "Has no GUI!, Hah!".
So, how do you get a standard adopted with no advertising or compelling reason to use it?
Not sure...
Matthias Bock
John Griessen
> I am very much missing an open repository for the development of hardware,
> for electrical schematics as well as for mechanical plans, for collaborative working, design of construction manuals and so on.
> I don't have a lot of time, but I would be ready to contribute to it with programming if necessary.
> The gEDA-js project may be of interest in this context (javascript schematics design):
> https://github.com/matthiasbock/gEDA-js
and aim for something widely appealing, since a repository with purpose of disseminating
is by definition about inclusion broadly. Single people can get loads done. I think the reaction
of "yet another repository attempt" was just critical conclusion they didn't go far enough,
that they hadn't actually done much hardware or wetware design to know what was needed.
Someone will innovate something good soon. And it won't look like the docs for break out boards...
instead it will be the data you need to quickly decide feasibility and then go build things.
I'm busy, but will give your gEDA-js a look. I use gEDA tools for design with a project directory
method of making the work sharable. A good thing to look at may be the frameworks for provisioning
web servers -- puppet, chef, salt. They have the concept that running a kind of checklist again and again
with incremental changes keeps the setup up to date. Like makefiles, but in ruby or python language.
And they deal with keys and encryption and web site certs out of the box. The list of dependencies
to get to a web-site/web-app method of sharing OSHW and open wetware could become long, but the list
of data types is long too, so that might be necessary.
Catarina Mota
Bryan Bishop
> In order for a repository project to be successfull, a group of people -
> with equal rights
> to decide what to do, should be organized. Only this way, users can be sure
commercial product, but just a small package manager that actually
manages packages. Maybe something based on opkg. If you want something
made by committee, just stick with ISO 10303 (which, for whatever
reason, nobody seems to know about... wtf).
Matt Maier
The problem is that we don't know what we need.
That's where the committee comes in. We need to get some stakeholders into a room and hash out a mutually agreeable prioritization of requirements. There is little point in discussing specific "hows" until we have some consensus on "what."
For example, the STEP file format is indeed a standard for exchanging product information, but it's copyrighted and has a massive amount of overhead. I doubt even OSE is doing any project big enough to justify that much complexity. A giant, complicated format like STEP could obviously describe simple projects, but it would also create a huge barrier to entry due to all of the complexity that is only there for complex projects. Since most open hardware projects are simple, or at least striving for simplicity, STEP might be kind of like hiring a marching band to follow you around and play a song when you get a new text message.
Or maybe the complexity is worthwhile, or doesn't matter, and my personal impression of the situation is inaccurate. The best way to find out is to compare it to a bunch of other people's impressions so we can come up with a generally applicable solution, not just a solution to my specific problem.
At any rate, the discussion has to happen before any implementation makes sense.
Catarina Mota
Bryan Bishop
<a.malcol...@gmail.com> wrote:
> Bryan, if I organize a Google Hangout for it, will you put together a short
> presentation on ISO 10303 and do a Q&A for us on what it is, what it says,
> and why it matters?
I would be happy to speak with you about existing standards and
on-going progress in open source hardware file formats/packaging,
either over email, irc, voip, phone, or in person.
I am curious as to what outcomes you are expecting from that sort of
conversation. In particular, it strikes me as odd that you would ask
why these things matter-- you run into them constantly if you do any
hardware development (it's seriously hard to find a commercial CAD
tool that doesn't support STEP), and in the software world there's a
tremendous amount of standardization on packaging formats, which has
led to hundreds of thousands of standard 'components' (which you will
find on most computers).
These are the common elements that have lead to all of the different
efforts on "github for hardware" or "open source hardware packaging"
projects. These are not projects by committees*, but rather
individuals that look at what tools they need, and then they write
them (* excluding ISO's work in this area, which is very much a
committee). I think in some cases this has been successful, like
thingdoc, which successfully solves a small piece of the puzzle, but
needs all the other tools everyone keeps talking about.
So.. are you expecting to be able to go home and use some existing
packaging solutions? or contribute to them and fix bugs (or whatever)?
Are you looking for advice on making this sort of software?
I think that for ISO-10303-specific information, the best person for
you to talk with would be Charlie Stix, who replied earlier in a
recent thread, or maybe Mark Pictor when he isn't busy on SCL... As
for other hardware packaging attempts from the open source world, I
would be happy to talk with you about those, but I am unwilling to
prepare a presentation for a "Hangout".
> At any rate, the discussion has to happen before any implementation makes
> sense.
(or no) discussion, and yet it makes a lot of sense and works pretty
well for its intended purpose, and is a positive contribution to
packaging within that area of the open source hardware community..
Bryan Bishop
> you to talk with would be Charlie Stix, who replied earlier in a
instead Charlie Stirk..
Bryan Bishop
Maybe I see where our misunderstanding happened.
What I wrote to Matt was a direct response to his
"design-by-committee" suggestion. When I read your first message in
reply to me, I was still thinking "holy crap how am I going to help
these guys avoid a design-by-committee disaster".. in that context,
your message (including "We need you to instruct us in this") gets
interpreted to mean that you would only consider-for-consideration the
topics I mentioned if I prepare a presentation to inform you about
their nature, existence, function or meaning. As you can imagine, that
was very startling for me to read because of how important they are to
creating any sort of informed decision about agreeing to a common file
format for packages, which informs a lot of other downstream decisions
about which tools to make and which tools to give GUIs to, or which
things might not conceptually work out from the various decisions on
file formats to keep our 'things' etc.
But now I think maybe you were not asking in that context of that
email you were replying to, and just asking out of general
curiosity... in which case I am sorry about the misunderstanding.
However, my original offer for talking whenever to elaborate on the
whatever open source hardware projects still applies.
Anyway, here is some basic ISO information as you requested. I brought
it up in the earlier emails because if Matt wants something designed
by committee, this is a big committee (tc184-sc4) with lots of
hardware companies backing it.
http://en.wikipedia.org/wiki/ISO_10303
"""
ISO 10303 is an ISO standard for the computer-interpretable
representation and exchange of product manufacturing information. Its
official title is: Automation systems and integration — Product data
representation and exchange. It is known informally as "STEP", which
stands for "Standard for the Exchange of Product model data". ISO
10303 can represent 3D objects in Computer-aided design (CAD) and
related information.
The international standard's objective is to provide a mechanism that
is capable of describing product data throughout the life cycle of a
product, independent from any particular system. The nature of this
description makes it suitable not only for neutral file exchange, but
also as a basis for implementing and sharing product databases and
archiving.
Typically STEP can be used to exchange data between CAD,
computer-aided manufacturing, computer-aided engineering, product data
management/enterprise data modeling and other CAx systems. STEP is
addressing product data from mechanical and electrical design,
geometric dimensioning and tolerancing, analysis and manufacturing,
with additional information specific to various industries such as
automotive, aerospace, building construction, ship, oil and gas,
process plants and others.
STEP is developed and maintained by the ISO technical committee TC
184, Automation systems and integration, sub-committee SC 4,
Industrial data. Like other ISO and IEC standards STEP is copyright by
ISO and is not freely available. However, the 10303 EXPRESS schemas
are freely available, as are the recommended practices for
implementers.
Other standards developed and maintained by ISO TC 184/SC 4 are:
ISO 13584 PLIB - Parts Library
ISO 15531 MANDATE - Industrial manufacturing management data
ISO 15926 Process Plants including Oil and Gas facilities Life-Cycle data
ISO 18629 PSL- Process specification language
ISO 18876 IIDEAS - Integration of industrial data for exchange,
access, and sharing
ISO 22745 Open technical dictionaries and their application to master data
ISO 8000 Data quality
STEP is closely related with PLIB (ISO 13584, IEC 61360).
The evolution of STEP can be divided into four release phases. The
development of STEP started in 1984 as a successor of IGES, SET and
VDA-FS.[1] The initial plan was that "STEP shall be based on one
single, complete, implementation-independent Product Information
Model, which shall be the Master Record of the integrated topical and
application information models".[2] But because of the complexity, the
standard had to be broken up into smaller parts that can be developed,
balloted and approved separately.[3] In 1994/95 ISO published the
initial release of STEP as international standards (IS) with the parts
1, 11, 21, 31, 41, 42, 43, 44, 46, 101, AP 201 and AP 203.[4] Today AP
203 Configuration controlled 3D design is still one of the most
important parts of STEP and supported by many CAD systems for import
and export.
In the second phase the capabilities of STEP got widely extended,
primarily for the design of products in the aerospace, automotive,
electrical, electronic, and other industries. This phase ended in the
year 2002 with the second major release, including the STEP parts AP
202, 209, AP 210, AP 212, AP 214, AP 224, AP 225, AP 227, AP 232.[5]
Basic harmonization between the APs especially in the geometric areas
was achieved by introducing the Application Interpreted Constructs
(AIC, 500 series).
A major problem with the monolithic APs of the first and second
release is that they are too big, have too much overlap with each
other and are not sufficiently harmonized. These deficits lead to the
development of the STEP modular architecture (400 and 1000 series).[6]
This activity was primarily driven by new AP covering additional
life-cycle phases such as early requirement analysis (AP 233) and
maintenance and repair (AP 239), and also new industrial areas (AP
221, 236). New editions of the previous monolithic APs on a modular
basis have been developed (AP 203, 209, 210). The publication of these
new editions coincide with the release of the new ISO product SMRL,
the STEP Module and Resource Library, in 2010 that contains all STEP
resource parts and application modules on a single CD. The SMRL will
be revised frequently and is available at a much lower cost than
buying all the parts separately. At the end of 2010 the seventh Change
Request (CR) of the SMRL has been worked out.
In mid 2010 the development of the new major AP 242 Managed model
based 3d engineering was initiated. The first edition of AP242 is
expected to be technically complete in 2011 and is dedicated to
replace the most successful STEP APs 203, 214 and other APs in the
mechanical design area in an upward compatible way. In particular it
will contain major updates in the area of Geometric dimensioning and
tolerancing, Kinematics, and Tessellation. Future editions of AP242
will extend the scope further into areas such as electrical harnesses.
........
Design APs:
Mechanical:
AP 201, Explicit draughting. Simple 2D drawing geometry related to a
product. No association, no assembly hierarchy.
AP 202, Associative draughting. 2D/3D drawing with association, but no
product structure.
AP 203, Configuration controlled 3D designs of mechanical parts and assemblies.
AP 204, Mechanical design using boundary representation
AP 207, Sheet metal die planning and design
AP 209, Composite and metallic structural analysis and related design
AP 214, Core data for automotive mechanical design processes
AP 235, Materials information for the design and verification of products
AP 236, Furniture product data and project data
AP 242, Managed model based 3d engineering (under development)
Connectivity oriented electric, electronic and piping/ventilation:
AP 210, Electronic assembly, interconnect and packaging design. The
most complex and sophisticated STEP AP.
AP 212, Electrotechnical design and installation.
AP 227, Plant spatial configuration
Ship:
AP 215, Ship arrangement
AP 216, Ship moulded forms
AP 218, Ship structures
Others:
AP 225, Building elements using explicit shape representation
AP 232, Technical data packaging core information and exchange
AP 233, Systems engineering data representation
AP 237, Fluid dynamics has been cancelled and the functionality
included in AP 209
Manufacturing APs:
AP 219, Dimensional inspection information exchange
AP 223, Exchange of design and manufacturing product information for cast parts
AP 224, Mechanical product definition for process plans using machining features
AP 238 - Application interpreted model for computer numeric controllers
AP 240, Process plans for machined products
Life cycle support APs:
AP 239, Product life cycle support
AP 221, Functional data and schematic representation of process plants
AP 241, Generic Model for Life Cycle Support of AEC Facilities (planned)
"""
Actually, ISO 10303 is nothing I would wish upon anyone because of how
convoluted (and expensive) it is; but it's an excellent example of a
standard in wide adoption that solves a lot of the core problems in
CAD. The other end of the spectrum are smaller tools like thingdoc
that solve precisely one problem well (generating documentation from
source code comments, much like doxygen or mocco or docco, or sphinx
or whatever the flavor-of-the-week documentation generator is), just
based on plaintext in a git repo (folder) that others are free to
automatically download through whatever other open source hardware
tools they so choose.
Charlie
Regarding ISO 10303 STEP with respect to issues in these OSHW discussions, what follows are comments from my perspective of being involved in several aspects of STEP and related standards/specifications.
ISO 10303 is a broad and deep collection of standards to represent the product data model for exchange, sharing and repositories over the lifecycle. The official 10303 documents are developed by ISO TC184/SC4, copyright and available for purchase. However for some purposes like CAD data exchange, the EXPRESS schemas and recommended practices that are freely available through STEPmod on sourceforge and the CAX-IF, respectively, are sufficient for software implementers. The major mechanical CAD authoring and translator software vendors participate in the private CAX-IF test rounds, and some publicly list their implementation coverage on the CAX-IF web site. There exist mechanical CAD open source and free STEP implementations such as BRL-CAD/STEPcode, FreeCAD/OpenPLM/OpenCascade, and IDA-STEP Viewer/JSDAI, and there are commercial software toolkit vendors.
The CAX-IF has recently focused on the requirements of LOTAR International for Long Term Archiving and Retrieval of commercial aircraft type certification data, such as Product Manufacturing Information (PMI) associated with geometry in AP242. The sponsors of related technology such as JT, 3D PDF, HOOPS, 3D XML, etc. participate in the CAX-IF, so it is a forum for communication on common issues. LOTAR manages a standards and technology portfolio, and sponsors pilot demonstrations. LOTAR is funding the development of AP242 for PMI, AP239 implementations for PDM and Meta-data, and harmonization between AP239 and AP242. A key part of STEP for CAD is validation: how do you measure from a STEP import or export, other than through a visual diff, that what was received is well-formed and corresponds what was sent? So there are validation properties in the EXPRESS schemas for critical metrics, and there rules, functions and procedures that STEP files must satisfy when validating against a schema using an EXPRESS compiler. The feedback loop from requirements, modifying schemas, developing recommended practices, testing data files, and identifying implementation issues has reached a regular cadence with new schemas and test rounds several times a year.
Like the CAX-IF, LOTAR is a joint project between PDES Inc. and ProSTEP iViP. ProSTEP works closely with the auto industry, and supports automotive AP242 use cases for managing assemblies and kinematics for digital mock-up applications, including shapes in native CAD, JT or STEP. This involves a new high level model in AP242 called the Business Object Model. AP242 also inherits a manufacturing process planning model from AP214, so the BOM and shape models could be used for clash detection in manufacturing. The AP242 BOM also serves as a basis for a higher-level API into AP domain specific terms, such as those for composite structure and shape, which map into the lower level representations in the STEP integrated resources used in CAD exchange. Others plan to use the 242 BOM for publish-subscribe to a shared PDM repository, incremental updates to product structures, and engineering change request/order/note.
Here is a Wikipedia article I drafted on AP242.
http://en.wikipedia.org/wiki/Wikipedia_talk:Articles_for_creation/AP_242
Other organizations such as the ASD/AIA Integrated Logistics Support S-series specifications are using AP239 Product Life Cycle Support (PLCS) through the PLCSlib (and deprecated DEXlib) integrated development environment for Data Exchange Specifications (DEX’s). PLCSlib and DEXlib are under the authority of the OASIS PLCS TC, which has liaisons with ISO and other relevant organizations. PLCSlib is a toolkit for creating DEX’s that is easier to use, has more built-in quality checks, and uses more common SysML and OWL development tools than STEPmod or DEXlib, which use EXPRESS. Most importantly, PLCS entities, properties and relationships are extendable to subclasses with OWL reference data to a domain specific terminology. In this way, new elements can be added for different uses as in the OSHW discussions.
There are other AP’s (Application Protocols) for CAE (AP209), Systems Engineering (AP233), Electro-Mechanical (AP210), etc. that are built using the STEP modular architecture (STEPmod), but not as widely implemented as CAD. Other non-modular AP’s include AP238 for CNC. The STEP integrated resources are also used by other specifications, such as the Industry Foundation Classes (IFC) which are widely used in Building Information Modeling (BIM).
There is a legacy non-modular AP232 Technical Data Packaging (TDP) that is still in production use, but LOTAR and others plan to use the more recent modular AP239 PLCS for packaging. For instance, there is a TDP message DEX, and LOTAR PDM and Meta-data DEX’s in development are for other packaging aspects. PLCS is a highly-relational and extendable model, and edition 2 includes most of AP233 Systems Engineering. Several types of high-level API’s have been built based on PLCS, for instance for the Behavioural Digital Aircraft DEX’s used in the EU CRESCENDO program.
Even within a schema like AP242, some data models have not been widely implemented, nor tested within the CAX-IF. For instance, AP242 and its ancestor AP203, contain information such as requirements, functional breakdowns, person & organization, approvals, security classification, information rights, project/contract, etc. However, recommended practices on how to use these in exchanges have never been developed by the CAX-IF, so it is not likely that they are exchanged between different software applications. The current strategy in LOTAR Meta-data is to put this information in a wrapper based on PLCS and point to the shape files, or in MIL-STD-31000 to encode the information in User Defined Attributes in AP242.
To summarize, STEP has been developed by large automotive and aerospace companies to solve very similar problems as those faced by OSHW. IMHO, STEP schema and standard development should be left to the experts because it takes considerable effort to get up to speed on the specialized technologies. The OSHW community could work through existing STEP experts and organizations to get what OSHW want implemented in the standards. However, it takes persistent effort to synch up with the various relevant ISO, CAX-IF, LOTAR, PDES, and ProSTEP meetings, projects, and schedules. A less onerous approach is to track the STEP developments and use them for OSHW purposes. For instance, like the MIL-STD-31000 TDP community, OSHW could come up with modeling practices and model attributes that they need and propose modeling guides for the former, and a set of User Defined Attributes to encode the latter. PLCS is more accessible than the rest of STEP, and existing PLCS templates and DEX’s in development could be modified for OSHW purposes. For instance, the LOTAR DEX’s could be used as a basis for OSHW packaging. Through reference data, PLCS is capable of incorporating terminology from other standards and specifications, like from OSHW. In the meantime, the OSHW community can develop their own domain terminology (while mapping it to STEP and PLCS) and use it in lightweight data formats like Excel files, pdf forms, and XML schemas. This latter approach has been used successfully by ProSTEP when developing the ReqIF standard and simulation data management specifications.