karpfen in short
karpfen is an open-source toolkit for model-driven engineering. You describe a system in a few text files and run it. karpfen IDE is the desktop program that edits, draws and runs these files.
What karpfen is for
Lightweight prototyping
A system in karpfen is a folder of text files: the types of a domain, the objects, and the state machines that change the objects. The runtime executes these models as they are, so trying an idea means changing a file and running it again. While the model runs, you send events to it and watch it change. Bridges connect the running model to HTTP, MQTT and ROS, so a prototype can talk to real devices and services.
Teaching model-driven engineering
karpfen is small enough for a course at a university or a training in a company. Its three languages cover the core ideas of model-driven engineering: a metamodel, a model that conforms to it, and behaviour as state machines. The IDE shows every file as text and as a diagram side by side, checks a model against its metamodel while you type, and halts a running state machine at breakpoints. The first chapter of the documentation is a complete walk through one example, a lamp with a wall switch.
The three parts of karpfen
- The modeling languages
-
Three textual languages. KMeta describes the types of a domain, KModel describes the objects of these types with their values, and KStates describes a state machine that runs on one object, where it reads and changes the model.
- The runtime
-
A server that runs a model with its state machines in steps called ticks. Events come in from outside, and clients watch the model change.
- The IDE
-
A desktop program that edits the files, checks them while you type, draws them as diagrams, runs them in its own runtime and shows the run.
What the IDE does today
- Draws every model file as a diagram that also edits the text
-
A
.kstatesfile is drawn as a statechart, a.kmetafile as a class diagram and a.kmodelfile as an object diagram. The diagram is drawn from the text, and every change made in the diagram is an edit of the text, so Undo takes it back. - Checks while you type
-
Once the text has not changed for 300 ms, the editor reports syntax errors and checks each file against the files it depends on: a model against its metamodel, a state machine against the types and events it names. Every run validates the project first, and an error blocks the run.
- An editor that knows the three languages
-
Syntax colouring, with Python coloured on its own inside
EVALblocks, completion, hover, go to definition across files, an outline, and find and replace with regular expressions. - Runs in a karpfen runtime in Docker
-
Run deploys an environment descriptor, a
.kenv.jsonfile, to a karpfen runtime in a Docker container that belongs to the IDE. Each open folder gets its own container, which listens on127.0.0.1only. The first run builds the image of the runtime, which takes a few minutes. - Shows the model while it runs
-
The Runtime tool window shows the model as a tree, the active states of every state machine and the log of the runtime. Its Events pane sends an event with a JSON payload into the run, and the open statechart marks the active states while the run is observed.
- Halts a run at breakpoints
-
With the language feature Breakpoints switched on, a run halts at the
BREAKPOINTblocks of states and transitions. Resume and Step continue it, and the statechart marks where the run halts. - Bridges to HTTP, MQTT and ROS
-
A
.kbridge.jsonfile connects the running model to the outside. An inbound route turns a message into an event; an outbound route turns a property, the active states or an event into a message. ROS goes through a rosbridge server. - Validates and runs without a window
-
The same program works from a terminal:
karpfen-ide validate <folder>checks a project andkarpfen-ide run <folder>runs it, each with a defined exit status.
Facts
- Systems
- macOS on Apple silicon and on Intel, Windows, Debian and Ubuntu. There is one installer for each. Download karpfen IDE
- What it needs
- A local Docker engine, such as Docker Desktop, to run a model. An installed IDE brings its own Java.
- Licence
- Apache License 2.0. The languages, the runtime and the IDE are open source, each in a repository of its own. karpfen-IDE on GitHub
- Maintainer
- Karl Kegel. About karpfen
- Documentation
- A numbered reference of the languages, the runtime and the IDE. Documentation