STEM with Raspberry Pi Hardware: Teachers Guide¶

Welcome to the teacher's guide for Learning STEM with Raspberry Pi Hardware: An Encyclopedia of Hands-On Projects Across the Raspberry Pi Hardware Family. This guide explains every feature of the textbook, how to use it in your classroom, and how to customize it for your students. No prior technical knowledge is assumed — every technical term is defined before it is used.

About This Interactive Intelligent Textbook¶

What is an Intelligent Textbook?¶

An intelligent textbook is a digital textbook that goes beyond static text and images. It includes interactive simulations, self-grading quizzes, a searchable glossary, and a structured map of how concepts relate to each other. The goal is to give students a richer, more engaging learning experience than a traditional printed textbook.

The Five Levels of Intelligent Textbooks¶

Not all digital textbooks are created equal. We categorize intelligent textbooks into five levels based on how interactive and adaptive they are:

Level	Name	Description	Example Features
Level 1	Static Digital	A PDF or basic web version of a print textbook	Text and images only, no interactivity
Level 2	Interactive	Adds interactive elements like simulations, quizzes, and searchable glossaries	MicroSims, self-check quizzes, concept search
Level 3	Adaptive	Adjusts content based on student performance	Personalized learning paths, difficulty adjustment
Level 4	AI-Assisted	Includes an AI tutor that can answer student questions	Chatbot integration, automated feedback
Level 5	Fully Adaptive AI	Continuously learns from student interactions and optimizes the experience	Real-time content generation, predictive analytics

This textbook is a Level 2 Intelligent Textbook. It combines nearly 100 interactive MicroSims, self-check quizzes, a searchable glossary and FAQ, a concept-dependency learning graph, and a mascot-guided narrative — but it does not yet adjust content to individual student performance or include an AI tutor.

What Makes This Textbook Different¶

Interactive MicroSims let students manipulate models directly in their browser — no software installation required
Encyclopedia structure — 20 chapters organized into five ascending hardware-cost tiers, so you can dip in wherever fits your budget and available class time rather than reading cover to cover
Debugging-first mindset — every project treats wiring mistakes and bugs as expected, teachable moments rather than failures
Learning graph — a visual map showing how all 531 concepts connect and build on each other across every hardware tier
Berry the Raspberry — a friendly mascot character (called a "pedagogical agent") who guides students through each chapter with tips, encouragement, and key insights
Completely free and open source — licensed under Creative Commons for non-commercial use

Using the Chapters¶

Chapter Structure¶

The textbook contains 20 chapters organized around five ascending hardware-cost tiers. Students and teachers do not need to read them in strict order — the book is designed to be used like an encyclopedia — but concepts within a tier do build on earlier tiers:

Chapters	Topic Area
1–3	Foundations — computational thinking and debugging, choosing the right Raspberry Pi product, breadboard/GPIO/electrical fundamentals
4–6	Tier 1: Pico on a Breadboard (~$4–20/kit) — digital I/O and PWM, NeoPixel LED art, buttons/photoresistors/analog sensors
7–8	Tier 2: Pico-Based STEM Robot Kits (~$19–35) — no-display robot, OLED display and expressive behaviors
9–10	Tier 3: Specialty Pico Projects — clocks/watches/display drivers, wireless communication with the Pico W
11–13	Tier 4: Raspberry Pi 500+ Keyboard Computer — Linux desktop and terminal, file management/packages/remote access, per-key RGB keyboard lighting
14–18	Tier 5: Raspberry Pi 5 and Edge AI — Pi 5 hardware, software dev environment, the AI HAT+ and neural networks, real-time object detection, audio signal processing
19–20	Capstone and Classroom Logistics — budgeting/sourcing/classroom logistics, capstone design challenges that combine multiple tiers

What Each Chapter Contains¶

Every chapter follows a consistent structure:

