diff --git a/.gitignore b/.gitignore index dbf48c1d..4d594143 100644 --- a/.gitignore +++ b/.gitignore @@ -14,9 +14,9 @@ **/src-gen/ **/fed-gen/ C/include -Cpp/include -Cpp/share -Cpp/lib +Cpp/**/include +Cpp/**/share +Cpp/**/lib # Created by https://www.toptal.com/developers/gitignore/api/intellij,gradle,eclipse,maven,visualstudiocode # Edit at https://www.toptal.com/developers/gitignore?templates=intellij,gradle,eclipse,maven,visualstudiocode diff --git a/README.md b/README.md index 3ac79ed5..1cc03d58 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,25 @@ [![CI](https://github.com/lf-lang/examples-lingua-franca/actions/workflows/ci.yml/badge.svg)](https://github.com/lf-lang/examples-lingua-franca/actions/workflows/ci.yml) ## 🛝 Lingua Franca Playground -Get to know the language and tinker with some example Lingua Franca programs! +Get to know the [Lingua Franca coordination language](https://lf-lang.org) and browse [example programs](examples/README.md). +To view, edit, and run the programs, you can either run locally on your computer or run in the cloud using either GitHub Codespaces or Gitpod. -### :rocket: Cloud-based dev environment +## 💻 Running Locally +Quick start: + +1. Clone this repo (`git clone git@github.com:lf-lang/playground-lingua-franca.git`) +2. Open with [VS Code](https://code.visualstudio.com) (`code playground-lingua-franca`) +3. Install the [Lingua Franca extension](https://github.com/lf-lang/vscode-lingua-franca) (Ctrl+P and enter `ext install lf-lang.vscode-lingua-franca`). + +Once in VSCode, navigate to [./examples](./examples) and click on any of the `.lf` files to open them into your editor. To build and run, use Ctrl+Shift+P and select `Lingua Franca: Build and Run`. Note: You might need not install additional dependencies in order to successfully build some of the code you find in this repository. For more information, see the [setup-env.bash](./utils/scripts/setup-env.bash) script that we use to configure our Docker-based environments. + + +## :rocket: Running in the Cloud Spin up a fully configured dev environment in the cloud that start in seconds. Any dependencies required for building or running any of the examples are preinstalled. A web-based VS Code editor, preloaded with the Lingua Franca extension, is accessible through either **GitHub Codespaces** or **GitPod**. Simply click on either of the links below to get started. -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&repo=477928779&ref=main&skip_quickstart=true&devcontainer_path=.devcontainer%2Fnightly%2Fdevcontainer.json) +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&repo=477928779&ref=main&skip_quickstart=true&devcontainer_path=.devcontainer%2Fnightly%2Fdevcontainer.json) (NOTE: This can be quite slow to start.) [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/new#https://github.com/lf-lang/playground-lingua-franca/tree/main) @@ -32,9 +43,3 @@ bash ./utils/scripts/setup-lf.bash dev Please note that running these commands will remove the current lingua-franca directory. -## 💻 Local dev environment -1. Clone this repo (`git clone git@github.com:lf-lang/playground-lingua-franca.git`) -2. Open with VS Code (`code playground-lingua-franca`) -3. Install the [Lingua Franca extension](https://github.com/lf-lang/vscode-lingua-franca) (Ctrl+P and enter `ext install lf-lang.vscode-lingua-franca`). - -Once in VSCode, navigate to [./examples](./examples) and click on any of the `.lf` files to open them into your editor. To build and run, use Ctrl+Shift+P and select `Lingua Franca: Build and Run`. Note: You might need not install additional dependencies in order to successfully build some of the code you find in this repository. For more information, see the [setup-env.bash](./utils/scripts/setup-env.bash) script that we use to configure our Docker-based environments. diff --git a/examples/C/README.md b/examples/C/README.md index d28c1f47..9829af28 100644 --- a/examples/C/README.md +++ b/examples/C/README.md @@ -1,16 +1,19 @@ # C Examples -* [Patterns](src/patterns/README.md): Common communication patterns. -* [Deadlines](src/deadlines/README.md): Uses of deadlines in Lingua Franca. + +(in alphabetical order) + * [Car Brake](src/car-brake/README.md): Sketch of ADAS system illustrating the CAL theorem. -* [Rosace](src/rosace/README.md): Aircraft controller illustrating periodic systems with multiple periods. -* [Simulation](src/simulation/README.md): Using Lingua Franca for simulation. +* [Deadlines](src/deadlines/README.md): Uses of deadlines in Lingua Franca. +* [Distributed](src/distributed/README.md): Basic federated hello-world examples. +* [Furuta Pendulum](src/modal_models/FurutaPendulum/README.md): A controller and simulation illustrating a modal reactor. * [Keyboard](src/keyboard/README.md): Responding to keyboard input using ncurses. +* [Leader Election](src/leader-election/README.md): Federated fault-tolerant system with leader election. * [MQTT](src/mqtt/README.md): Interacting with MQTT-based services. -* [Furuta Pendulum](src/modal_models/FurutaPendulum/README.md): A controller and simulation illustrating a modal reactor. +* [Patterns](src/patterns/README.md): Common communication patterns. * [Rhythm](src/rhythm/README.md): Sound generation and terminal user interface demos. +* [Rosace](src/rosace/README.md): Aircraft controller illustrating periodic systems with multiple periods. * [SDV](src/sdv/README.md): Software defined vehicle sketch integrating user input, a web display, and sound. * [Shared Memory](src/shared-memory/README.md): Using shared memory to exchange large data objects between federates. +* [Simulation](src/simulation/README.md): Using Lingua Franca for simulation. * [Train Door](src/train-door/README.md): Train door controller from a verification paper. -* [Distributed](src/distributed/README.md): Basic federated hello-world examples. * [Watchdog](src/watchdog/README.md): Federated illustration of watchdogs. -* [Leader Election](src/leader-election/README.md): Federated fault-tolerant system with leader election. diff --git a/examples/Cpp/AlarmClock/src/AlarmClock.lf b/examples/Cpp/AlarmClock/src/AlarmClock.lf index 27992705..6ffe3051 100644 --- a/examples/Cpp/AlarmClock/src/AlarmClock.lf +++ b/examples/Cpp/AlarmClock/src/AlarmClock.lf @@ -1,29 +1,26 @@ /** - * This is a minimal example of an alarmclock implemeted using the features lingua franca supplies. + * This is a minimal example of an alarm clock implemeted using the features Lingua Franca supplies. * * This is just an extract and simplification from the main project which you can find here: * https://github.com/revol-xut/lf-alarm-clock * * This file contains the networking implementation it is really just an simple socket application - * which parses simple http headers and respondes in text/plain + * which parses simple HTTP headers and responds in text/plain * * @author Tassilo Tanneberer */ target Cpp { - cmake-include: "AlarmClock.cmake", - keepalive: true + cmake-include: "AlarmClock.cmake" } import Network from "./Network.lf" import Clock from "./Clock.lf" -// import Network.lf; -// import Clock.lf; main reactor AlarmClock { clock = new Clock() network = new Network() - network.event -> clock.event // additon of a new event + network.event -> clock.event // addition of a new event network.delete_index -> clock.cancel_by_index clock.event_dump -> network.updated_events diff --git a/examples/Cpp/AlarmClock/src/Clock.lf b/examples/Cpp/AlarmClock/src/Clock.lf index 7eef961d..61a71d5d 100644 --- a/examples/Cpp/AlarmClock/src/Clock.lf +++ b/examples/Cpp/AlarmClock/src/Clock.lf @@ -7,8 +7,7 @@ * Author: Tassilo Tanneberer */ target Cpp { - cmake-include: "AlarmClock.cmake", - keepalive: true + cmake-include: "AlarmClock.cmake" } public preamble {= diff --git a/examples/Cpp/AlarmClock/src/Network.lf b/examples/Cpp/AlarmClock/src/Network.lf index 2455d30d..58bef152 100644 --- a/examples/Cpp/AlarmClock/src/Network.lf +++ b/examples/Cpp/AlarmClock/src/Network.lf @@ -1,17 +1,19 @@ /** - * This is a minimal example of an alarmclock implemeted using the features lingua franca supplies. + * This is a minimal example of an alarm clock implemeted using the features Lingua Franca supplies. * * This is just an extract and simplification from the main project which you can find here: * https://github.com/revol-xut/lf-alarm-clock * * This file contains the networking implementation it is really just an simple socket application - * which parses simple http headers and respondes in text/plain + * which parses simple HTTP headers and responds in text/plain. + * + * This requires [installing Crow](https://crowcpp.org/master/getting_started/setup), which provides + * the HTTP server implementation. * * @author Tassilo Tanneberer */ target Cpp { - cmake-include: "AlarmClock.cmake", - keepalive: true + cmake-include: "AlarmClock.cmake" } public preamble {= diff --git a/examples/Cpp/AlarmClock/src/README.md b/examples/Cpp/AlarmClock/src/README.md index 914f796d..cb8a56e0 100644 --- a/examples/Cpp/AlarmClock/src/README.md +++ b/examples/Cpp/AlarmClock/src/README.md @@ -1,63 +1,29 @@ Lingua Franca Alarm Clock ---------------------------- -**Contact:** +**Author:** -**Main Repository:** [](https://github.com/revol-xut/lf-alarm-clock) - -A small and tiny alarmclock which is written using the scheduling and time features from lingua franca. - -## What you will learn - -- sharing state between reactors -- stopping scheduled events - -## Project +A small alarm clock which is written using the scheduling and time features from Lingua Franca. +This requires [installing Crow](https://crowcpp.org/master/getting_started/setup), which provides the HTTP server implementation. ![Programm Structure](./images/entire_program.png) - -## Building - -**Dependencies:** jdk11, boost, mpg321, Crow - - -```bash - $ lfc ./AlarmClock.lf -``` - -**Building with nix** - -This cross compiles for aarch64. -``` - nix build .#packages.aarch64-linux.lf-alarm-clock -``` - ## Installation By default the AlarmClock expects the sound files to be placed in `~/music/AlarmClock/` you can change this path by editing the `shared_header.cpp` file. Furthermore is it possible to configure paths to other binaries in this file e.g. kill, mpg321 -commands. -### Installing Crow from source - -On most distros, Crow needs to be build and installed from source: +This program requires that you first [install Crow](https://crowcpp.org/master/getting_started/setup). +If you have installed Crow in a location where CMake does not automatically find it, then you can manually specify the location when compiling the LF program as follows: -```bash - $ git clone git@github.com:CrowCpp/Crow.git - $ mkdir Crow/build - $ cd Crow/build - $ cmake -DCMAKE_INSTALL_PREFIX= - $ make install -``` -Note that you can adjust the preferred install location by replacing ``. - -To build the alarm clock using this manually installed version of Crow, simply run: ```bash $ CMAKE_PREFIX_PATH= lfc ./AlarmClock.lf ``` -## Endpoints & Usage +## Usage + +Running the program starts a web server on localhost at port 8680. The commands it understands are: ### /list **GET** Returns a list of upcoming events. @@ -90,7 +56,7 @@ Stops the currently playing alarm sound. $ curl http://0.0.0.0:8680/stop ``` -### /add_event_timestamp **POST** +### /add\_event\_timestamp **POST** Will schedule your alarmclock for the given timestamp Request: @@ -115,7 +81,7 @@ $ curl http://0.0.0.0:8680/add_event_timestamp -X POST -H "Content-Type: text/js Schedules event for given timestamp. -### /add_event_relative **POST** +### /add\_event\_relative **POST** Will schedule a event relative to the current time. Request diff --git a/examples/Cpp/CarBrake/src/README.md b/examples/Cpp/CarBrake/src/README.md index 2eedfa6d..b38e1f25 100644 --- a/examples/Cpp/CarBrake/src/README.md +++ b/examples/Cpp/CarBrake/src/README.md @@ -14,7 +14,7 @@ The second version forsakes consistency altogether using a Lingua Franca physica ## Variant that fixes this -The CarBrake2.lf variant, if made federated, decouples the vision system from the handling of brake pedal actions +The CarBrake2.lf variant decouples the vision system from the handling of brake pedal actions in a way that makes it impossible for the vision system to have any effect on the ability of the other component to make deadlines. The price for this decoupling is added nondeterminacy because the physical connection reassigns time stamps based on the current physical clock. @@ -24,4 +24,8 @@ reassigns time stamps based on the current physical clock. CarBrake CarBrake.lf: Sketch of an ADAS implementation that emphasizes strong consistency at the expense of availability and therefore will miss deadlines when the brake pedal is pushed while image analysis is being performed. + + CarBrake2 + CarBrake.lf: Variant that decouples the vision system from the handling of the brake pedal using a physical connection. + \ No newline at end of file diff --git a/examples/Cpp/CarBrake/src/img/CarBrake.png b/examples/Cpp/CarBrake/src/img/CarBrake.png new file mode 100644 index 00000000..08286dae Binary files /dev/null and b/examples/Cpp/CarBrake/src/img/CarBrake.png differ diff --git a/examples/Cpp/CarBrake/src/img/CarBrake2.png b/examples/Cpp/CarBrake/src/img/CarBrake2.png new file mode 100644 index 00000000..d78cd012 Binary files /dev/null and b/examples/Cpp/CarBrake/src/img/CarBrake2.png differ diff --git a/examples/Cpp/Patterns/README.md b/examples/Cpp/Patterns/README.md new file mode 100644 index 00000000..386d170d --- /dev/null +++ b/examples/Cpp/Patterns/README.md @@ -0,0 +1,6 @@ +# C++ Patterns +A few common design patterns: + +* [Fully Connected Broadcast](src/FullyConnected_00_Broadcast.lf) +* [Fully Connected Addressable](src/FullyConnected_00_Addressable.lf) +* [MatrixConnectedRowsAndColumns](src/MatrixConnectedRowsAndColumns.lf) diff --git a/examples/Cpp/Patterns/src/MatrixConnectedRowsAndColumns.lf b/examples/Cpp/Patterns/src/MatrixConnectedRowsAndColumns.lf index 796b116f..bfb67823 100644 --- a/examples/Cpp/Patterns/src/MatrixConnectedRowsAndColumns.lf +++ b/examples/Cpp/Patterns/src/MatrixConnectedRowsAndColumns.lf @@ -1,6 +1,6 @@ // This pattern creates a matrix of nodes, where each of the nodes can send // messages to all other nodes in the same row or in the same column. Since -// banks in LF are one dimensional, we use hierachy to implement the second +// banks in LF are one dimensional, we use hierarchy to implement the second // dimension. Nodes are organized in Rows which are grouped to form the matrix. target Cpp diff --git a/examples/Cpp/README.md b/examples/Cpp/README.md new file mode 100644 index 00000000..df779532 --- /dev/null +++ b/examples/Cpp/README.md @@ -0,0 +1,7 @@ +# C++ Examples +* [Alarm Clock](AlarmClock/src/README.md) +* [Car Brake](CarBrake/src/README.md) +* [Patterns](Patterns/src/README.md) +* [Reflex Game](ReflexGame/src/ReflexGame.lf) +* [Add](RequestResponse/src/Add.lf) and [AddWithContext](RequestResponse/src/AddWithContext.lf) request-response patterns +* [ROS2](ROS2/src/README.md) diff --git a/examples/Cpp/ROS2/src/README.md b/examples/Cpp/ROS2/src/README.md index 1ed55731..b4fc3833 100644 --- a/examples/Cpp/ROS2/src/README.md +++ b/examples/Cpp/ROS2/src/README.md @@ -1,5 +1,5 @@ -This is an LF reimplementation of the ROS 2 minimal publisher and sunscriber +This is an LF reimplementation of the ROS 2 minimal publisher and subscriber [example](https://docs.ros.org/en/galactic/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html). -It consists of two LF files, MinimalPublisher and MinimalSubscriber, each +It consists of two LF files, [MinimalPublisher.lf](MinimalPublisher.lf) and [MinimalSubscriber.lf](MinimalSubscriber.lf), each implementing the corresponding nodes from the original example. diff --git a/examples/Cpp/ReflexGame/src/ReflexGame.lf b/examples/Cpp/ReflexGame/src/ReflexGame.lf index a68f94cd..3484e079 100644 --- a/examples/Cpp/ReflexGame/src/ReflexGame.lf +++ b/examples/Cpp/ReflexGame/src/ReflexGame.lf @@ -7,7 +7,6 @@ * @author Marten Lohstroh */ target Cpp { - keepalive: true, cmake-include: "ReflexGame.cmake" } diff --git a/examples/README.md b/examples/README.md index eb4913c5..5a81456a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,2 +1,5 @@ # Examples -Our examples are organized by __target__. \ No newline at end of file +Our examples are organized by __target__ language: + +* [C examples](C/README.md) +* [C++ examples](Cpp/README.md) \ No newline at end of file