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.

1 Getting started

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.

2 Modeling languages

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.

3 Execution

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.

4 The IDE

What the IDE does today

Draws every model file as a diagram that also edits the text

A .kstates file is drawn as a statechart, a .kmeta file as a class diagram and a .kmodel file 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.

4.3 Diagrams

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.

4.4 Validating

An editor that knows the three languages

Syntax colouring, with Python coloured on its own inside EVAL blocks, completion, hover, go to definition across files, an outline, and find and replace with regular expressions.

4.2 Text editor

Runs in a karpfen runtime in Docker

Run deploys an environment descriptor, a .kenv.json file, to a karpfen runtime in a Docker container that belongs to the IDE. Each open folder gets its own container, which listens on 127.0.0.1 only. The first run builds the image of the runtime, which takes a few minutes.

4.5 Running

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.

4.5.4 The Runtime tool window

Halts a run at breakpoints

With the language feature Breakpoints switched on, a run halts at the BREAKPOINT blocks of states and transitions. Resume and Step continue it, and the statechart marks where the run halts.

4.6 Debugging

Bridges to HTTP, MQTT and ROS

A .kbridge.json file 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.

4.7 Bridges

Validates and runs without a window

The same program works from a terminal: karpfen-ide validate <folder> checks a project and karpfen-ide run <folder> runs it, each with a defined exit status.

4.8 Command line

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