YAML front matter — Metadata at the top of each chapter file (title, description, version). Students don't see this; it's used by search engines and the website builder.
Summary — A brief overview of what the chapter covers and what students will learn.
Concepts covered — A numbered list of the specific concepts addressed in the chapter, drawn from the learning graph (typically 20–30 per chapter).
Prerequisites — A note on what prior knowledge the chapter assumes, referencing the course description.
Welcome from Berry — A mascot admonition that introduces the chapter topic in Berry's friendly, encouraging voice.
Main content — The core instructional material, written at an accessible reading level with every technical term defined on first use. Includes tables, real-world examples, and embedded MicroSims.
Mascot admonitions — Throughout the chapter, Berry appears several more times to highlight key insights, offer practical tips, and warn about common mistakes or safety considerations.
Bringing It Together — A closing section connecting the chapter's ideas to what comes next in the book, ending with a celebration admonition from Berry.

The Quiz and Annotated References for each chapter are separate pages, linked from the chapter's navigation entry and from a link at the bottom of the chapter itself.

Suggested Classroom Use¶

Before class: Assign the chapter as reading homework. The MicroSims keep students engaged during independent reading.
During class: Use the MicroSims on a projector for whole-class demonstrations. Ask students to predict what will happen when you change a slider, then test their predictions.
After class: Use the quiz for a quick formative assessment, and point students to the references for further reading.
Pacing: Chapters vary in length and hands-on build time depending on hardware tier — a breadboard chapter may fit in one class period, while a full robot build or capstone project may take several. Use the price tier and hardware requirements stated at the top of each chapter to plan ahead.

Using the MicroSims¶

What is a MicroSim?¶

A MicroSim (short for "micro-simulation") is a small, interactive simulation that runs directly in a web browser. Students don't need to install any software — MicroSims work on any device with a modern web browser (Chrome, Firefox, Safari, Edge).

Each MicroSim lets students manipulate one or more variables (using sliders, buttons, or drag-and-drop) and immediately see how the model responds. This "learn by doing" approach helps students build intuition for abstract concepts like PWM duty cycles, I2C addressing, or a neural network's confidence score.

How MicroSims Are Embedded¶

MicroSims appear within chapter text as rectangular interactive areas. They are embedded using iframes — a web technology that displays one web page inside another. You don't need to understand how iframes work; just know that the MicroSims load automatically when students view the chapter page.

Types of MicroSims¶

The textbook includes nearly 100 MicroSims built with different visualization technologies:

Technology	What It's Good For	Example MicroSims
p5.js	Interactive animations, circuit builders, and code tracers with sliders and buttons	Ohm's Law Circuit Simulator, NeoPixel Animation Studio, Blink an LED Code Tracer
Chart.js	Bar charts and line charts for comparing costs and performance	Cost Per Student by Hardware Tier, Inference Latency and Frames Per Second Benchmark Chart, RAM Shortage Price Impact
vis-network	Network diagrams showing connections and dependencies	Learning Graph Viewer, BLE GATT Structure Explorer, Behavior Tree Priority Explorer

Tips for Using MicroSims in Class¶

Project them on a screen — MicroSims are designed to be visible on a projector. Have students call out predictions before you move a slider.
Let students explore independently — After a demonstration, give students 5–10 minutes to experiment on their own devices.
Use the "Reset" button — Most MicroSims have a reset button. Encourage students to reset and try different scenarios.
Connect to the text — Each MicroSim is placed near the concept it illustrates. After exploring the sim, have students re-read the surrounding text.
Offline access — MicroSims require an internet connection unless you have built the site locally (see "Customizing Your Own Textbook" below).

Embed Any MicroSim on Your Own Page

You can add any MicroSim to any web page — a Google Site, a WordPress blog, an LMS like Canvas or Schoology, or even a plain HTML file. Just paste a single line of HTML, replacing YOUR-MICROSIM-NAME with the name of any MicroSim from the MicroSims list:

<iframe src="https://dmccreary.github.io/raspberry-pi-stem/sims/YOUR-MICROSIM-NAME/main.html"
    width="100%" height="450px"
    scrolling="no">
</iframe>

That's it — one line of code and your students have an interactive simulation on any page you control.

MicroSim Specifications¶

