# Student Setup Guide

This guide explains how to install Visual Studio Code (VS Code) and Python,
then install this project's Python packages from `requirements.txt`. The
commands below cover Windows, macOS, and Debian/Ubuntu Linux.

Use Python 3.11 or newer. The current `ipykernel` version listed in
`requirements.txt` requires at least Python 3.11.

## 1. Install Visual Studio Code and Python

### Windows

Open PowerShell or Windows Terminal and install VS Code and Python with
WinGet:

```powershell
winget install --id Microsoft.VisualStudioCode --exact
winget install --id Python.Python.3.13 --exact
```

Close and reopen the terminal after installation so that it can find the new
commands. Check that Python is available:

```powershell
python --version
```

If `python` is not recognized, try `py -3.13 --version`.

### macOS

Install Homebrew first if it is not already installed. Then install VS Code
and Python:

```bash
brew install --cask visual-studio-code
brew install python
```

Check that Python is available:

```bash
python3 --version
```

### Debian/Ubuntu Linux

The following commands use `apt`. Install Python, pip, and the virtual
environment support package:

```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv
```

To install VS Code through `apt`, first add Microsoft's package repository and
signing key:

```bash
sudo apt install wget gpg
sudo install -d -m 0755 /etc/apt/keyrings
wget -qO- https://packages.microsoft.com/keys/microsoft.asc \
  | gpg --dearmor \
  | sudo tee /etc/apt/keyrings/packages.microsoft.gpg > /dev/null
echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" \
  | sudo tee /etc/apt/sources.list.d/vscode.list > /dev/null
sudo apt update
sudo apt install code
```

Check that Python is available:

```bash
python3 --version
```

If this reports a version older than 3.11, install a newer Python version
using a method supported by your Linux distribution before continuing. Avoid
replacing the system Python, which may be needed by system tools.

**Linux and macOS commands may differ** depending on your distribution,
operating-system version, and package manager. The Linux commands above are
specifically for Debian/Ubuntu systems using `apt`; other distributions may
use a different package manager and package names. On macOS, Homebrew is one
option, but another package manager may require different commands.

## 2. Install the VS Code extensions

The Python extension provides Python interpreter selection and run controls.
The Jupyter extension enables the Interactive Window for scripts that use
`# %%` cells.

If the `code` command is available in your terminal, install both extensions
with:

```text
code --install-extension ms-python.python
code --install-extension ms-toolsai.jupyter
```

Alternatively, open the Extensions view in VS Code, search for **Python**
(Microsoft) and **Jupyter** (Microsoft), and install them.

## 3. Open the course project

In VS Code, open the project folder: **File → Open Folder...**. Open a terminal
in that folder using **Terminal → New Terminal**. The commands in the next
section assume that the terminal's current directory contains
`requirements.txt`.

## 4. Create a virtual environment and install project packages

A virtual environment keeps this project's packages separate from other
Python projects on your computer. Create it in the project folder as `.venv`.

### Windows

In PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

If the `python` command is unavailable but the Python launcher works, create
the environment with:

```powershell
py -3.13 -m venv .venv
```

Then run the two pip commands above.

### macOS and Linux

In the project folder, run:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```

The last command installs the packages listed in `requirements.txt`, including
the libraries used to build presentations, communicate over serial, and run
interactive Python cells.

## 5. Select the project interpreter in VS Code

1. Open the Command Palette (`Ctrl+Shift+P` on Windows/Linux or
   `Cmd+Shift+P` on macOS).
2. Run **Python: Select Interpreter**.
3. Select the Python interpreter inside this project's `.venv`:
   - Windows: `.venv\Scripts\python.exe`
   - macOS/Linux: `.venv/bin/python`

For an interactive script, open its `.py` file and select **Run Cell** above a
`# %%` cell, or use **Run Current File in Interactive Window** from the
editor's context menu. The first time you run a cell, VS Code may ask you to
select a Python kernel; choose the interpreter from `.venv`.

## Troubleshooting

- If VS Code does not find Python or `pip`, close and reopen VS Code and its
  terminal, then select the `.venv` interpreter again.
- If package installation fails, confirm that the terminal is in the project
  folder and that `requirements.txt` is present there.
- If you change or recreate the virtual environment, rerun the pip install
  command for your operating system.