Why I Built My Own SysML Tool
· Projects
I spend my days working on systems. At work it is my job. At home it is my hobby. Firmware, test rigs, little devices that talk to each other. Everything I touch is a system of some kind.
And every system has the same problem. The big picture lives nowhere.
The requirements are in one document. The architecture diagram is in some slide deck from two years ago. The real behavior is in the code and the wiring. These three never agree with each other. When something changes, you update one of them and forget the other two. Six months later the diagram is fiction.
Systems engineering people solved this a long time ago. It is called MBSE — model-based systems engineering. You keep one model of the system, and everything else is a view of that model. The standard language for this is SysML. It has been around for about twenty years.
So why doesn't everyone just do that?
Because of the tools. The serious SysML tools are enterprise software. They cost more than my car. There are free community editions, but they are capped — one popular one stops you at 500 model elements, which sounds like a lot until you actually model something. The open-source options are heavyweight web platforms that want a server and a database before you can draw a single box. I just wanted to open a folder and start modeling.
Then SysML v2 came along and changed one thing that matters to me more than everything else: it has a textual notation. A model is now a plain text file. You can read it. You can diff it. You can put it in git next to the code it describes.
That was the moment I decided to build my own tool. If a model is just text, then a modeling tool is just a good text editor with pictures. That is a thing one person can build.
So that is what the SysML v2 Tool is. You open a folder of .sysml files. Text on the left, diagram on the right. They are the same model — edit the text and the diagram updates, drag a connection in the diagram and the text updates. There is a table view for requirements and parts, because sometimes a grid is the honest answer. It checks your constraints too: write car.mass <= 2000 in a requirement, and when your car gets too heavy, the tool tells you.
The text is always the source of truth. The diagrams are just projections of it. There is no hidden database, no binary file format holding your work hostage. If you stop using the tool tomorrow, your models are still readable text files in your git history.
But the real reason I built it is simpler than all of that. I wanted a tool I can shape. Every tool I use daily annoys me in some small way, and normally I can do nothing about it. This one is different. When the diagram layout bothers me, I fix it. When I need a part of the language that is not supported yet, I add it. The tool grows in whatever direction my projects pull it.
I should be honest about what it is not. It covers a practical subset of SysML v2, not the whole standard. It will not replace the enterprise tools for people who need the enterprise things. It is a personal tool, built for the way I work.
There is a version of it running right here on this blog. It works in Chrome and Edge — it opens a local folder on your machine, and your files never leave your computer. You can even install it as an app from the browser if you want it on your dock.
It will not make your systems simpler. It did not make mine simpler. But at least now my diagrams and my requirements stop lying to each other.