Within each chapter, you'll find a collapsible details section below each MicroSim labeled with its name. Click to expand and see the full specification, including the Bloom's Taxonomy level it targets, the learning objective, the interactive controls available, and the default parameters when it loads. These specifications are useful for lesson planning and for understanding the pedagogical intent behind each simulation.

Using the Glossary¶

What is the Glossary?¶

The glossary is an alphabetical list of all key terms used in the textbook — 531 entries in all — each with a precise, concise definition, a worked example, and links to related terms. It serves as a quick-reference dictionary for students encountering unfamiliar vocabulary.

How to Access the Glossary¶

Click "Glossary" in the left navigation sidebar from any page
Use the browser's built-in search (Ctrl+F on Windows/Linux, Cmd+F on Mac) to find a specific term on the glossary page
Use the site-wide search bar at the top of any page to search for a term across the entire textbook

Tips for Using the Glossary in Class¶

Vocabulary preview — Before starting a new chapter, have students look up the key terms in the glossary to build familiarity.
Definition matching — Create a warm-up activity where students match glossary definitions to terms from the current chapter.
Student-generated definitions — After reading a chapter, have students write their own definitions, then compare with the glossary.
Glossary quizzes — Use glossary terms for quick formative assessments (flash cards, quiz games, etc.).

Using the FAQ¶

What is the FAQ?¶

The FAQ (Frequently Asked Questions) is a curated list of common questions students and educators ask about the book — from "Do I need to buy every hardware tier?" to "What is the first project I'll build?" — organized by topic, with clear, concise answers.

Tips for Using the FAQ in Class¶

Discussion starters — Pick 2–3 FAQ questions at the start of class and have students discuss before revealing the answer.
Homework support — Point students to the FAQ when they have questions outside of class hours.
Parent/administrator briefing — The "Getting Started" section of the FAQ is a quick way to explain the book's scope and cost to a parent, principal, or purchasing committee.
Test review — Students can use the FAQ as a study guide before assessments.

Using the Quizzes¶

What Are the Quizzes?¶

Each chapter has an accompanying quiz page with multiple-choice questions designed for self-assessment. Quizzes test understanding of the concepts covered in that chapter and are aligned to specific items from the learning graph.

How Quizzes Work¶

Quizzes are accessed by clicking the "Quiz" link under each chapter in the left navigation
Each quiz contains 10 multiple-choice questions at varying Bloom's Taxonomy levels
Questions are presented as expandable sections — students can click to reveal the answer and explanation after attempting the question
Quizzes are not graded automatically — they are designed as formative self-check tools, not summative assessments

Tips for Using Quizzes in Class¶

Exit tickets — Have students complete the quiz at the end of a class period as a quick check for understanding.
Pre-reading check — Assign the quiz before the chapter to see what students already know (diagnostic assessment).
Post-reading review — Use the quiz after reading to identify concepts that need re-teaching.
Collaborative quiz — Have students work in pairs to discuss each question before revealing the answer.
Custom assessments — Use the quiz questions as a bank to create your own tests. The questions are openly licensed (see "Understanding the License" below).

Bloom's Taxonomy Levels¶

Each quiz question is tagged with a Bloom's Taxonomy level. Bloom's Taxonomy is a framework that classifies thinking skills from simple to complex:

Level	Name	What It Means	Example Verb
L1	Remember	Recall facts and definitions	Define, list, name
L2	Understand	Explain concepts in your own words	Explain, describe, compare
L3	Apply	Use concepts to solve problems	Calculate, demonstrate, solve
L4	Analyze	Break down and examine relationships	Differentiate, organize, compare
L5	Evaluate	Make judgments based on criteria	Assess, argue, justify
L6	Create	Produce original work or solutions	Design, construct, propose

The book's own learning outcomes (see the Course Description) are tagged the same way, and separately flag which outcomes apply to [Student] readers versus [Educator] readers — for example, an educator-specific Analyze-level outcome is "analyze a classroom's existing equipment and budget to determine which hardware tier(s) are currently feasible to adopt."

Using the References¶

What Are the References?¶

Each chapter has an accompanying references page with a curated list of approximately 10 high-quality sources that students can use for further reading. References prioritize Wikipedia articles for accessibility and reliability, supplemented by authoritative books and research papers.

