lf-lang · lhstrh · Aug 17, 2023 · Aug 16, 2023 · Aug 16, 2023 · Aug 16, 2023
diff --git a/docs/book.toml b/docs/book.toml
@@ -1,5 +1,5 @@
 [book]
-authors = ["Abhi Gundrala and Edward A. Lee"]
+authors = ["Abhi Gundrala", "Edward A. Lee", "Marten Lohstroh"]
 language = "en"
 multilingual = false
 src = "src"

diff --git a/docs/src/GettingStarted.md b/docs/src/GettingStarted.md
@@ -0,0 +1,108 @@
+# Getting Started
+
+Before getting started, please make sure you have satisfied all the [prerequisites](Prerequisites.html).
+
+## Set up GitHub account and SSH key
+If you do not yet have a GitHub account, [create one](https://github.com/signup).
+
+### Set up authentication with GitHub
+In order to push to your repo, you need to authenticate. You can either do this using a public/private key pair through SSH, or use token-based authentication via `gh`, the GitHub command-line interface (installation instructions [here](https://github.com/cli/cli#installation)). If you want to avoid the hassle of installing a private key on it, use `gh` for authentication (recommended; pre-installed on the VM).
+
+#### Using GitHub CLI
+To authenticate with GitHub through its CLI tool, run:
+```bash
+$ gh auth login
+```
+
+#### Using SSH
+In the ⚙️ [Settings](https://github.com/settings/profile) of your [GitHub account](https://github.com), go to 🔑 [SSH and GPG keys](https://github.com/settings/keys) and enter the contents of your `~/.ssh/id_rsa.pub`. If you do not have this file, create it using the following command:
+```bash
+$ ssh-keygen -t rsa -b 4096 -C "your_github@email.com"
+```
+Additional information about setting up public key authentication with GitHub can be found [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+
+> **_Tip for VM users_**
+> 
+> If you prefer not to use `gh` for authentication and are looking for a convenient way to copy your private key onto a VM, consider using [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole). It is preinstalled on the [Ubuntu VM](https://vm.lf-lang.org) prepared for this course.
+
+
+## Create your repository
+Start by creating a new private repository on GitHub based on the [lf-3pi-template](https://github.com/lf-lang/lf-3pi-template) repository, which provides a starting point for students to carry out the exercises in this lab and to develop further applications using the [Raspberry Pi Pico board](https://www.raspberrypi.com/products/raspberry-pi-pico/) and the [Pololu 3pi+ 2040 robot](https://www.pololu.com/docs/0J86).
+
+Navigate to the [lf-3pi-template](https://github.com/lf-lang/lf-3pi-template) repository.  Select "Use this template" and "Create a new repository", as shown here:
+
+<img src="img/3piTemplate.png" alt="Template repo"/>
+
+Give your repo a name and click on "Create repository":
+
+<img src="img/my-3pi.png" alt="new repo"/>
+
+## Clone your repository
+On the command line on your host machine, clone the repo.
+For an SSH-based setup, run:
+
+```bash
+$ git clone git@github.com/<username>/<reponame>.git
+```
+
+Or, for a setup that uses GitHub CLI, run:
+
+```bash
+$ gh repo clone <username>/<reponame>
+```
+
+The template includes [raspberrypi/pico-sdk](https://github.com/raspberrypi/pico-sdk) as a submodule, which itself also has a lot of submodules. We recommend against using the `--recursive` flag because we do not need to recursively clone the submodules inside of `pico-sdk`. Instead, change directory into the root of your clone and run:
+
+```bash
+$ git submodule update --init
+```
+
+If  `pico-sdk` was checked out correctly, `git submodule` will show the hash _without_ a `-` preceding it,
+e.g.: `6a7db34ff63345a7badec79ebea3aaef1712f374 pico-sdk (1.5.1)`.
+
+
+## Configure Nix
+
+To create a reproducible unix shell environment that installs all required dependency applications, we use the [nix](https://nixos.org) package manager, which has support for Linux, macOS, and Windows (via WSL). See [prerequisites](Prerequisites.html) for installation instructions. If you prefer to manage dependencies yourself and not rely on `nix`, follow the [instructions for a non-`nix` setup](Non-Nix.html).
+
+After installation, run the following in the shell to enable the experimental nix flakes feature, which helps to create more consistent builds:
+
+```bash
+$ mkdir -p ~/.config/nix
+$ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
+```
+
+To install the dependencies, run the following in the root of your repository:
+
+```bash
+$ nix develop
+```
+
+This should automatically download and install specific revisions of the `gcc-arm` toolchain, `openocd`, and `picotool`. These packages will be required compiling, flashing and debugging C code for the RP2040.
+(You can alternatively manually [install the Raspberry Pi Pico Tools](Non-Nix.html#install-picotool).)
+
+If you hit any error while running `nix develop`, see troubleshooting instructions below.
+
+> **_Troubleshooting (Linux/WSL)_**
+>
+> You may see an error message like this when running the `nix develop` command:
+> ```bash
+> error:
+>       … while fetching the input 'git+file:///home/osboxes/lf-lang/my-3pi'
+> error:
+>       cannot connect to socket at '/nix/var/nix/daemon-socket/socket': Permission denied
+>
+> ```
+> This means that your user is not a member of the `nix-users` group. To fix this, see [prerequisites](Prerequisites.html#using-nix-on-linuxwsl).
+
+> **_Troubleshooting (ARM/Apple Silicon Mac)_**
+>
+> As of August 1, 2023, the stable version of nix does *not* support ARM/Apple Silicon Macs. You may see an error message like this when running the `nix develop` command:
+> ```
+> is not available on the requested hostPlatform
+> ```
+> You can work around this issue by setting up an environmental variable and running the nix command with an additional argument, `--impure`, like this:
+> ```bash
+> $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
+> $ nix develop --impure
+> ```
diff --git a/docs/src/InstallVSCode.md b/docs/src/InstallVSCode.md
diff --git a/docs/src/Installation.md b/docs/src/Installation.md
diff --git a/docs/src/InstallingPicoTools.md b/docs/src/InstallingPicoTools.md
@@ -1,58 +1 @@
-# Installing Raspberry Pi Pico Tools
-
-If you use Nix as explained in the [installation instructions](./Installation.md), then you should not need to manually install the Raspberry Pi Pico SDK.  But just in case, we provide here instructions adapted from the [Pololu instructions](../lib/pololu-3pi-2040-robot/c/README.md). See also the [GNU ARM installation instructions](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
-
-## Set the PICO\_SDK\_PATH Environment Variable
-
-Set the `PICO_SDK_PATH` environment variable:
-
-```
-export PICO_SDK_PATH=../lf-pico/lib/pico-sdk
-```
-
-where `...` is replaced by the path to the folder where you cloned the `lf-pico` repository.  For convenience, put the above command in your `~/.bash_profile` file so that the environment variable is available to any bash terminal.  Depending on what operating system and terminal you use, you may need to find some other way to set this environment variable.
-
-Note that the `PICO_SDK_PATH` variable is automatically set by `nix develop` in the shell that  it launches (see the [installation instructions](./Installation.md)).
-Moreover, if you use the template repo, then `PICO_SDK_PATH` will be subsequently automatically set whenever you compile any LF file in your repo even if you are not using the shell launched by `nix develop`.
-
-## Install CMake and ARM cross compiler
-
-### On Linux
-
-```
-sudo apt update
-sudo apt install cmake make gcc gcc-arm-none-eabi libnewlib-arm-none-eabi
-```
-Note:  Ubuntu and Debian users might additionally need to also install `libstdc++-arm-none-eabi-newlib`.
-
-### On MacOS
-
-```
-$ brew install cmake make gcc arm-none-eabi-gcc
-$ brew tap ArmMbed/homebrew-formulae
-```
-
-**NOTE:** If you are running on an Apple M1-based Mac you will need to install Rosetta 2 as the Arm compiler is still only compiled for x86 processors and does not have an Arm native version.
-```
-$ /usr/sbin/softwareupdate --install-rosetta --agree-to-license
-```
-
-## Compile Plain C Examples
-
-To make sure your installation has worked, compile the example programs provided with the pico-sdk.  Assuming you have cloned `lf-pico`, then from the `lf-pico` root directory, do this:
-
-```
-cd pico/pico-examples
-mkdir build
-cd build
-cmake ..
-make
-```
-After a while, the build directory will have subdirectories for many examples.  To load the Blink example onto the robot (which simply blinks an LED):
-
-* Plug the robot into the USB port of your computer.
-* Put the robot in BOOTSEL mode by holding the B button while pressing the reset button. You should see an external disk appear with a name like `RPI-RP2`.
-* Open the `RPI-RP2` folder.
-* Drag the `blink.uf2` (in `lib/pico-examples/build/blink`) into the `RPI-RP2` folder.
-
-The robot should immediately start running the program.
+# Non-nix Setup
diff --git a/docs/src/Instructors.md b/docs/src/Instructors.md
@@ -0,0 +1,47 @@
+# Notes for Instructors
+If you are teaching an embedded systems course and would like to use this material, please feel welcome to do so. This page provides resources for preparing a lab based on the software and hardware used in this lab manual.
+
+## Lingua Franca
+These labs rely heavily on the use of [Lingua Franca (LF)](https://lf-lang.org/), an [open-source](https://repo.lf-lang.org/)
+coordination language for designing and building systems that feature
+concurrency, may be reactive and/or time-sensitive, and may be distributed. It
+integrates seamlessly with existing target languages, including C, C++, Python,
+Rust, and TypeScript, and the C target is particularly suited for programming
+embedded systems. LF provides a component-based design methodology that allows
+programmers to take full advantage of existing manufacturer-supplied SDKs and
+legacy software while it equips programmers with powerful abstractions for
+specifying concurrent and timed system behavior.
+
+Writing concurrent software that behaves deterministically and in accordance
+with timing requirements is a difficult an error-prone task when done using
+low-level primitives like threads, interrupts, and hardware timers. Lingua
+Franca provides syntax for defining and composing concurrent components called
+reactors, which react to events deterministically, supported by a dynamic
+runtime scheduling engine. While reactions to events can perform low-level
+interactions with the hardware (for example, to access a sensor or drive an
+actuator), this logic is entirely independent from the orchestration of
+interactions with other software components, which is taken care of
+automatically by the Lingua Franca runtime system. This approach facilitates
+building complex systems out of simple components and provides a more
+disciplined approach to system design.
+
+## The Pololu 3Pi+ 2040 Robots
+The Pololu robot used in these labs is available for purchase [here](https://www.pololu.com/category/300/3pi-plus-2040-robot). The 3pi+ 2040 is a versatile, high-performance, user-programmable robot that measures just 9.7 cm (3.8") in diameter. At its heart is a Raspberry Pi RP2040 microcontroller (like the one on the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/)), a 32-bit dual-core Arm Cortex-M0+ processor running at 125 MHz.
+
+<img src="img/Pololu_RPi3+.png" alt="The Pololu RPi3+ 2040 robot" width="50%"/>
+
+The robot is available as a kit or pre-assembled, and comes in different motor configurations:
+* **30:1 MP 6V Micro Metal Gearmotors** (Standard Edition, _used in this lab_)
+  - up to 1.5 m/s; offer a good combination of speed and controllability
+* **75:1 LP 6V Micro Metal Gearmotors** (Turtle Edition)
+  - up to 0.4 m/s; allow for longer battery life
+* **15:1 HPCB 6V Micro Metal Gearmotors** (Hyper Edition)
+  - up to 4 m/s; difficult to control, easy to damage
+
+For more information, refer to the [docs provided by Pololu](https://www.pololu.com/docs/0j86).
+
+## The Ramp used for the Hill Climb
+Build instructions for a ramp to use with the [Hill Climb](Hill.html) exercise will be posted here soon. The robots are very light-weight, however, so even a very flimsy ramp constructed using cardboard will probably do.
+
+## Solutions
+We can provide access to solutions of the lab exercises upon request. Please contact `eal` `at` `berkeley.edu` to place an inquiry.
diff --git a/docs/src/Interrupts.md b/docs/src/Interrupts.md
@@ -25,7 +25,7 @@ factors may impact the latency of handling this interrupt?
 
 4. One issue with nested interrupts is that an ISR may have to be carefully designed to be **reentrant**.  A function is reentrant if it can be safely called again while it is in the middle of an execution. You are given the following function:
 
-    ```
+```
     void send_to_radio(char* data) {
         static char data_to_send[10];
         memcpy(data_to_send, data, 10)
@@ -35,11 +35,10 @@ factors may impact the latency of handling this interrupt?
     }
 ```
 
-    1. Is the function `send_to_radio` reentrant? Why or why not? **Hint:** Make
+1. Is the function `send_to_radio` reentrant? Why or why not? **Hint:** Make
 sure to understand static variables in C.
 
-    2. What is one simple way to make the function reentrant?
-
+2. What is one simple way to make the function reentrant?
 
 ## 6.2. Interrupt Service Routine
 

diff --git a/docs/src/Non-Nix.md b/docs/src/Non-Nix.md
@@ -0,0 +1,52 @@
+# Non-`nix` Setup
+
+If you use `nix` as explained in the [getting started instructions](./GettingStarted.html#configure-nix), then you should not need to manually install the Raspberry Pi Pico SDK, C library and math library compiled for bare metal Cortex ARM, or the GNU Arm Embedded Toolchain for cross-compilation. To install these manually and not rely on `nix` to provide these dependencies, follow these instructions.
+
+## Install Raspberry Pi Pico SDK
+
+Clone the [raspberrypi/pico-sdk](https://github.com/raspberrypi/pico-sdk) repository and set the `PICO_SDK_PATH` environment variable:
+
+```bash
+$ git clone https://github.com/raspberrypi/pico-sdk.git
+$ cd pico-sdk
+$ export PICO_SDK_PATH=`pwd`
+```
+
+For convenience, set `PICO_SDK_PATH` in your `~/.bash_profile` file so that the environment variable is available to any bash terminal. After completing the steps above, this can be done as follows:
+
+```bash
+$ echo "export PICO_SDK_PATH=$PICO_SDK_PATH" >> ~/.bash_profile
+```
+
+Depending on what operating system and terminal you use, you may need to find some other way to set this environment variable.
+
+## Install `picotool`
+To build and install `picotool` from source, refer to the [https://github.com/raspberrypi/picotool](raspberrypi/picotool) repository.
+
+## Install CMake, Standard C Library, ARM cross compiler
+
+See also the [GNU ARM installation instructions](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
+
+### On Ubuntu
+
+```
+sudo apt update
+sudo apt install cmake make gcc gcc-arm-none-eabi libnewlib-arm-none-eabi
+```
+**Note:** It might be additionally needed to also install `libstdc++-arm-none-eabi-newlib`.
+
+### On macOS
+
+```
+$ brew install cmake make gcc arm-none-eabi-gcc
+$ brew tap ArmMbed/homebrew-formulae
+```
+
+**NOTE:** If you are running on an Apple M1-based Mac you will need to install Rosetta 2 as the Arm compiler is still only compiled for x86 processors and does not have an Arm native version.
+```
+$ /usr/sbin/softwareupdate --install-rosetta --agree-to-license
+```
+
+## Perform a Smoke Test
+
+To make sure your installation has worked, follow the instructions [here](Tools.html#using-the-command-line).