From 30b9f8afd5aa49d8ca53942f8ea88013c4247ec7 Mon Sep 17 00:00:00 2001
From: Ayke van Laethem <aykevanlaethem@gmail.com>
Date: Tue, 28 May 2024 19:18:30 +0200
Subject: [PATCH] Add a 'tour of TinyGo' with interactive examples in a
 mini-playground

---
 content/_index.md               |   1 +
 content/getting-started/tour.md |   8 ++
 content/tour/_index.md          |  10 ++
 content/tour/blink/_index.md    |   9 ++
 content/tour/blink/external.md  | 131 ++++++++++++++++++++++++++
 content/tour/blink/onboard.md   |  85 +++++++++++++++++
 content/tour/button/_index.md   |   7 ++
 content/tour/button/external.md | 162 ++++++++++++++++++++++++++++++++
 content/tour/button/onboard.md  |  96 +++++++++++++++++++
 layouts/tour/baseof.html        |  83 ++++++++++++++++
 layouts/tour/single.html        |   3 +
 static/playground               |   2 +-
 static/playground.js            |   1 +
 static/tour.js                  | 138 +++++++++++++++++++++++++++
 14 files changed, 735 insertions(+), 1 deletion(-)
 create mode 100644 content/getting-started/tour.md
 create mode 100644 content/tour/_index.md
 create mode 100644 content/tour/blink/_index.md
 create mode 100644 content/tour/blink/external.md
 create mode 100644 content/tour/blink/onboard.md
 create mode 100644 content/tour/button/_index.md
 create mode 100644 content/tour/button/external.md
 create mode 100644 content/tour/button/onboard.md
 create mode 100644 layouts/tour/baseof.html
 create mode 100644 layouts/tour/single.html
 create mode 100644 static/tour.js

diff --git a/content/_index.md b/content/_index.md
index 1a8c9699..f38eebe6 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -48,6 +48,7 @@ Ready to get started? [Click here](getting-started).
 			</div>
 			<div class="col col-auto">
 				<button class="btn btn-secondary playground-btn-flash" disabled>Download binary</button>
+				<a href="/tour/" class="btn btn-link">Tour of TinyGo</a>
 			</div>
 		</div>
 		<textarea placeholder="Loading..." class="form-control input" rows="20" style="font-family: monospace; tab-size: 4" spellcheck="false"></textarea>