How References Are Organized¶

Each reference includes:

Title — The name of the source
URL — A clickable link to the source
Relevance — A brief description of why this source is useful and how it connects to the chapter content

A Note About Link Rot¶

Link rot is when a web link (URL) stops working because the page has been moved, renamed, or deleted. This is a common problem with any resource that links to external websites. While we prioritize Wikipedia (which has very stable URLs), some links may become outdated over time.

If you or your students encounter a broken link:

Try searching for the article title on the source website
Use the Wayback Machine to find archived versions of the page
Report the broken link using GitHub Issues (see "Feedback" below)

The Learning Graph¶

What is a Learning Graph?¶

A learning graph is a visual map showing how concepts in the textbook depend on each other. It is structured as a DAG (Directed Acyclic Graph) — a diagram where arrows show which concepts must be understood before others. This book's learning graph contains 531 concepts organized into 12 taxonomy categories spanning all five hardware tiers.

How Teachers Can Use the Learning Graph¶

Prerequisite checking — Before teaching a concept, verify that students have covered its prerequisites
Remediation — If a student struggles with a concept, trace back to its prerequisites to find the gap
Curriculum mapping — Compare the learning graph to your existing syllabus to identify coverage gaps
Enrichment — Advanced students can explore concepts ahead of the current chapter by following the graph forward

The interactive Learning Graph Viewer is available in the "Learning Graph" section of the left navigation, alongside quality reports on the graph, glossary, and FAQ coverage.

Berry the Raspberry: The Book's Pedagogical Agent¶

What is a Pedagogical Agent?¶

A pedagogical agent is a character that appears throughout a textbook to guide students. Research shows that pedagogical agents improve student engagement and perception of learning — a phenomenon called the persona effect.

Meet Berry¶

Berry is a raspberry with a circuit-board leaf cap and a tool belt — a fruit built for building electronics. Berry's catchphrase, "Let's build something!", reflects the book's hands-on, hardware-first philosophy and its overall theme, "STEM is Our Superpower!" Bugs and wiring mistakes are treated as part of the fun — the "training montage" where a student's next superpower gets earned, not a failure.

Berry appears as colored callout boxes (called admonitions) throughout each chapter — a welcome at the start, a handful of thinking/tip/warning/encourage moments through the body, and a celebration at the end. Berry appears no more than 5–6 times per chapter to avoid overuse, and is never placed in back-to-back callouts.

Note that this teacher's guide, and other instructor-facing pages, intentionally do not use Berry admonitions — student-facing mascot content is reserved for the chapters, quizzes, and FAQ.

Tips for Teachers¶

Read Berry's tips aloud — They're written in a conversational, hands-on tone that works well when spoken.
Use as discussion prompts — Berry's "thinking" admonitions highlight the most important insight in each chapter section.
Encourage struggling students — Point students to Berry's "encourage" admonitions when they're frustrated with a wiring or debugging problem.

Learning STEM with Raspberry Pi Hardware is one book in a much larger effort to make hands-on, AI-assisted STEM education free and open to every classroom. If you want to go deeper on a specific hardware family, or understand how a book like this one gets built, these related resources are a good next stop:

Companion hardware-tier books — Moving Rainbow, STEM Robots, Clocks and Watches, Robot Faces, AI Racing League, and others each go deep on a single hardware family where this book goes wide. See the About page for the full list with pricing and scope notes.
Learning Graphs — Explains the concept-dependency-graph methodology used to sequence this book's 531 concepts, describe learner progression, and support AI-driven personalization of educational content. Useful if you want to understand why the chapters are ordered the way they are, or build a learning graph for your own course.
Claude Skills for Intelligent Textbooks — Documents the reusable, AI-agent "skills" used to generate this book's chapters, quizzes, glossary, FAQ, and MicroSims. Useful if you or your students want to see how the content pipeline works, or build your own skill-driven textbook.
Building Intelligent Textbooks With AI — A step-by-step guide to building intelligent textbooks like this one using open standards, MkDocs, and the Material theme. Its case studies gallery showcases nearly 100 other intelligent textbooks built with these same methods, across subjects from quantum computing to U.S. history.

