Nimble Project Wrap-Up
Author: Jeremy Wright
Published: 2025-10-20
Last Updated: Never
License: CC BY-SA 4.0
Previous Post: First Nimble Project Update
Contents
Introduction
Note: There is a companion post on the Wakoma blog which gives the high-level "why" of Nimble, and it is a nice comlement to this post which covers the low-level "how" of the technical implementation.
This is a wrap-up post for the Nimble project work funded through NGI Zero Core, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. This post can be read in isolation, but the previous post on this project will give some additional context.
As a quick recap, this development team met at a hackathon hosted by the Open Toolchain Foundation (OTFN) in March 2023. OTFN exists to "promote the adoption and support the development of tools (software) for designing products, machines, etc. (hardware), namely Open Source software tools for engineering." At that hackathon a prototype was built of a system that created parametric documentation which stayed in sync with its associated CAD when changes were made. The prototype focused on the Nimble network rack and worked well, but it had a long way to go to be production-ready. NLnet funded the development of this production-ready system so that Wakoma and the team could bring it to reality. There was also a focus on the part of NLnet to ensure the toolchain was independent of the Nimble project so that it would be useful to a wider range of hardware projects. I believe that the team has met this goal.
The Result
If you want to skip straight to seeing the end result, there is a hosted version of the Nimble Configurator here. A screenshot of the final user interface with a sample configuration is shown below
CadOrchestrator also has an example cup holder tree project which demonstrates how flexible CadOrchestrator can be in serving other projects. The example uses OpenSCAD instead of CadQuery as its CAD tool, showing that users are not locked in to a single CAD system. A hosted version of that example project can be found here.
A flow chart of this project's initial architecture was provided in the previous blog post. While the end result uses most of the same pieces, there are some key changes in how things are organized. The following updated diagram, created by Julian Stirling, goes into much more detail on the final architecture and how the data flows.
The diagram itself provides some explanation text, and what follows is additional information on the components. It is important to note that with the exception of the Nimble-specific source files and the hardware database, these tools can be used for other hardware projects besides Nimble.
- Networking Hardware Database - Wakoma did a survey and assembled information on the most common network components used for Nimble racks, and then added that information into this database. The information includes the physical dimensions of the device in each shelf, which allows CAD models and assemblies to be generated in an automated way. This database was created specifically to service the Nimble project, but the information contained in the database could be useful to other projects.
- CadOrchestrator - The area boxed in as CadOrchestrator was labeled generically as the "orchestration" layer in the original diagram. This application provides a web server and a user interface to allow a user to configure and generate their customized documentation and CAD. It has "orchestrator" in the name because it acts like an orchestra conductor to the rest of the application, triggering actions based on user input.
- ExSource Tools - ExSource is a tool which can run various programs to generate output, kind of like a build tool for hardware projects. For instance, it can be passed a source file for OpenSCAD, told what format to output that CAD file to, and it will run OpenSCAD to convert the file. This is frequently used to convert source files to an output format (i.e. STL). ExSource also has the capability of running cq-cli, which is the next piece of the puzzle.
- cq-cli - Most of the CAD work done in this project is in CadQuery, and a wrapper around CadQuery called CadScript is used in some places. cq-cli is an existing command line tool which takes these files and converts them to an output format (i.e. STL, STEP) for use in the generated documentation. During the course of this project, cq-cli was expanded to handle FreeCAD files as well, including parametric ones. This means that with a single tool, ExSource/cq-cli can convert all CAD files needed in this project to other formats. A special assembly renderer script was also created that allows cq-cli to trigger the output of PNG image renders of Nimble shelf and rack assemblies. This includes annotated and exploded views, which leverage callouts (i.e. assembly lines) to make assembly instructions more expressive and easier to follow.
- GitBuilding - GitBuilding is an existing tool that was developed to allow creation of high-quality, easily updated hardware documentation, with a focus on assembly instructions. GitBuilding uses text-based source files which can be manipulated by a program, enabling the sort of automatically adapting documentation which this project requires. GitBuilding ties all of the automated changes to the documentation source together with the output CAD files to generate the resulting documentation which the user can see and interact with. As stated above, this documentation is kept up-to-date with the current state of the configuration of the Nimble rack.
- Source Files - At the heart of the system is the text-based source files. Some are configuration files that tell CadOrchestrator how to do its job, and others are source files for the resulting CAD and documentation. These source files may be modified by CadOrchestrator based on user input to achieve automated adaptation of the documentation for any given configuration. You can see the flow of where these files are used in the diagram above.
Reflections on the Result
Creating a truly modular, automatic, infinitely configurable system that generates CAD, renders, and documentation on the fly was ambitious.
The team learned valuable lessons during this project. As always with programming, generating something that is simple and flexible is easy enough, as is generating something complex and inflexible. We used this project to create the complexity we needed to build and document the Nimble, and then at regular intervals we paused to refactor it into more self-contained and flexible tools and functions.
This project has not fully reached the holy grail of a highly complex and truly flexible system that is usable for any project. Aspects of the codebase were easy to generalize, and these have been generalized into their own tools. Other aspects likely still need additional refinement, and that is discussed in the next section.
Where to Next?
A great first step would be for other open hardware projects to implement parts (or the whole of) this architecture for their own projects. The separate parts of this toolchain are listed above, but two good high-level project repositories to use as templates and discussion spaces would be the Nimble and CadOrchestrator-Example repositories.
By implementing this system for other real-world hardware projects, it is hoped that it can be refined and improved into a system that can be applied universally to any hardware project.
There are many options for where the development of this project could go next. Below are a few ideas.
- The hardware documentation tools that we have demonstrated require the user to be Python-savvy enough to install packages on their local machines. Many hardware engineers find this difficult. Creating a hosted documentation platform that allows anyone to suggest edits to hardware documentation would be a huge step forward for open hardware. We would like to do this in a way where we do not hold a user's data, we just help them manipulate it. One option would be to support the GitHub and GitLab APIs, a hosted service would then create Merge Requests with updated documentation.
- Better tools for visualizing assembly steps. We already have a demo (slider on bottom view here) of how to create animated assemblies. However, the workflow for creating the correct animated files makes the method difficult to use in any evolving open hardware project.
- Expand the generated renders of CAD assemblies to include numeric callouts that correlate to a Bill of Materials, which updates automatically with changes in the assemblies or BOM.
Thanks
Two organizations were directly involved in making this project happen.
- NLnet - Provided the funding that allowed for this project to be built. The funding was specifically provided by NGI Zero Core, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program.
- Wakoma - Provided the point-of-contact with NLnet, and guidance on what the community needed in the final result of this project. One of the forms this took was to establish and populate the hardware database mentioned above. Wakoma also provided developer operations expertise to host the hardware database that feeds into the documentation/CAD system, as well as providing hosting for the finished server framework.
In addition, this team would never have met if it had not been for the Hackathon hosted by the Open Toolchain Foundation.
Team
The following people were members of the team for this project.
- Eric Nitschke - Project management, database development and community interface.
- Julian Stirling - Project management, GitBuilding expertise and Jack of all trades.
- Antonio de Jesus Anaya Hernandez - DevOps (Developer operations) Engineer
- Amudhan Manivasagam - DevOps (Developer operations) and database development.
- Andreas Kahler - CAD model development.
- Jeremy Wright - CAD assembly development, CAD rendering and annotation.
Editors
The following people contributed feedback on this blog post, and it is much appreciated.
© 2018-2025 7B Industries