diff --git a/content/getting-started/tour.md b/content/getting-started/tour.md
new file mode 100644
index 00000000..dad28aee
--- /dev/null
+++ b/content/getting-started/tour.md
@@ -0,0 +1,8 @@
+---
+title: "Tour"
+type: "docs"
+---
+
+We have a Tour of TinyGo, where you'll learn how to use TinyGo even if you aren't very familiar with programming hardware. You can find it [here]({{< ref "tour/blink/onboard.md" >}}).
+
+The tour assumes you are already familiar with Go. If not, you can follow the [Tour of Go](https://go.dev/tour/) to get started.
diff --git a/content/tour/_index.md b/content/tour/_index.md
new file mode 100644
index 00000000..c8af9c32
--- /dev/null
+++ b/content/tour/_index.md
@@ -0,0 +1,10 @@
+---
+title: "Tour of TinyGo"
+type: "docs"
+---
+
+Welcome to the tour of TinyGo!
+
+This tour assumes you're already familiar with Go. If not, you can go through the [tour of Go](https://go.dev/tour/) to get started.
+
+Every example in this tour is runnable directly in the browser, and most can be downloaded directly to your own electronics board (like the [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333)).
diff --git a/content/tour/blink/_index.md b/content/tour/blink/_index.md
new file mode 100644
index 00000000..9d009db7
--- /dev/null
+++ b/content/tour/blink/_index.md
@@ -0,0 +1,9 @@
+---
+title: "Blinking LED"
+type: "docs"
+description: "Write the \"hello world\" of electronics by making an LED blink!"
+---
+
+This short tour will get you up to speed with blinking a simple LED. This is a great way to start, especially if you've never done electronics before: if the LED blinks you know that everything works to continue in the tour. If you can't get it to work, you might need to do some troubleshooting before you can continue.
+
+This tour also teaches the basics of the TinyGo-specific machine package.
diff --git a/content/tour/blink/external.md b/content/tour/blink/external.md
new file mode 100644
index 00000000..518dde5a
--- /dev/null
+++ b/content/tour/blink/external.md
@@ -0,0 +1,131 @@
+---
+title: "External LED"
+description: "Same blinking LED as in the previous example, but now with an external LED."
+weight: 2
+---
+
+Instead of using an on-board LED, you can also connect a LED to an external pin. Just like you see in the example on the right. It connects an external LED (a red one in this case) to the pin A1 on the board.
+
+The code is almost identical to the previous example. The only difference is this line:
+
+```go
+	led := machine.A1
+```
+
+We've replaced the `led` variable: instead of the on-board LED we're now using the external pin A1.
+
+If you want to try this on a development board, make sure you use the correct wiring:
+
+  * Connect the LED cathode (short lead with flat side) to a resistor of around 220Ω-330Ω. Use at least 150Ω to protect the LED, and use at most 1000Ω to still be able to see the LED (higher values will make the LED very dim).
+  * Connect the other end of the resistor to ground.
+  * Connect the LED anode to pin A1 on the board. See the silkscreen on the board or the graphic in the simulator to know which pin this is.
+
+**Warning**: the resistor is not optional, not using the resistor can destroy the LED and/or your board. The LED might even explode!
+
+The simulation doesn't need this resistor because the virtual LED can't burn out. This simplifies the demo, but remember that the real world is messy and LEDs need a resistor. (There are technical reasons for this, read [this answer](https://electronics.stackexchange.com/questions/28393/why-do-we-need-resistors-in-led) for more details).
+
+<script type="module">
+import { setupTour } from '/tour.js';
+let ledConfig = {
+	type: 'led',
+	humanName: 'External LED',
+	color: [255, 0, 0],
+	svg: 'led-tht-5mm.svg',
+};
+let code = `
+// You can edit this code!
+package main
+
+import (
+	"machine"
+	"time"
+)
+
+func main() {
+	led := machine.LED
+	led.Configure(machine.PinConfig{Mode: machine.PinOutput})
+	for {
+		led.High()
+		time.Sleep(time.Second/2)
+
+		led.Low()
+		time.Sleep(time.Second/2)
+	}
+}`;
+setupTour({
+	boards: {
+		'arduino': {
+			code: code.replace('machine.LED', 'machine.D2 // Arduino Uno'),
+			parts: {
+				led: {
+					config: ledConfig,
+					x: 45,
+					y: -10,
+					rotation: 90,
+				}
+			},
+			wires: [
+				{from: 'main.D2', to: 'led.anode'},
+				{from: 'main.GND#2', to: 'led.cathode'},
+			],
+		},
+		'arduino-nano33': {
+			code: code.replace('machine.LED', 'machine.D2 // Arduino Nano 33 IoT'),
+			parts: {
+				led: {
+					config: ledConfig,
+					x: 12,
+					y: -18,
+				}
+			},
+			wires: [
+				{from: 'main.D2', to: 'led.anode'},
+				{from: 'main.GND#1', to: 'led.cathode'},
+			],
+		},
+		'circuitplay-bluefruit': {
+			code: code.replace('machine.LED', 'machine.A2 // Circuit Playground'),
+			parts: {
+				led: {
+					config: ledConfig,
+					x: 35,
+					y: -4,
+					rotation: 90,
+				}
+			},
+			wires: [
+				{from: 'main.A2', to: 'led.anode'},
+				{from: 'main.GND#1', to: 'led.cathode'},
+			],
+		},
+		'circuitplay-express': {
+			code: code.replace('machine.LED', 'machine.A2 // Circuit Playground'),
+			parts: {
+				led: {
+					config: ledConfig,
+					x: 35,
+					y: -4,
+					rotation: 90,
+				}
+			},
+			wires: [
+				{from: 'main.A2', to: 'led.anode'},
+				{from: 'main.GND#1', to: 'led.cathode'},
+			],
+		},
+		'pico': {
+			code: code.replace('machine.LED', 'machine.GP20 // Raspberry Pi Pico'),
+			parts: {
+				led: {
+					config: ledConfig,
+					x: 16,
+					y: -18,
+				}
+			},
+			wires: [
+				{from: 'main.GP20', to: 'led.anode'},
+				{from: 'main.GND#4', to: 'led.cathode'},
+			],
+		},
+	}});
+</script>
diff --git a/content/tour/blink/onboard.md b/content/tour/blink/onboard.md
new file mode 100644
index 00000000..cfdb6494
--- /dev/null
+++ b/content/tour/blink/onboard.md
@@ -0,0 +1,85 @@
+---
+title: "Blinking LED"
+description: "Hello world of hardware. Blink an on-board LED using your own development board."
+weight: 1
+---
+
+This is the classic "blinking LED" demo you will find in many places. You can find it for the [Arduino IDE](https://docs.arduino.cc/built-in-examples/basics/Blink/) for example. Here is the equivalent in Go.
+
+If you have one of the supported boards (see the dropdown below the code), you can run this code on your own hardware! If you don't, you can just use the simulator that's already running.
+
+Going through the code we can see the following:
+
+```go
+package main
+```
+
+This is just standard Go, so we begin with package main.
+
+```go
+import (
+	"machine"
+	"time"
+)
+```
+
+We import two packages. The time package is the well-known time package which we need to sleep while blinking. However the machine package is new: it is a special standard library package used by TinyGo.
+
+You can think of the machine package like the os or syscall package: it provides an abstraction layer over the underlying hardware and makes code more portable across boards.
+
+```go
+	led := machine.LED
+	led.Configure(machine.PinConfig{Mode: machine.PinOutput})
+```
+
+This configures the LED pin. The constant `LED` is defined in the machine package and represents the pin that is connected to the on-board LED. It is of type `machine.Pin`.
+
+We configure the pin here as an output pin, that is, it outputs either a high or low signal. _High_ or _low_ in this case mean that the output voltage is either somewhere close to the supply voltage (usually 5V or 3.3V) or close to ground (0V).
+
+```go
+	for {
+		led.High()
+		time.Sleep(time.Second/2)
+
+		led.Low()
+		time.Sleep(time.Second/2)
+	}
+```
+
+Here we just blink the LED: we set the output to high for ½ second and then set it to low for ½ second.
+
+Try changing these values and see what happens! For example you can set both to 1 second, or only one of them.
+
+When you play around with the sleep duration, you might discover that "high" and "low" don't actually match the "on" and "off" state of the LED. "high" usually means that the LED is off, while "low" means that it is on. This is because of the way the LED is wired: the anode is connected to the power source (probably via a resistor), and the cathode is connected to the microcontroller pin. This means that when the pin is high (close to the power source) both sides are positive and no current will flow. And when the pin is negative, current will flow from the power source through the LED into the microcontroller. Some boards are wired differently however, and "high" will mean the LED is on while "low" is off.
+
+<script type="module">
+import { setupTour } from '/tour.js';
+setupTour({
+	boards: {
+		'arduino-nano33': {},
+		'arduino': {},
+		'circuitplay-bluefruit': {},
+		'circuitplay-express': {},
+		'pico': {},
+	},
+	code: `
+// You can edit this code!
+package main
+
+import (
+	"machine"
+	"time"
+)
+
+func main() {
+	led := machine.LED
+	led.Configure(machine.PinConfig{Mode: machine.PinOutput})
+	for {
+		led.High()
+		time.Sleep(time.Second/2)
+
+		led.Low()
+		time.Sleep(time.Second/2)
+	}
+}`});
+</script>
diff --git a/content/tour/button/_index.md b/content/tour/button/_index.md
new file mode 100644
index 00000000..3cbe5b91
--- /dev/null
+++ b/content/tour/button/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Reading button inputs"
+description: "Make interactive hardware by responding to button presses."
+type: "docs"
+---
+
+We've seen a blinking LED which provides output, now we're ready for reading from an input.
diff --git a/content/tour/button/external.md b/content/tour/button/external.md
new file mode 100644
index 00000000..1ce3e205
--- /dev/null
+++ b/content/tour/button/external.md
@@ -0,0 +1,162 @@
+---
+title: "External button"
+description: Use an external push button
+weight: 2
+---
+
+This time we'll be blinking an LED, but only when the button is pressed.
+
+If you try it out, you'll see that the LED is initially off (or on), but when you press the button it'll quickly blink. When you release the button, the blinking will stop and it will keep the last state (either on or off).
+
+If you have one of these boards but do not have a pushbutton, you can also use a small wire to connect the given pin (D2/A2/GP2 depending on the board) and then touch a ground point, such as the outside of the USB connector.
+
+
+```go
+	led := machine.LED
+	led.Configure(machine.PinConfig{Mode: machine.PinOutput})
+```
+
+This configures the on-board LED, same as in the [blink example]({{< ref "../blink/onboard.md" >}}).
+
+```go
+	button := machine.D2 // Arduino Uno
+	button.Configure(machine.PinConfig{Mode: machine.PinInputPullup})
+```
+
+This configures the button input. The button pin varies by board, but this time it's always a pullup.
+
+```go
+		// if the button is low (pressed)
+		if !button.Get() {
+			// ...
+		}
+```
+
+Here we check whether the button input is _low_, in other words, whether it is pressed. This is a bit counter intuitive, but that's how it is.
+
+```go
+			// toggle the LED
+			led.Set(!led.Get())
+```
+
+Here we use a trick to toggle the LED: we can actually read the current output value using `led.Get()` and then we can change the value to the opposite value using `led.Set`. This is equivalent to the following:
+
+```go
+			if led.Get() {
+				led.Low()
+			} else {
+				led.High()
+			}
+```
+
+<script type="module">
+import { setupTour } from '/tour.js';
+let buttonConfig = {
+	type: 'pushbutton',
+	humanName: 'Push button',
+	svg: 'pushbutton.svg',
+};
+let code = `
+package main
+
+import (
+	"machine"
+	"time"
+)
+
+func main() {
+	led := machine.LED
+	led.Configure(machine.PinConfig{Mode: machine.PinOutput})
+
+	button := EXT_BUTTON
+	button.Configure(machine.PinConfig{Mode: machine.PinInputPullup})
+
+	for {
+		// if the button is low (pressed)
+		if !button.Get() {
+			// toggle the LED
+			led.Set(!led.Get())
+		}
+
+		// wait a bit, for the blinking effect
+		time.Sleep(100 * time.Millisecond)
+	}
+}`;
+setupTour({
+	boards: {
+		'arduino': {
+			code: code.replace('EXT_BUTTON', 'machine.D2 // Arduino Uno'),
+			parts: {
+				button: {
+					config: buttonConfig,
+					x: 45,
+					y: -10,
+					rotation: 90,
+				},
+			},
+			wires: [
+				{from: 'main.D2', to: 'button.A'},
+				{from: 'main.GND#2', to: 'button.B'},
+			],
+		},
+		'arduino-nano33': {
+			code: code.replace('EXT_BUTTON', 'machine.D2 // Arduino Nano 33 IoT'),
+			parts: {
+				button: {
+					config: buttonConfig,
+					x: 12,
+					y: -18,
+				}
+			},
+			wires: [
+				{from: 'main.D2', to: 'button.A'},
+				{from: 'main.GND#1', to: 'button.B'},
+			],
+		},
+		'circuitplay-bluefruit': {
+			code: code.replace('EXT_BUTTON', 'machine.A2 // Circuit Playground'),
+			parts: {
+				button: {
+					config: buttonConfig,
+					x: 35,
+					y: -4,
+					rotation: 90,
+				}
+			},
+			wires: [
+				{from: 'main.A2', to: 'button.A'},
+				{from: 'main.GND#1', to: 'button.B'},
+			],
+		},
+		'circuitplay-express': {
+			code: code.replace('EXT_BUTTON', 'machine.A2 // Circuit Playground'),
+			parts: {
+				button: {
+					config: buttonConfig,
+					x: 35,
+					y: -4,
+					rotation: 90,
+				}
+			},
+			wires: [
+				{from: 'main.A2', to: 'button.A'},
+				{from: 'main.GND#1', to: 'button.B'},
+			],
+		},
+		'pico': {
+			code: code.replace('EXT_BUTTON', 'machine.GP2 // Raspberry Pi Pico'),
+			parts: {
+				button: {
+					config: buttonConfig,
+					x: -11,
+					y: 18,
+				}
+			},
+			wires: [
+				{from: 'main.GP2', to: 'button.A'},
+				{from: 'main.GND#6', to: 'button.B'},
+			],
+		},
+	},
+});
+</script>
diff --git a/content/tour/button/onboard.md b/content/tour/button/onboard.md
new file mode 100644
index 00000000..9c02c783
--- /dev/null
+++ b/content/tour/button/onboard.md
@@ -0,0 +1,96 @@
+---
+title: "Reading button input"
+description: Learn how to respond to button presses
+weight: 1
+---
+
+Having some output using a LED is nice, but what's even better is if the electronics respond to you!
+
+In this example, we'll use one of the supported boards that have a button on them. If you don't have one of these boards, you can just read the code here and try the next step in the tour where you can connect an external button (or just use a wire).
+
+A lot of code will be familiar from the blinking LED in the previous step, but there are some important differences:
+
+```go
+	button := machine.BUTTONA
+	button.Configure(machine.PinConfig{Mode: machine.PinInputPulldown})
+```
+
+Instead of configuring a LED, we'll configure the pin that's connected to the button labeled 'A' (usually the leftmost button). The mode is `PinInputPullup` or `PinInputPulldown`, the specific mode depends on the board (we'll come back to this later).
+
+```go
+		if button.Get() {
+			println("button input is high")
+		} else {
+			println("button input is low")
+		}
+```
+
+Here we read out the current button state and print whether it was high (`true`) or low (`false`).
+
+You may find that the button pin is normally high but changes to low when pressed, and other boards are the reverse. This depends on how the button is wired, and will be explained later.
+
+## Serial connection
+
+To see the output of the program, you can use a serial monitor. There is a [tutorial for that]({{< ref "serialmonitor.md" >}}). But in short:
+
+  * If you have TinyGo installed, you can open a serial monitor using `tinygo monitor` command. You may need to specify the board, like `tinygo monitor -target=circuitplay-express`.
+  * If you have the Arduino IDE installed, you can use the built-in serial monitor. Make sure to select the right port and to set the baud rate to 115200.
+  * On Linux and MacOS you can use a command-line tool like picocom (which you probably need to install manually).
+  * If you use Windows, Adafruit has a [list of tools you can use](https://learn.adafruit.com/windows-tools-for-the-electrical-engineer/serial-terminal).
+
+## Button wiring
+
+There are many different types of buttons for loads of different applications. The one we're using here is a plain old pushbutton, or a _mometary_, _normally open_ _SPST_ button:
+
+  * _Momentary_ means that you can press it to change state, but when you release it it will revert to its previous state. This is like a keyboard key, and unlike a light switch (which keeps its state).
+  * _Normally open_ means that the connection between the two poles is open (unconnected) when it is not being pressed.
+  * _SPST_ is short for _single-pole, single-throw_ which basically means it's a simple switch with two terminals and two states.
+
+For more information about buttons, please [read this SparkFun article](https://learn.sparkfun.com/tutorials/button-and-switch-basics/all).
+
+For the boards in this tour, one terminal of the button is connected to the pin of the microcontroller and another is connected to either VCC (the power source) or GND (ground, or 0V). This depends on the board.
+
+With this, you can understand that as long as you're pressing the button, the input will be what the button is connected to. For example, if it is connected to GND, you will read `false` as long as you're pressing the button.
+
+But what if you're not pressing the button? It's not connected to ground, but also not to VCC, so what is it? The answer is that it is in an intermediary state called _floating_. Sometimes it reads one way, sometimes another, and it's kind of random which it will do. Even moving your hand around the pin might change the state! Electronic designers will try to avoid this state, by gently pulling the voltage either to ground or to VCC, using a resistor. See the next section.
+
+## Pull mode
+
+To avoid the floating state, microcontrollers have a way to gently pull the voltage one way or another using a built-in resistor. This is why we need either `PinInputPullup` or `PinInputPulldown`. This tells the pin to connect a weak resistor, either between the pin and VCC or between the pin and ground. You can think of it as pulling the voltage either way so it avoids wandering off. Once you press the button, the voltage will be pulled very hard in the other direction so will override the weak pull from the pullup or pulldown resistor.
+
+Sometimes, electronic designers will also put these resistors as physical resistors on the board. This is the case for the Gopher Badge for example. In that case, it is not necessary to specify a pull mode: the hardware already does that. But it won't harm either.
+
+
+<script type="module">
+import { setupTour } from '/tour.js';
+let codePulldown = `
+package main
+
+import (
+	"machine"
+	"time"
+)
+
+func main() {
+	button := machine.BUTTONA
+	button.Configure(machine.PinConfig{Mode: machine.PinInputPulldown})
+
+	for {
+		if button.Get() {
+			println("button input is high")
+		} else {
+			println("button input is low")
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+}`;
+let codePullup = codePulldown.replace('PinInputPulldown', 'PinInputPullup');
+setupTour({
+	boards: {
+		'circuitplay-bluefruit': { code: codePulldown },
+		'circuitplay-express': { code: codePulldown },
+		'gopher-badge': { code: codePullup.replace('BUTTONA', 'BUTTON_A // Gopher Badge uses BUTTON_A') },
+		'microbit': { code: codePullup },
+	},
+});
+</script>
diff --git a/layouts/tour/baseof.html b/layouts/tour/baseof.html
new file mode 100644
index 00000000..fa8372a1
--- /dev/null
+++ b/layouts/tour/baseof.html
@@ -0,0 +1,83 @@
+<!doctype html>
+<html itemscope itemtype="http://schema.org/WebPage"
+    {{- with .Site.Language.LanguageDirection }} dir="{{ . }}" {{- end -}}
+    {{ with .Site.Language.Lang }} lang="{{ . }}" {{- end }} {{/**/ -}}
+    class="no-js">
+  <head>
+    {{ partial "head.html" . }}
+    <link rel="stylesheet" href="/playground/simulator.css">
+  </head>
+  <body class="td-{{ .Kind }}{{ with .Page.Params.body_class }} {{ . }}{{ end }}">
+    <header>
+      {{ partial "navbar.html" . }}
+    </header>
+    <div class="container-fluid td-outer">
+      <div class="td-main">
+        <div class="row flex-xl-nowrap">
+          <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
+            {{ partial "sidebar.html" . }}
+          </aside>
+          <main class="col-12 col-md-9 col-xl-10 ps-md-5" role="main">
+            <div class="row">
+              <div class="col-12 col-xl-6">
+                {{ partial "version-banner.html" . }}
+                {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
+                {{ block "main" . }}{{ end }}
+              </div>
+              <div class="col-12 col-xl-6">
+                <div class="mb-3">
+                  <textarea placeholder="Loading..." class="form-control input" rows="20" style="font-family: monospace; tab-size: 4" spellcheck="false">{{ block "code" .}}{{ end }}</textarea>
+                </div>
+                <div class="row justify-content-end">
+                  <div class="col col-auto">
+                    <div id="board" class="btn-group mb-3">
+                      <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false" title="Select a developer board">...</button>
+                      <div class="dropdown-menu">
+                      </div>
+                    </div>
+                    <button class="btn btn-secondary mb-3 playground-btn-reset" disabled title="Restore code and simulator to the beginning state">Reset</button>
+                    <button class="btn btn-secondary mb-3 playground-btn-flash" disabled title="Download firmware image to flash to a board">Flash</button>
+                  </div>
+                </div>
+                <div class="simulator">
+                  <div class="schematic-buttons">
+                    <button class="schematic-button-pause schematic-button" title="Pause/resume the simulation">
+                      <!-- only one of these two images is visible at a time -->
+                      <img src="/playground/resources/codicon/debug-pause.svg" class="button-img-pause"/>
+                      <img src="/playground/resources/codicon/play.svg" class="button-img-play"/>
+                    </button>
+                  </div>
+                  <svg class="schematic" tabindex="0">
+                    <g class="schematic-wrapper" style="transform: translate(50%, 50%)">
+                      <g class="schematic-parts"></g>
+                      <g class="schematic-wires"></g>
+                    </g>
+                  </svg>
+                  <div class="panels">
+                    <div class="tabbar">
+                      <span class="tab active panel-tab-terminal"><a>Terminal</a></span>
+                      <span class="tab"><a>Properties</a></span>
+                      <span class="tab"><a>Add</a></span>
+                    </div>
+                    <div class="tabcontent active terminal-box">
+                      <textarea class="terminal" readonly></textarea>
+                    </div>
+                    <div class="tabcontent panel-properties">
+                      <div class="content"></div>
+                    </div>
+                    <div class="tabcontent panel-add">
+                      Loading...
+                    </div>
+                  </div>
+                  <div class="schematic-tooltip"></div>
+                </div>
+              </div>
+            </div>
+          </main>
+        </div>
+      </div>
+      {{ partial "footer.html" . }}
+    </div>
+    {{ partial "scripts.html" . }}
+  </body>
+</html>
diff --git a/layouts/tour/single.html b/layouts/tour/single.html
new file mode 100644
index 00000000..49bb662a
--- /dev/null
+++ b/layouts/tour/single.html
@@ -0,0 +1,3 @@
+{{ define "main" }}
+{{ .Render "content" }}
+{{ end }}
diff --git a/static/playground b/static/playground
index d816b8db..dae27dc4 160000
--- a/static/playground
+++ b/static/playground
@@ -1 +1 @@
-Subproject commit d816b8dbbab5f696c7eda677dc9c7d7d2137ae24
+Subproject commit dae27dc4f414b0d5f1cbf73bfc65bd26649f1481
diff --git a/static/playground.js b/static/playground.js
index 6ae916f9..266b77db 100644
--- a/static/playground.js
+++ b/static/playground.js
@@ -25,6 +25,7 @@ addEventListener('DOMContentLoaded', async () => {
 		firmwareButton: firmwareButton,
 		baseURL: new URL('/playground/', document.baseURI),
 		apiURL: PLAYGROUND_API,
+		features: [],
 	});
 	await simulator.setState(state, state.target);
 
diff --git a/static/tour.js b/static/tour.js
new file mode 100644
index 00000000..27857844
--- /dev/null
+++ b/static/tour.js
@@ -0,0 +1,138 @@
+import { Simulator } from './playground/simulator.js';
+
+export { setupTour };
+
+// Note: to test this locally, run the playground server!
+// Run the following in a terminal:
+//
+//    cd static/playground
+//    go run .
+//
+const PLAYGROUND_API = location.hostname == 'localhost' ? 'http://localhost:8080/api' : 'https://playground-bttoqog3vq-uc.a.run.app/api';
+
+const boardNames = {
+	'arduino': 'Arduino Uno',
+	'arduino-nano33': 'Arduino Nano 33 IoT',
+	'circuitplay-bluefruit': 'Adafruit Circuit Playground Bluefruit',
+	'circuitplay-express': 'Adafruit Circuit Playground Express',
+	'gopher-badge': 'Gopher Badge',
+	'microbit': 'BBC micro:bit v1',
+	'pico': 'Raspberry Pi Pico',
+}
+
+// Configure the tour. This works on pages that use the "tour" layout.
+// The config parameter has the following layout:
+//
+//   {
+//     code: '...',                // default code
+//     boards: {
+//       'arduino': {              // board name
+//          code: '...',           // code for this board (optional)
+//          parts: {               // extra parts besides the main part (optional)
+//            led: { ... },        // configuration for this part
+//          },
+//          wires: [               // wires (optional)
+//            {from: 'main.D2', to: 'led.anode'},
+//            {from: 'main.GND#2', to: 'led.cathode'},
+//          ],
+//       },
+//       'microbit': {},           // an empty value also works (and uses defaults)
+//     },
+//   }
+async function setupTour(config) {
+	let boards = [];
+	for (let boardName in config.boards) {
+		boards.push(boardName);
+	}
+	function createState(board) {
+		let state = {
+			target: board,
+			parts: {
+				main: {
+					location: `parts/${board}.json`,
+					x: 0,
+					y: 0,
+				}
+			},
+			wires: [],
+		}
+		let boardConfig = config.boards[board];
+		if (boardConfig.code) {
+			state.code = boardConfig.code.trim();
+		} else {
+			state.code = config.code.trim();
+		}
+		for (let key in boardConfig.parts) {
+			let value = structuredClone(boardConfig.parts[key]);
+			value.x = value.x || 0;
+			value.y = value.y || 0;
+			state.parts[key] = value;
+		}
+		for (let wire of (boardConfig.wires) || []) {
+			state.wires.push(wire);
+		}
+
+		return state;
+	}
+
+	let root = document.querySelector('.simulator');
+	let textarea = document.querySelector('textarea.input');
+	let firmwareButton = document.querySelector('.playground-btn-flash');
+	let resetButton = document.querySelector('.playground-btn-reset');
+
+	// Pick default board.
+	let currentBoard = boards[0];
+	if (localStorage.tinygo_tour_board in config.boards) {
+		// The user previously picked a different board.
+		currentBoard = localStorage.tinygo_tour_board;
+	}
+
+	let boardButton = document.querySelector('#board .dropdown-toggle');
+	let boardMenu = document.querySelector('#board .dropdown-menu');
+	for (let board of boards) {
+		let boardName = boardNames[board] || board;
+		let a = document.createElement('a');
+		a.textContent = boardName;
+		a.classList.add('dropdown-item');
+		if (board === currentBoard) {
+			a.classList.add('active');
+			boardButton.textContent = boardName;
+		}
+		a.href = "";
+		a.addEventListener('click', async e => {
+			// Select a different board.
+			localStorage.tinygo_tour_board = board;
+			e.preventDefault();
+			boardMenu.querySelector('a.dropdown-item.active').classList.remove('active');
+			a.classList.add('active');
+			boardButton.textContent = boardName;
+			currentBoard = board;
+			state = createState(currentBoard);
+			textarea.value = state.code;
+			await simulator.setState(state, currentBoard);
+		})
+		boardMenu.appendChild(a);
+	}
+
+	// Load simulator.
+	let state = createState(currentBoard);
+	textarea.value = state.code;
+	let simulator = new Simulator({
+		root: root,
+		input: textarea,
+		features: [],
+		firmwareButton: firmwareButton,
+		baseURL: new URL('/playground/', document.baseURI),
+		apiURL: PLAYGROUND_API,
+	});
+	await simulator.setState(state, state.target);
+
+	resetButton.disabled = false;
+	resetButton.addEventListener('click', async e => {
+		resetButton.disabled = true;
+		state = createState(currentBoard);
+		textarea.value = state.code;
+		await simulator.setState(state, currentBoard);
+		resetButton.disabled = false;
+	});
+}