Skip to content

Publishing Your Hardware Designs in the Open Hardware Repository

The Open Hardware Repository is a place on the Web to showcase your hardware (and gateware) designs. It is complementary to typical developer platforms such as GitLab and GitHub in that it makes it very easy to find what you are looking for. As an example, let's look for an FMC carrier in PCIe format. You can easily find the SPEC board by clicking on the funnel icon in the search bar, selecting the PCIe tag and then narrowing down even further by selecting FMC Carrier. That leaves you with still a few options, one of which is the SPEC.

From the SPEC page in ohwr.org, you have links to the project hosted in gitlab.com, in particular the wiki describing the project as recommended in our best practices for hardware. The actual design files are still one click away from there, in CERN's EDMS.

In this example, there is a separation of concerns:

  • ohwr.org makes it easy for prospective users and collaborators to find your design.
  • The developer platform (gitlab.com in this case) allows you to easily present and update information in a wiki and to manage issues.
  • EDMS ensures your design files are safely stored at CERN for many years.

How it works

The ohwr.org site is built every day using the Hugo static website generator with some additions. The source code for the website lives in https://github.com/OHWR/ohwr.org.

The generation of the website is data-driven, with file config.yaml playing the most important role in the process. It is a configuration file containing one entry for each project to be included in the catalogue.

Here is the entry for the SPEC board:

- id: 'spec'
    repository: 'https://gitlab.com/ohwr/project/spec.git'
    contact:
      name: 'Grzegorz Daniluk'
      email: 'grzegorz.daniluk@cern.ch'
    weight: 90
    tags:
      - 'PCIe'
      - 'FMC'
      - 'FMC Carrier'
      - 'White Rabbit'
      - 'WR Node'
    compatibles:
      - 'fmc-tdc-1ns-5cha-hw'
      - 'fmc-delay-1ns-8cha'
      - 'fmc-adc-100m14b4cha-hw'
      - 'wr-switch-hw'
      - 'wrs-lj-hw'
      - 'wrs-fl-hw'
      - 'wrs-ljdprep-hw'
      - 'wr-switch-hw-v4'

The repository key tells the website generator where to find further information. In the case of the SPEC, it points to a git repository in gitlab.com. By convention, the generator expects to find a file called .ohwr.yaml in the top-most directory of that repository, containing further information about the project. You can see that file for the SPEC here. It is a simple text file in YAML format providing e.g. licensing information and links to the pictures which the generator fetches to build the ohwr.org site.

This level of indirection provides you as a designer the freedom to evolve the content under your control (by e.g. modifying your wikis and your .ohwr.yaml file) while the maintainers of ohwr.org keep control of the config.yaml file in GitHub and can decide which projects to include in ohwr.org.

The format and options for your .ohwr.yaml file are documented in the instructions to submit a project to ohwr.org. They also include a method to display news for your project.

How to get your design in the catalogue

Since you cannot directly modify the config.yaml file that drives the generation of the ohwr.org website, you need to ask the maintainers to do so. This is done through the creation of a GitHub issue as explained in the instructions. In the issue, you will be asked to provide the link to the repository of your project (where the generator should find your .ohwr.yaml file), your contact details and any tags (existing or new) you want to use in your project. If you know of any compatible piece of hardware already in ohwr.org, you can mention it as well.

The information you supply will be used to create an entry in the config.yaml file as the one shown above for the SPEC board. The weight key is optional and allows the maintainers to control the order of display of projects in ohwr.org.

Notice that if you are completely new to this flow, you will need accounts in all relevant collaboration platforms, including a github.com account to create the issue and a gitlab.com account if you are hosting your design in gitlab.com. Please use your cern.ch address as primary email address in these accounts for any CERN-related work. Notice also you can host your design in github.com, gitlab.com or any other git-enabled platform, always mirroring the repo at CERN for backup purposes.