A scoping report to address feasability and shared definition of "interactivity" in the Open Know How project and open source hardware landscape. Commisioned by the Internet of Production Alliance.
The Open Know How (OKH) project is creating an open data model to standardise how hardware designs and documentation are shared online. OKH is divided into three stages: discoverability, portability, and interactivity. The first two stages are already live. The discoverability standard[1], specifies a way to make open hardware designs searchable, specifying a light-weight common data-structure to lay out important project data and to link to design files and detailed documentation. The portability standard[2] paves a way to collect, collate, and archive hardware designs from platforms in a standardised way, enabling makers to keep a permanent copy of the documentation that they need to build a product. This report discusses the scope and viability of the final “interactivity'' stage of OKH. Interactivity is meant, in principle, to enable collaboration on hardware projects across platforms and softwares and two-way updating of design documentation, to accelerate development with diverse, disparate and distributed teams. The authors have been commissioned by the Internet of Production Alliance to address the problems of: misalignment within the team on a working definition of interactivity; progressing the development of OKH interactivity in accordance with required outcomes of grant funding; and uncertainty regarding the feasibility of the technical development of this aspect of OKH.
This report will serve as a common reference for further discussion and development of OKH interactivity, provide an assessment of the technical barriers to development and offer final recommendations.
The interactivity phase of OKH recognises that shared hardware design is an ongoing collaborative process. Designs move through many phases from proof of principle, to prototypes, through eventually to design for manufacture and a final product. For a more equitable and distributed model of local production, aspects of designs must be customised for local needs and for local supplies. The ideal interactivity standard would set out a common protocol allowing designers and makers to adapt, remix, customise, and combine hardware designs from any source without the need for them to move their own work into a new platform. It could be seen as a means to circulation of design and documentation and even decentralising projects further from particular platforms and programs.
Unlike portability, interactivity must be a two-way process. Information should seamlessly move from the original source design into a modified localised design; and, if appropriate, it should be possible for these modifications to be shared back into original the design. Interactivity should allow each party to concentrate on the hardware design itself, rather than on learning new processes, new platforms and new software.
Collaborative hardware development is currently siloed by design tools that cannot interact, by documentation tools that cannot interact and by platforms that will not interact. Hardware communities spend vast effort discussing the pros and cons of specific tools and platforms and hardware projects face tough choices deciding which tools and platforms to use. After this discussion a new maker looking to build upon a project is faced with a stark choice: either learn a new set of tools and a new platform, or take considerable time to port existing work to their preferred tool and platform. If the decision is taken to port the work to a preferred, then the maker must accept that this will make it hard to share back any changes or accept updates from the original project. This paint point is the motivation behind aiming to develop an interactivity solution, which is admittedly a large scope encompassing countless files types, different softwares and numerous platforms. Not to mention the immeasurable variation in physical hardware design dimensions, materials, fabrication processes, assembly steps etc., which all have a bearing on the nature of the CAD files, documentation and other data. Broad as this scope may be, if a solution space can be envisioned, then the potential impact for collaboration, cross-pollination of ideas and distribution of Open Source Hardware (OSH)[3] could be huge. An interactivity solution could seriously challenge corporate proprietary design tools, which can hamper accessibility, as well as unlock new modes of collaboration, new work-flows and a broaden the community who can engage with OSH. This could even be in alignment with wider sustainability, political and economic objectives.
Setting out a framework for interactivity is hard due to the expansive scope of open source hardware design. A possible, but not perfect, framing could be that there are data (to be interacted with), software (with which the interaction happens) and platforms (on which the data is stored and to/from which the data is sent). Data could be broken down further into design files, documentation, planning and verification, revision control and project management. To add complexity to this contextual landscape, any given hardware project will certainly have many different kinds of data, requiring functions only available on specific softwares, stored across multiple platforms and collaborated on by many users with established workflows and cultural differences. Even the OKH data model, a single standard for organising a hardware project, is very flexible such that it gives rise to an infinitude of possible interactions between these aspects of a hardware project. Furthermore, a limitation to this framework is that in reality the distinction between platforms and softwares is blurred, such that there are many functions, like viewing, commenting and editing, that go beyond just data storage. An example here might be the CAD platform Onshape[4].
Nonetheless, to add clarity and to build a common reference for discussing the technical challenges of interactivity, the proposed framing is expanded upon.
Hardware project data can be broken down further into many aspects including: design files (CAD), documentation (assembly instructions, bills of materials), planning and verification (requirements, failure mode analysis), revision control and project management, etc.
Design files includes editable design files, typically native file types like .FCStd for FreeCAD, as well as standardised exchange files, typically neutral or non-proprietary types like .stl, .step or .iges. Within the OKH manifest schema, this could apply to fields such as, “design-files”, “schematics”, “manufacturing-files” etc. This could even include aspects of software and firmware, associated with the hardware in the project.
Documentation at its core is a combination of text, pictures, and tables.
Planning and verification documentation ranges from Product Design Specifications (PDSs), Failure Mode & Effects Analysis (FEMA) and other Quality Assurance and Quality Control (QA/QC) methods.
Revision control, or version control, is in the open hardware context often native to the platform, but could also be as simple as an agreed file naming convention between collaborators.
Project management could include clear documentation like timeplans, to more disparate and nebulous information like comments threads and discussion forums.
An imperfect framework, for conceptualising the aspects of open source hardware in considerations for interactivity. Designed by Alex Kimber, for this report.
Creating an overarching interoperability standard for all aspects of hardware design is a vast and insurmountable task, yet dealing with just one of these aspects without considering the interaction between different aspects within a single project may lead to a standard that breaks existing workflows and does not address the identified need. Therefore, an ideal interactivity development would need to take a holistic or at least widely scoped approach, touching upon the important aspects of the framing above.
Later in the report the feasibility assessment will address in more technical detail the interactivity between CAD and documentation programs, and their associated data types, as well as between different platforms, to get a comprehensive analysis. However, an interactivity standard that truly addresses the pain point would need to understand and account for all the various flows between all the aspects of the framework.
An ideal interactivity protocol would allow any change to any aspect of a design to be seamlessly updated on any platform or in any software in real time with no detriment to continuing the design within the original platform and software. A possible scenario to illustrate this could be for one user to migrate a project from one platform to their preferred one, add or edit design files in that project on their preferred platform and for their collaborator to see this change on the original source project on the first platform, in real time. This ideal is only possible with unification of functionality between platforms and software.
To illustrate why interactivity relies on unification of functionality consider the more familiar problem of collaboration on a text document. Every word processor can create a PDF of a final document with pictures and varying text size, fonts, and spacing. For consistency when writing a document a Word user may set up styles for headings, subheadings, etc. If this document converted into the format of another program, the style of each heading could be transferred correctly. However, if this other program does not have a heading feature, it will only be able to load in that this line is large and bold. Once the document is edited in the program, all information as to the location of headings, subheadings is lost. If converted back to Word, new headings would no longer maintain a consistent style. Other features such as tracked changes or comments may also be lost when moved into word processors that do not support these changes. While it is technically possible for users of different word processors to collaborate, they are limited to the features that are common to both programs. This leads either to information being lost information, or it forces users to only use a subset of the functionality of the software they are using. Even if the final output looks the same, the loss of data structure means the document is functionally not the same.
Hardware design is fundamentally more complex than document writing, as it must precisely specify the construction of a three dimensional object. This specification is held in a combination of digital design files, technical drawings, documented procedures, etc. For any product that wishes to meet a base level of quality management it is essential not only to save the current state of the project, but to also track how a project is revised and the design decisions associated with any change. This forms a fundamental part of internationally accepted quality management standards such as ISO 9001[5] (or ISO 13485 in the medical field).
A number of other hardware-focused collaboration platforms have been established to support the sharing of hardware designs, such as wikifactory[6], Wevolver[7], Instructables[8], or Anneal[9]. These platforms support the storage of CAD files, provide a way to display associated documentation, and include project management tooling or revision control. This young and vibrant space is showing many innovations but has not settled on an established workflow. As the process of hardware development is complex and is unique to the material, fabrication, context of every project, no workflow has proven to be superior or universally applicable. In lieu of an emergent practice that has broad recognition from the community, a standard with a predefined workflow for most hardware development cases would have a lowest common denominator effect. The unification of functionality that interactivity would rely on to work is a long way away from the current landscape, and would be immensly challenging to create.
In addition to CAD-based cloud collaboration and hardware-focused collaboration platforms, a number of collaborative hardware projects are choosing to use platforms designed for collaboration on software development. Mass open collaboration on software can be traced backed back 40 years to the GNU Project which began in 1983[10]. Over four decades collaborative software development has built its own collaboration platforms. Platforms such as GitHub and GitLab have millions of users are used by both commercial and open software firms. Many collaborative hardware projects use these software development platforms as they provide highly sophisticated revision control, detailed project management, and the ability build sophisticated automation into a project’s workflow. These software development platforms are very mature, but as they are designed for software their interface is often confusing or not optimised for hardware engineers and many aspects of hardware engineering are poorly supported.
Creating interactivity between software development platforms and hardware-focused collaboration platforms would require supporting only the features common to both. This would risk loosing the hardware specific features developed by hardware-focused collaboration platforms, while also loosing the more powerful automation and revision control aspects of the software platforms creating a worst of both worlds. Focusing only on hardware-focused collaboration platforms will exclude a large proportion of established collaborative hardware projects that require advanced features not yet available on these less established platforms. To mitigate this risk one could identify only those features that were best practice in both categories, and focus development on iterative improvements there, which would not constitute the definition of global interactivity stated above and would be more like the portability phase of OKH. For example, in software engineering, most platforms build their features on top a well supported version management program that can be run in the cloud or on any local machine (Git). Encouraging hardware platforms to follow this lead and build upon open standards would both accelerate innovation and enhance portability.
One possibility is to focus only on the interactive editing of documentation, such as assembly manuals. However, this itself poses significant problems. Hardware documentation is tied to the specific design. While some projects do use general purpose word processors for text documentation and spreadsheets for bills of materials this is problematic for complex projects that need to track large numbers of assembly stages, different hardware configurations, and link the documentation directly to the design.
Established commercial documentation platforms like Dozuki[11] (used by iFixit, and Prusa Research) allow the reuse of specific instructions in multiple configurations of a project, and also support multiple documentation in multiple languages. Other documentation software is being developed by members of this community. OSH AutoDoc[12] interacts directly with the CAD itself to automate the creation of bills of materials and assembly renders. GitBuilding uses metadata to track bills of materials as components are mentioned in documentation, bills of materials and instructions for highly configurable projects with minimal duplication of information. Likewise to the emergent hardware focused software and platforms for CAD, these documentation platforms for complex projects with varying requirements is a dynamic space with no dominant, proven and popular solution, applicable to all. Therefore, interactivity of documentation would risk low adoption from the community, due to only being able to functionally exchange features common to all platforms resulting in a solution not suitable for the complex projects that the likes of Dozuki addresses.
Despite the apparent challenges and risks of development of an interactivity standard, the benefits of the ideal interactivity could be wide ranging if it were possible to unlock or come close to.
Traditionally tacking of how a project is revised and evolves over its design is handled via specialised Product Data Management (PDM) software within major organisations. PDM software is highly centralised, with data stored within a companies own servers. Within the larger enterprise further project management and data storage covering the whole lifecycle of the product is contained in centralised Product Lifecycle Management (PLM) software. Both PDM and PLM software is often prohibitively expensive. If interactivity could be established across a decentralised network of platforms, with comparable collaboration features as PDMs and PLMs, then this would significantly lower the barrier to complicated, larger scale hardware development, but would need to match up to the impressive functionality of these closed softwares and server networks.
PDM and PLM software is dominated by a few companies that also write CAD software, often with one product requiring the use of other products. This entrenched vendor oligopoly has dominated hardware design within traditional centralised industry. With the internet enabling distributed design and manufacturing some commercial companies have begun to offer could based CAD with built in revision control (such as Onshape or Fusion 360), keeping design history and CAD locked into the same software. This means that a platform like Fusion 360 can offer a one-stop-shop of powerful tools and a streamlined workflow that is useful in hardware development, but only made possible through centralisation, proprietary features and prohibative subscriptions. Interactivity could unlock this vertical toolchain, but would need to work wholesale, covering an entire equivalent and broadly accepted workflow, or would not offer the same kind of value.
Full seamless interactivity would require interactivity between CAD programs, interactivity between documentation software, and interactivity between platforms. Rather than consider interactivity as a whole this report will consider these three aspects separately to make the analysis.
Computer Aided Design (CAD) interactivity is likely the least feasible aspect of interactivity within the OKH scope. Original CAD files contain more than just the geometry of the final designed part or assembly. Most traditional CAD files contain a tree structure of different geometry operations which are linked together. This allows the CAD users to step through aspects of the design to understand how it has been built. It also allows parametric models can be adjusted in a clear and consistent manner.
As part of a parametric design, the designer might specify that the width of an object is always twice its length and the depth is half the length. They may then specify that a series of holes are spaced with dimensions allowing them to mate with another standard component. In this simple example when modifying the length of the object all three principle directions will scale, however the hole pattern will remain fixed as it is needed for mounting. If only the geometry is exported from one CAD package to another, these design critical parametric constraints are lost. Uniform scaling would break compatibility of the mounting holes, linear scaling of the length would not affect the other dimensions as the designer had intended.
As components and assemblies become more complex, the number of interdependent constraints grows. To allow seamless collaboration between CAD packages they must be able to not only describe the same geometry, but they must implement the same constraints and structure to allow modelling to be continued or adapted, vis-à-vis the analogus word document to PDF problem decscribed earlier.
The complexity of adapting CAD models is hard to overstate. Even within a single CAD program there is considerable development that goes into ensuring that CAD models do not break when changes are applied. For example if a step late in the process of designing the shape adds a logo to a specific face of the object, what happens when and early step is modified changing the number of faces? This "topological naming" problem[13] is largely mitigated in many modern CAD packages, but remains a major issue within the Open Source CAD package FreeCAD. As can be seen from the considerable amount of ongoing development on Topological Naming within CAD, the solution depends on a great level of extra information to be stored which is specific to the way the underlying CAD kernel calculates geometries. Any work to allow CAD programs to seamlessly interact with CAD files from other packages would likely add to a whole regression in the stability of models under modification, forcing users to adopt more disciplined design workflows. In short, exchanging CAD data is markedly harder than, for example, text documents, due to unique geometric and programmatic challenges.
Standardised exports (or data exchange formats) for CAD geometry do exist. STEP is the most famous of these data exchange formats. The STEP standard is maintained by the International Organization for Standardization (ISO), under ISO 10303[14]. While STEP looses the constrains that allow seamless ongoing development, the format is almost universally supported within CAD packages. However, despite this near universal support STEP is not a fully reliable export method. The standard is long and complex allowing the same geometry to be described in multiple different forms. Due to this complexity and the miriad of information that could be contained, the full standard is rarely implemented in full.
Another broadly used file format is the trusty Standard Tessellation Language (STL) file. Unlike the STEP file which saves complete geometry, STLs divide up the form into a mesh of many triangular surfaces, giving a “pixelated” representation. The more triangles used to build up the mesh, the higher the resolution the model is the more it is reflecting the true design, with the trade-off of larger file sizes. Sharing geometry using mesh files is useful because they can be lightweight, depending on the facet count, and are commonly used for fabrication, i.e. slicing for 3D printing. However, they are only approximations of the exact dimensions of the original design to a workable resolution, meaning a great deal of accuracy (and, depending on the number of facets, precision) is lost, and parametrisation is impossible. In order to share the designs in lower files sizes a lower resolution is required, accelerating the data loss trade-off.
Improvements to CAD interoperability (or interactivity) are likely to come through future ISO standardisation due the major corporations that write most CAD packages and also the major corporations that are key users of the CAD packages. Standardisation that allows users to port CAD files from one company’s CAD package to another is unlikely to be seen as desirable for a established major CAD vendor, as it provides a pathway for their existing users to migrate all of their past work to another vendor's package.
Theoretically any tool could be used to create the documentation. Some level of conversion between documents formats is achievable with programs such as Pandoc[15].
The core documentation format used in many online platforms is markdown. Markdown is used by hardware platforms such as Wikifactory, and software focused platforms such as GitHub and GitLab.
Documentation for complex systems is often hard to maintain manually. Again looking to open Open Source Software (as a mature field for collaborate development), the main documentation for code is rarely written in markdown on GitHub, this is normally simply a landing page pointing to detailed documentation. Standardised documentation practices that link directly to the underlying code are common in modern programming languages. This allows developers to keep the code and documentation synchronised and allow automated checking that the documentation is complete.
Within the field of hardware development the most basic instructions are assembly instructions. These often contain photographs or renders of the assembly steps, tabulated lists of parts and tools (bills of materials), and textual description of the documentation. The challenge for hardware documentation is to keep these the renders, bills of materials and text in sync with the design as it changes. This is particularly important for collaborative development where remote teams each contribute to ongoing prototyping.
A commercial platform for documentation hosting is Dozuki. It is possible to set a bill of materials for a Dozuki page. It is also possible to have longer guides using multiple pages. Two different guides can re-use the same pages if they share assembly steps. Dozuki also allows pages to track other information such as the task difficulty or the time taken, and it supports translation of documentation. It also has considerable extra functionality for within business to record the assembly of specific products for quality management purposes and to provide feedback. The freedom to document is somewhat limited by all text being limited to bullet points which render best when kept short; this however is done to encourage short precise instructions. The data from within Dozuki can be exported in a documented format called oManual[16].
Open source documentation programs for hardware are being written within the community. An early example was Docubricks[17] which like oManual has a strict data structure, allowing part lists for each "brick" (bricks are a set of instructions in Docubricks). The structure is designs so that bricks can be reused within larger guides. Docubricks has seen little to no development over the past five years.
A more actively maintained open source documentation project is GitBuilding[18]. GitBuilding is based on markdown bringing it closer to the format used within Wikifactory, GitLab, and GitHub. It is designed to allow the documentation to be stored on the same platform as the hardware design. GitBuilding uses custom metadata to tag the use of components within written instructions. This allows the Bill of Materials to be created automatically as a spreadsheet for a whole guide, as well as the bill of materials for a single page within the guide to be displayed at the top of the page. GitBuilding also has functionality to allow pages to be reused in multiple guides, including advanced templating that allows specific elements of a reused page to be tweaked, for example to show a different image. It also has functionality for previewing 3D models.
While GitBuilding provides steps forward directly linking the parts that are mentioned within the text to the bill of materials that is presented as a table, it does not link directly to the CAD source for either rendering the assembly process or checking consistency between its Bill of Material and the one specified in CAD. Another new open source documentation project is attempting to address this challenge. OSH AutoDoc is a plug-in for FreeCAD that creates assembly renders, and Ikea-style instructions using a markup language called scribble. OSH AutoDoc represents a potentially huge step forward in the quality of hardware documentation, but it is limited projects in a specific CAD package (FreeCAD) and is only at the proof-of-principle stage[19].
Due to the very different ways that information is captured in programs like Dozuki, Docubricks, GitBuilding, and OSH AutoDoc, no simple conversion can move documentation from one format to another without loss of information. A standard that captured features in common with each program would remove the most innovative features of these programs as they develop. This is likely to harm rather than benefit the community of users. GitBuilding has made some effort to implement Dozuki features so oManual documentation can be imported, however the import will still always require manual work to link up the parts used to the correct part of the text. The developers of GitBuilding and OSH AutoDoc are also in communication to see if there are ways the two programs work together.
Another, perhaps smaller yet nonetheless illustrative, issue that documentation interactivity could come up against is regional differences in requirements. For example, technical drawings, needed for part manufacturing follow industry standards and conventions. Although drawing standards like the ISO Geometrical Product Specification (GPS) and the British BS 8888 standard are similar in how they stipulate line weights, units, projections etc., they vary from American and Japanese standards. Meaning universal interactivity of documentation would need to account for translating not only content of the documentation for regional differences, e.g. language, but the formatting and structure too.
Platform interactivity has two key barriers. Firstly that most platforms not only store the current hardware design. They also store the history of the design (revision control) as it has evolved, which is essential for quality management. Most platforms also provide some level of project management such as Wikifactory's Tasks, or GitLab's Issues, Epics, and Merge requests. The minimum for true interactivity would be some alignment of functionality. For example GitLab and GitHub have similar project management and use the same underlying software for revision control. This allows projects to be exported from GitLab and imported into GitHub (or vice versa) with very minimal data loss. This is not possible between GitHub and Wikifactory, as Wikifactory uses its own proprietary revision control which does not allow export of the full revision history.
Even with complete data alignment, interactivity is considerably more complex. Platforms such as GitLab are open source, this means that many organisations maintain their own GitLab platform (such as the CERN Open Hardware Repository). Despite there being total data alignment between GitLab.com and another organisation hosting GitLab, it is not possible for a user on one server to fully interact with a project on another server. GitLab has discussed adding this functionality for seven years (see https://gitlab.com/gitlab-org/gitlab/-/issues/14116)[20], however there are numerous technical and security issues as to how the information could safely be brokered. Some progress on interactivity (or federation) between different software development platforms has been made by the forgefriends project[21]. ForgeFreinds is using the W3C Activity Pub protocol[22], the complexity of the project despite the alignment of underlying data within software development platforms should highlight the difficulty of seamless interactivity between platforms.
While true seamless interactivity would be ideal, it is a task that would be impossible without a significant rewrite of many major open source and proprietary platforms. Even a carefully delimited scope, such as a subset of documentation of OKH formatted projects, on a limited selection of platforms using preselected softwares, would still be challenging to achieve two-way interactivity. Furthermore, with this it still may limit exploration of new functionality.
Instead of focusing on interactivity, this report recommends focusing on enhancing portability as high fidelity portability of data between programs and platforms. Improved portability would not solve the issues identified, such as the difficulties in learning a new platform, but it might go some way to mitigate some of the issues in migration of projects and sharing data across teams, which would aid collaboration.
The current OKH portability standard is a one way export away from existing platforms into a "Solid". While the use of the standardised web decentralisation project such a solid allows users to have full control of their design that they have exported, the portability standard in its current form does not create a project where work can easily be continued, ported to a new platform, or even ported back into the original platform.
Enhanced portability is unlikely at this stage to be appropriate for standardisation, as there is not enough alignment between projects to directly port information. Instead, an enhanced portability project could work on a detailed mapping of the key data structure differences between platforms, documentation tools, and CAD tools. To better understand precisely which data structures, workflows and features are used, and by which stakeholders, a qualitative analysis and surveys could to be undertaken, in order to pin point which aspects of the mapping ought to be developed for enhanced portability. From this the project could help develop import and export functionality between specific software which explicitly captures or highlights data that is lost or needed after conversion, as well as data flows that are most commonly used by the community. This targeted approach, coupled with detailed user guidance, would provide users with certain clear paths to move a project into their preferred platform or software with knowledge of the work involved after import/export and realistic expectations of data fidelity.
In summary, interactivity as currently conceptualised would come up against significant technical barriers to development, even if the resulting ideal would seriously challenge existing verticals, oligopolies and proprietary platforms by enabling “faster publishing with maximum reach, speeding up research and reproduction”[23]. It not deemed feasible, by this assessment, that an open source data standard could instrumentalise two-way data conversion, across different platforms, encompassing the necessary aspects of open source hardware design and workflows, in the current landscape. Therefore, it is the recommendation of this report to focus attention and resources on enhanced portability where there is an identified need from a stakeholder group and a detailed data flow mapped out, to provide users with some routes for a minimal loss of data structure, damage to workflow or compromise of features from the relevant software or platform.
Creative Commons Attribution 4.0 International License (CC-BY 4.0)