Feedback¶

Reporting Issues and Suggestions¶

This textbook is an open-source project hosted on GitHub, a website where software and content projects are developed collaboratively. You don't need to understand programming to report a problem or suggest an improvement.

What is a GitHub Issue?¶

A GitHub Issue is like a support ticket — it's a way to report a bug, suggest an improvement, or ask a question. Each issue gets a unique number and can be discussed by the project team and community.

How to Submit Feedback¶

Go to the textbook's GitHub repository: dmccreary/raspberry-pi-stem
Click the "Issues" tab at the top of the page
Click the green "New issue" button
Give your issue a clear title (e.g., "Broken link in Chapter 5 references" or "Suggestion: Add MicroSim for topic X")
In the description, provide as much detail as possible:
- Which page or chapter has the problem
- What you expected to see vs. what you actually see
- Your browser and device (if relevant)
Click "Submit new issue"

You will need a free GitHub account to submit issues. If you prefer not to create an account, you can email feedback to the author using the contact page.

Types of Feedback Welcome¶

Typos and errors — factual mistakes, spelling errors, broken formatting
Broken links — URLs that no longer work
MicroSim bugs — simulations that don't load or behave unexpectedly
Content suggestions — topics that should be covered, examples that could be improved
Accessibility issues — content that is difficult to read or navigate for students with disabilities

Understanding the License¶

What is a Creative Commons License?¶

A license is a legal document that explains what others are allowed to do with a piece of work. A Creative Commons (CC) license is a standardized, easy-to-understand license used for educational and creative content. It tells you exactly what permissions you have without needing a lawyer.

This Textbook's License¶

This textbook uses the CC BY-NC-SA 4.0 license. Here's what each part means:

Code	Full Name	What It Means
CC	Creative Commons	A standard open license
BY	Attribution	You must give credit to the original author
NC	Non-Commercial	You cannot use the material to make money
SA	Share-Alike	If you modify the material, you must share it under the same license
4.0	Version 4.0	The version of the license (the current standard)

What You CAN Do¶

Copy the entire textbook or individual chapters for your students
Share the textbook link with other teachers, students, or parents
Print chapters for classroom use
Modify the content — add your own examples, remove sections, change the order
Translate the content into other languages
Create derivative works — build your own version of the textbook based on this one

What You CANNOT Do¶

Sell the textbook or charge students for access
Remove attribution — you must credit the original author (Dan McCreary)
Use a different license — if you modify and share, it must remain CC BY-NC-SA 4.0
Claim it as your own work — the attribution requirement means you must acknowledge the original source

For the full legal text, see the Creative Commons License page.

Customizing Your Own Textbook¶

One of the most powerful features of this textbook is that you can create your own customized version. This section explains how, step by step.

Key Technical Terms¶

Before we begin, here are some terms you'll need to understand:

Repository (repo) — A folder on GitHub that contains all the files for a project. Think of it as the project's home directory.
Git — A version control tool that tracks changes to files. It lets you see what changed, when, and by whom.
Clone — Making a complete copy of a repository on your own computer.
Fork — Making a complete copy of a repository on your own GitHub account (stays on GitHub, not your computer).
MkDocs — The software that converts the textbook's markdown files into a website. You don't need to learn MkDocs deeply — just enough to make basic changes.
Markdown — A simple text formatting language. If you can write an email, you can write Markdown. **bold** makes bold, # Heading makes a heading, and - makes a bullet point.
mkdocs.yml — The main configuration file for the textbook website. It controls the site title, navigation structure, colors, and which features are enabled.

Step 1: Create a GitHub Account¶

If you don't already have one, go to github.com and create a free account.

Step 2: Fork or Clone the Repository¶

Option A: Fork (easier, stays on GitHub)

Go to dmccreary/raspberry-pi-stem
Click the "Fork" button in the upper-right corner
This creates a copy in your own GitHub account that you can edit

Option B: Clone (more control, works on your computer)

Install Git on your computer (git-scm.com)
Open a terminal (Command Prompt on Windows, Terminal on Mac)
Run this command:

