Hey there! The Open Source Imaging Initiative [1] published the design files of their first low-field MRI scanner [2, 3]. The dev team consists of geeks only, all specialized in a very specific field of engineering; there are only a very few individuals that understand all aspects of the machine. They are yet lacking a digital toolchain geek – and until we have one, I’ll take this role
The design files shall move to a self-hosted GitLab instance (already prepared). As some of you may know, the machine shall get certified for clinical use in the EU (and further judicial areas from there on); the technical documentation will need to follow relevant templates (e.g. [4]) and serve as a references for others that want to replicate and deploy the scanners.
Consistent versioning is the backbone of the toolchain – and currently the biggest concern in the community. People shall be able to maintain and upgrade a scanner at any point in time; so they need to know which exact versions of the modules have been used in their setup and which are compatible to each other.
I’ve put together a first draft [5] that touches on documentation structure and versioning. I would love to discuss it here and add your insights to it.
Once structure and versioning are clear, I’d like to expand the draft towards more layers of the toolchain (#OpenFlextureFTW)
I think our model of the variations/version was different. So this is a very interesting use case if you go with GitBuilding
In OpenFlexure the core microscope was in a single repo (other repos for software/electronics, etc). Our variations were things like higher or lower cost optics. As such, the entire project moved to the new version and we ran the docs.
For this it seems that you have versions for each sub components, and then you build a specific machine. Using submodules is one way to make sure the modular git repository is correct. If all instruction files for the sub-assemblies are in these it should be possible to make consistent documentation.
However you need more than just assembly documentation. You might need upgrade documentation and you will certainly need user documentation. It would be interesting to think about this.
I think the hardest part of the puzzle will be to think about how to mark which versions are compatible. And also to make sure that it is simple to configure the submodules in an instrument by instrument basis. Git Submodule is pretty confusing, and someone needs to fork the repository and adjust all the submodule versions for their instrument. This seems quite messy and fork-heavy approach. I shouldn’t need to fork and edit a git repo to create documentation for a configuration. I should be able to clone the git repository, feed it in a configuration file and get the instructions.
Sounds like we need a hardware version of a package manager. This isn’t a new thing I don’t know if any of the toolchain research has looked into Configuration Management as I think it is called in the PLM world.
[Edit to say: I am not 100% sure I totally understand the term Configuration Management, some reading seems to imply that it is more similar to how I would understand the term “version control”]
Thousand thanks! I needed about 1h to process your post; the issues you point out are quite some rabbit holes (:
I’ve updated the draft, adding 2 new points:
I have to say that I have no clue how software package manager work internally and I do feel like I’m reinventing the wheel here – am I the first one to structure modules for an upgradable, complex assembly?
this is related to point 4. in your specification under “general”:
This alone is a multi million dollar project, I would think.
This is exactly what … supposedly, Tesla & co. have, and which I once said it would be super important to have for Open Source, and that we should send someone over there to liberate that specification, which should be possible, because it also makes sense for Tesla. Theirs is … seemingly working well in practise, so we would safe a LOT of time and money and effort.
… but as this is not gonna happen before you start developing (if ever), I would say you need to have a very limited way of interfacing between modules. Software wise it is possible, even though it is far from trivial as well; but hardware wise … I would not want to do that, because it would be a half-assed thing for sure (more like 1/1000-assed). needs a lot of thinking how to limit the interface(s) and the possible changes. you will not be able to do something general.
one way would be, to have humans test the compatibility and fill out a compatibility table, only for modules they actually tested together. if there are cross-dependencies though, this will quickly become infeasible.
with cross-dependencies I mean: this module in this version works with the main machine in this version, but only if software version so-and-so is used.
@kaspar did some of this fancy constraint solving just as package managers do for OpenFlexure. It was used in the STL selector.
While his program worked, it suffered from a garbage-in garbage-out problem… that was that many of the combinations had never been considered/tried. It could correctly solve the constraints it was given, but that didn’t mean that the answer was true. As Robin says, human testing compatibility will be key, especially as you move towards ISO13485. However, I would hope that this doesn’t mean too much extra information needs to be duplicated in the docs, just that a human needs to check it.
Thanks everyone for the replies! I think this was the impulse I needed to rethink the approach and come to a (as I hope) better idea
And sorry that is has taken ages for me to reply to my own post… the last months have been
intense and I didn’t find the brain space to properly think this through.
I’ve now decided to keep things simple: no compatibility assessment based on the specification of interfaces and dependencies; just versions of modules with BOMs defining a working combination of submodules.
