Merge pull request #4 from lf-lang/docs

Start on reworking lab structure
lf-lang · Jul 16, 2023 · 678d821 · 678d821
2 parents 361501a + a1fb361
commit 678d821
Show file tree

Hide file tree

Showing 15 changed files with 131 additions and 25 deletions.
diff --git a/.gitignore b/.gitignore
@@ -59,6 +59,7 @@ src-gen/
 /include/
 .vscode/
 include/
+.project
 
 # pico setup script location
 pico/

diff --git a/docs/src/Hill.md b/docs/src/Hill.md
@@ -0,0 +1,5 @@
+# Hill Climb
+
+The purpose of this exercise is to program the Pololu robot to execute a specified task, namely to climb a ramp, detect when it reaches the top, turn around, and drive back down the ramp, all without falling off the edge of the ramp.
+
+**FIXME:** From chapter 8 of 3d edition.
diff --git a/docs/src/Installation.md b/docs/src/Installation.md
@@ -0,0 +1,12 @@
+# Installation
+
+**FIXME:** Point to VM.
+
+The labs may also be run directly using a Linux, Mac, or Windows machine, the latter with the Windows Subsystem for Linux (WSL). There are four main components that need to be installed:
+
+- The lf-pico repository, which contains the lab exercises and supporting code.
+- [Lingua Franca](https://lf-lang.org), a coordination language that provides timing, concurrency, and state-machine models. Program logic is written in C.
+- Visual Studio Code (VSCode or just code), an Integrated Development Environment provided by Microsoft that supports Lingua Franca together with C programming and debugging.
+- The Raspberry Pi Pico tools, which include a cross compiler and Software Development Kit (SDK).
+
+The remainder of this section gives instructions for installing each of these components.
diff --git a/docs/src/Interrupts.md b/docs/src/Interrupts.md
@@ -0,0 +1,5 @@
+# Interrupts
+
+The purpose of this lab exercise is to understand how interrupts work. As a side effect, you will also learn how to use a logic analyzer to obtain detailed information about what a microcontroller is doing.
+
+**FIXME:** From chapter 5 of 3d edition.
diff --git a/docs/src/Introduction.md b/docs/src/Introduction.md
@@ -1,6 +1,34 @@
 # Introduction
-This series of labs is a targeted effort to create a minimal set of laboratory
-exercises designed to exposes students to introductory embedded systems concepts.
-The labs however have a focus on cyber physical systems modeling techniques and use
-the lingua franca coordination framework as a lightweight concurrency layer and
-reactor modeling tool. All code is run on the inexpensive raspberry pi pico ❤️.
+This series of labs exposes students to introductory embedded systems concepts.
+The labs focus on cyber physical systems modeling and design.
+They use the [Lingua Franca coordination language](https://lf-lang.org) to provide timing, concurrency, and state-machine modeling (via its modal models).
+All code is run on an inexpensive Raspberry Pi Pico ❤️.
+The labs are designed to be companion exercises for a course based on [Lee and Seshia, _Introduction to Embedded Systems: A Cyber-Physical Systems Approach](https://leeseshia.org), MIT Press, 2017.
+
+## Prerequisites
+These exercises assume that students are reasonably familiar with or able to quickly learn:
+
+- programming in C
+	- [C introduction](https://www.w3schools.com/c/c_intro.php)
+- Unix-like command-line tools
+	- [bash cheat sheet](https://github.com/RehanSaeed/Bash-Cheat-Sheet)
+	- [GitHub git cheat sheet](https://training.github.com/downloads/github-git-cheat-sheet/)
+	- [Unix reference card](https://www.cs.jhu.edu/%7Ejoanne/unixRC.pdf)
+	- [Command line reference](https://ss64.com)
+
+## Acknowlegments
+These labs are derived from several generations of lab exercises for the Berkeley EECS 149/249A course, Introduction to embedded systems. Contributors to the lab design include:
+
+- Joshua Adkins
+- Prabal Dutta
+- Branden Ghena
+- Shromona Ghosh
+- Abhi Gudrala
+- Jeff C. Jensen
+- Eric S. Kim
+- Edward A. Lee
+- Shaokai Lin
+- Marten Lohstroh
+- Sanjit Seshia
+- Trung Tran
+- Matthew Weber
diff --git a/docs/src/LF.md b/docs/src/LF.md
@@ -0,0 +1,5 @@
+# Embedded Programming with LF
+
+The purpose of this lab exercise is to learn to use the [Lingua Franca coordination language](https://lf-lang.org) to program an embedded bare-metal microcontroller, specifically the RPi-Pico on the Pololu robot. You will learn debugging strategies while you create a reusable LED reactor that can be used in other applications to provide information through the robot's LEDs.
+
+**FIXME:** From chapter 2 of 3d edition.
diff --git a/docs/src/Peripherals.md b/docs/src/Peripherals.md
@@ -0,0 +1,5 @@
+# Peripherals and Memory-Mapped I/O
+
+The purpose of this lab exercise is to learn how sensors and actuators are connected to a microcomputer and how the memory system abstraction is used to access and control them.
+
+**FIXME:** From chapter 4 of 3d edition.
diff --git a/docs/src/Robot.md b/docs/src/Robot.md
@@ -0,0 +1,5 @@
+# Robot
+
+The purpose of this exercise is to write software that uses sensor data to maneuver the Pololu robot.
+
+**FIXME:** From chapter 7 of 3d edition.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -3,10 +3,21 @@
 [Introduction](./Introduction.md)
 
 # Setup
-- [Installation](./InstallLFPico.md)
-    - [Lingua Franca](./InstallLF.md)
-    - [VSCode Setup](./InstallVSCode.md)
-    - [Pico Setup](./InstallingPicoTools.md)
-    - [Windows](./WindowsInstallation.md)
+- [Installation](./Installation.md)
+	- [lf-pico](./InstallLFPico.md)
+	- [Lingua Franca](./InstallLF.md)
+	- [VSCode](./InstallVSCode.md)
+	- [Pico Tools](./InstallingPicoTools.md)
+	- [Windows Installation](./WindowsInstallation.md)
 - [Basic Usage](./UsingLFPico.md)
-- [Chapter 1](./Chapter01.md)
+
+# Lab Exercises
+- [Tools and Environments](./Tools.md)
+- [Embedded Programming with LF](./LF.md)
+- [Interfacing with Sensors](./Sensors.md)
+- [Peripherals](./Peripherals.md)
+- [Interrupts](./Interrupts.md)
+- [Timers](./Timers.md)
+- [Robot](./Robot.md)
+- [Hill Climb](./Hill.md)
+- [Wireless](./Wireless.md)
diff --git a/docs/src/Sensors.md b/docs/src/Sensors.md
@@ -0,0 +1,15 @@
+# Interfacing with Sensors
+
+The purpose of this exercise is to learn to read sensor values on a microcontroller and to interpret those values. You will read accelerometer data from a device on the Pololu robot, convert the readings to meaningful units, and use the results to estimate the tilt of the surface on which the robot sits. As a side effect, you will gain experience reading a technical datasheet.
+
+## Prelab
+
+### References
+
+* Chapter 7, Sensors and Actuators, of [Lee and Seshia](https://leeseshia.org)
+* [ST LMS6DSO inertial module datasheet](https://www.pololu.com/file/0J1899/lsm6dso.pdf)
+
+### Questions
+
+
+
diff --git a/docs/src/Timers.md b/docs/src/Timers.md
@@ -0,0 +1,5 @@
+# Timers
+
+In previous lab exercises, Lingua Franca provided a built-in mechanism to control the timing of a programming execution. Ultimately, that mechanism is built using timers, which are peripheral devices associated with the microprocessor that measure time and raise interrupts at specified points in time.
+
+**FIXME:** From chapter 6 of 3d edition.
diff --git a/docs/src/Chapter01.md → docs/src/Tools.md b/docs/src/Chapter01.md → docs/src/Tools.md
@@ -1,10 +1,15 @@
-# Chapter 1
-## Tools and Environments
-This chapter will overview the different tool required for software development on embedded
-systems. Microcontrollers often have limited resources and interaction methods due to being headless devices. The tasks will introduce a common development workflows for these
-platforms.
-
-This section will explore the RP2040 microcontroller, a low cost dual-core arm based chip with various useful and unique hardware peripherals. The chip is embedded in the popular Raspberry Pi Pico and is tailored for education.
+# Tools and Environments
+The purpose of this lab exercise is to familiarize you with the various tools and environments used for embedded software programming. A simple Lingua Franca program, `blink.lf`, is provided for you to experiment with.
+This lab exercise assumes you have followed the [Installation instructions](./Installation.md)
+
+Embedded systems often have limited resources and interaction methods and hence require a different approach for programming.
+Their microprocessors often have no operating system, and are therefore called "bare metal" or "bare iron" machines.
+They often have no keyboard or display connected to them, which can make interaction challenging.
+And they often have limited networking capability.
+In this lab exercise, you will learn to interact with a particular microcontroller, a Raspberry Pi Pico RP2040
+(RPi-Pico), on the [Pololu 3pi+ 2040 robot](https://www.pololu.com/docs/0J86). 
+
+This section will explore the RPi-Pico microcontroller, a low cost dual-core Arm-based chip with various useful and unique hardware peripherals. The chip is embedded in the popular RPi-Pico and is tailored for education.
 
 ## Prelab
 ### Resources

diff --git a/docs/src/UsingLFPico.md b/docs/src/UsingLFPico.md
@@ -14,7 +14,7 @@ The above `lfc` command will also compile the generated code, creating a number
 
 ## Uploading to the RPi-Pico
 
-Plug your RPi-Pico into your USB port and start it in bootloader mode. On the Polulu robot, this is accomplished by holding thbe `B` button while pushing the `Reset` button. Two small green LEDs should be on, and a drive named something like `RPI-RP2` should appear mounted on your computer.
+Plug your RPi-Pico into your USB port and start it in bootloader mode. On the Pololu robot, this is accomplished by holding thbe `B` button while pushing the `Reset` button. Two small green LEDs should be on, and a drive named something like `RPI-RP2` should appear mounted on your computer.
 
 Drag the `Blink.uf2` file from `src-gen/Blink/build` into the `RPI-RP2` disk.
 The Blink program should immediately start running.
@@ -36,8 +36,6 @@ You should choose the GCC for arm-none-eabi option.
 If the vscode instance was setup properly, all necessary plugins will be installed
 and cmake will automatically build. 
 
-**FIXME**: This did not work for me. VS Code tried to use /usr/local/bin/arm-none-eabi-gcc-6.2.1, which did not exist for me. /usr/local/bin/arm-none-eabi-gcc does exist.
-
 **TODO**: Add instructions on how to analyze and automatically flash binaries using the pico-tool
 
 ## Debugging

diff --git a/docs/src/WindowsInstallation.md b/docs/src/WindowsInstallation.md
@@ -1,18 +1,18 @@
 # Notes for Windows Users
 
 ## WSL Setup
-It is recommend to use the Windows Subsystem for Linux (WSL) when developing on a windows machine.
-Use the following [installation](https://learn.microsoft.com/en-us/windows/wsl/connect-usb) instructions to install usb support.
+It is recommend to use the Windows Subsystem for Linux (WSL) when developing on a Windows machine.
+Use the following [installation](https://learn.microsoft.com/en-us/windows/wsl/connect-usb) instructions to install USB support.
 
-To mount the a pico device to the wsl instance, run the following in
+To mount the a Pico device to the WSL instance, run the following in
 an administrator powershell to find the correct bus and attach.
 
 ```
 usbipd wsl list
 usbipd wsl attach --busid <busid>
 ```
 
-In the wsl instance, run the following to verify the device has mounted.
+In the WSL instance, run the following to verify the device has mounted.
 
 ```
 lsusb
@@ -25,3 +25,4 @@ be setup and restart everytime the probe is used.
 ```
 sudo service udev restart && sudo udevadm trigger
 ```
+
diff --git a/docs/src/Wireless.md b/docs/src/Wireless.md
@@ -0,0 +1,5 @@
+# Wireless
+
+The purpose of this lab is to augment the Pololu robot with a Bluetooth Low Energy (BLE) radio link and to use that exchange data with a host computer.
+
+**FIXME:** From chapter 8 of 3d edition.