git clone https://github.com/dmccreary/raspberry-pi-stem.git

This downloads the entire textbook to your computer.

Step 3: Make Changes¶

All content files are in the docs/ folder. They are written in Markdown (.md files) — plain text files with simple formatting. You can edit them with any text editor.

Changing the Title and Description¶

Open mkdocs.yml and edit these lines:

site_name: "Your Custom Textbook Title"
site_description: "Your description here"
site_author: "Your Name"

Changing the Colors¶

In mkdocs.yml, find the palette section:

theme:
  palette:
    primary: 'indigo'    # Change to: blue, red, purple, teal, etc.
    accent: 'orange'     # Change the accent color

MkDocs Material supports these primary colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey.

Changing the Mascot¶

Berry's images live in docs/img/mascot/. Replace the pose files (or swap in your own character) and update docs/img/mascot/character-sheet.md so future AI-generated content stays consistent with your new mascot's name, colors, and voice.

Step 4: Preview Your Changes Locally¶

Install Python (version 3.8 or newer) from python.org
Install MkDocs and the Material theme:

pip install mkdocs mkdocs-material

Navigate to the project folder and start the preview server:

cd raspberry-pi-stem
mkdocs serve

Open your browser to http://127.0.0.1:8000/raspberry-pi-stem/ to see your customized version

The preview server watches for file changes. When you edit and save a Markdown file, the page automatically refreshes in your browser.

Step 5: Publish Your Version¶

To publish your customized textbook as a free website using GitHub Pages:

mkdocs gh-deploy

This command builds the website and publishes it to https://YOUR-USERNAME.github.io/raspberry-pi-stem/. The process takes about 1–2 minutes.

Customizing Your Analytics¶

What is Web Analytics?¶

Web analytics is the process of measuring how visitors use a website — which pages they visit, how long they stay, and where they come from. For an educational textbook, analytics can help you understand which chapters students read most, which MicroSims they interact with, and where they might be struggling.

Setting Up Google Analytics¶

This textbook is built to support Google Analytics — a free service from Google that tracks website visits — but it is not yet configured for this book. If you fork or clone this project, you can set up your own:

Go to analytics.google.com and sign in with a Google account
Create a new property (Google's term for a tracked website)
Google will give you a Measurement ID — a code that looks like G-XXXXXXXXXX
In your mkdocs.yml, uncomment and update this section:

extra:
  analytics:
    provider: google
    property: G-YOUR-MEASUREMENT-ID

Rebuild and deploy your site. Analytics data will start appearing within 24–48 hours.

What You Can Learn from Analytics¶

Which chapters are most/least visited — helps you identify where students might be skipping content
Average time on page — longer times may indicate engagement or confusion
Device breakdown — what percentage of students use phones vs. computers
Geographic distribution — where your students are accessing from
Search terms — what students search for on your site

xAPI Monitoring (Advanced)¶

xAPI (Experience API, also called "Tin Can API") is an advanced standard for tracking detailed learning activities — not just page views, but specific interactions like "student moved a slider to position X" or "student answered quiz question 3 correctly."

What is an LRS?¶

An LRS (Learning Record Store) is a database that stores xAPI learning records. Think of it as a specialized analytics system designed specifically for education. If you use an LRS, you can track granular student learning data.

Important: Regulatory Considerations¶

Before collecting student-specific learning data, be aware of these regulations:

FERPA (Family Educational Rights and Privacy Act) — U.S. federal law that protects student education records. If you collect data that can identify individual students, you must comply with FERPA.
COPPA (Children's Online Privacy Protection Act) — U.S. federal law that applies to children under 13. Given this book's upper-elementary-and-up audience, additional restrictions may apply to some of your students.
State laws — Many U.S. states have additional student privacy laws.
GDPR (General Data Protection Regulation) — European Union law that applies if any of your students are in the EU.

Recommendation: The Google Analytics setup described above is anonymous by default — it tracks aggregate page views, not individual students. This is the safest approach. If you want individual student tracking via xAPI, consult your school district's data privacy officer before proceeding.