A Raspberry Pi is a small computer that runs its own operating system. When fitted to Marty, it can run Python programs and send commands through Marty's expansion cable.

<note>
**You can use a Chromebook without enabling Linux on it.** Raspberry Pi OS (Linux), Python and your programs run on the Pi. Your Chromebook, PC or Mac is the screen and keyboard used to access it remotely. All commands in this guide run in the **Pi's terminal**, unless a step explicitly names your other computer.
</note>

===== Choose how to access your Pi =====

^ Method ^ What you use on your computer ^ What staff need to arrange ^
| Raspberry Pi Connect | A browser; no Chromebook Linux installation. Terminal access, or desktop sharing when supported. | Raspberry Pi OS Bookworm or later, internet access, Connect enabled and a school-approved account arrangement. |
| SSH | An SSH client. On ChromeOS, Google's Secure Shell extension is an option if permitted by IT. | SSH enabled on the Pi, its username and network address, and permission for the computer to reach the Pi. |
| Monitor and keyboard | Peripherals attached directly to the Pi. A desktop OS image also supports graphical editors. | Suitable peripherals and a separate Pi supply during initial setup, with the Pi disconnected from Marty. |

Start with **Connect** if a browser-based service fits your school's policies. Choose **SSH** if you prefer terminal access over the local network. A monitor and keyboard are useful for the first setup or if remote access is unavailable. You only need one working access method.

===== Setting up a Raspberry Pi =====

First check the [[martyv2:userguides:raspberry_pi:start#prerequisites|Marty hardware and power requirements]]. If the Pi already boots and has your students' work on it, keep that installation unless an upgrade is needed. Writing an OS image erases the selected storage device, so back up existing work first.

For a new card, a teacher or IT team can follow these steps:

  - Install [[https://www.raspberrypi.com/software/|Raspberry Pi Imager]] on a Windows, macOS or Linux computer. This initial preparation can be done on a staff computer even when students will only use Chromebooks.
  - Insert the microSD card, select the actual Pi model, then select Raspberry Pi OS and the correct storage device. Choose **Bookworm or later** for Connect. Choose a **desktop** edition if you want graphical desktop access; **Lite** is suitable for terminal-only use.
  - Use Imager's customisation screens to set a unique hostname (for example, ''%%marty-pi-01%%''), a Pi username and password, locale/time zone, and Wi-Fi details. Do not assume the username is ''%%pi%%'' or that there is a default password. Ask IT to configure school networks that require additional authentication.
  - If using SSH, enable it in the remote-access settings and configure your chosen authentication method. Current Imager versions may also offer Connect setup; otherwise enable Connect after boot as described below.
  - Double-check the target storage device before writing. When Imager finishes verification, eject the card, insert it into the Pi and boot it using an appropriate supply while it is disconnected from Marty.

See the [[https://www.raspberrypi.com/documentation/computers/getting-started.html|official Imager walkthrough]] for current screens. Prepare remote access before mounting the Pi in Marty so you can troubleshoot it easily.

==== Headless mode ====

“Headless” means using the Pi without a directly attached monitor or keyboard. Prepare its network and remote access first. It does not mean enabling a Linux environment on your Chromebook.

===== Interacting with a Raspberry Pi =====

==== Raspberry Pi Connect: browser access ====

Connect requires Raspberry Pi OS Bookworm or later. Both the Pi and the computer need internet access to use the service. A Raspberry Pi account and school approval may be required; arrange access for students with IT rather than sharing a teacher's personal password. See the [[https://www.raspberrypi.com/documentation/services/connect.html|official Connect documentation]] for current account options.

**One-time setup on the Pi:**

  - With a monitor and keyboard attached, open the Connect menu on the Pi desktop, turn the service on and follow the sign-in instructions to link the Pi to the approved account.
  - Alternatively, from an existing Pi terminal or SSH session, run the following commands. Open the verification link printed by the sign-in command on a computer where you can sign in to the approved account.

<code bash>
rpi-connect on
rpi-connect signin
</code>

If ''%%rpi-connect%%'' is not installed, install **one** of these packages on the Pi, then repeat the commands above:

<code bash>
sudo apt update
sudo apt install rpi-connect
</code>

For **Raspberry Pi OS Lite**, use ''%%sudo apt install rpi-connect-lite%%'' instead; it provides remote terminal access without desktop sharing.

**Each session on the Chromebook, PC or Mac:**

  - Open [[https://connect.raspberrypi.com|Raspberry Pi Connect]] in the browser and sign in using the access arrangement approved by your school.
  - Find your assigned Pi and select **Connect via → Remote shell** to open the Pi's terminal.
  - If you want the Pi desktop, select **Screen sharing** instead. This needs a running Wayland desktop session on the Pi; it is not available on OS Lite or an X11 desktop. Shell access does not need a desktop.
  - Use that Pi terminal to follow the Marty configuration and Python installation guides.

If a Pi is offline, check its power, network and linked account. Connect runs as a user service. For remote shell access after reboot without a local login, staff can enable user lingering from the Pi account linked to Connect:

<code bash>
loginctl enable-linger
</code>

This keeps that user's services running while logged out. It does not create the desktop session needed for screen sharing. See [[https://www.raspberrypi.com/documentation/services/connect.html#enable-remote-shell-at-all-times|Enable remote shell at all times]]. Reboot and check that browser terminal access works before installing the Pi in Marty. IT can run ''%%rpi-connect doctor%%'' on the Pi to diagnose service and network problems. A restrictive school firewall may need configuration even though the Chromebook can open the website.

==== SSH (Secure Shell) ====

SSH gives you a terminal on the Pi over the network. It does not provide a graphical desktop. Internet access is not needed for an established local SSH connection, though it is needed to download software during setup.

  - Enable SSH in Imager before the first boot, or on the Pi run ''%%sudo raspi-config%%'' and choose **Interface Options → SSH → Enable**.
  - Find the Pi's address. From a terminal on the Pi, run ''%%hostname -I%%'', or ask IT to identify it from the network's device list. Give classroom Pis distinct hostnames. Hostnames ending in ''%%.local%%'' may not resolve on every school network, so use the IP address if necessary.
  - On a Chromebook, ask IT to allow [[https://chromewebstore.google.com/detail/secure-shell/iodihamcpbpeioajjeobimgagajmlibd|Google's Secure Shell extension]]. Open it and enter the Pi username, hostname/IP address, and port **22**. Authenticate using the password or key configured on the Pi. No Chromebook Linux environment is required for this extension.
  - On Windows, macOS or Linux, use an available SSH client. In a terminal, enter ''%%ssh YOUR_PI_USERNAME@PI_ADDRESS%%'', replacing both placeholders with your Pi's details.
  - At the first connection, check the host identity/fingerprint with your teacher or IT team before accepting it. You should then see the Pi's terminal prompt.

Your computer must be allowed to reach the Pi over the network. Sharing a Wi-Fi name does not guarantee this: school client isolation or separate network segments can block connections. Ask IT to provide an approved route rather than changing device security settings yourself. See [[https://www.raspberrypi.com/documentation/computers/remote-access.html#ssh|Raspberry Pi's SSH documentation]].

==== Pi with a mouse, keyboard and a monitor ====

Connect the peripherals and use the Pi directly for setup. On a desktop edition of Raspberry Pi OS, open Terminal for the commands in our guides. OS Lite provides a text console instead. Configure and verify remote access before disconnecting the peripherals and mounting the Pi in Marty.

==== VNC (Virtual Network Computing) ====

VNC is another way to access a graphical Pi desktop over a network. It requires a configured server on the Pi and a compatible viewer on your computer. Availability depends on the OS, desktop and school device policies. See [[https://www.raspberrypi.com/documentation/computers/remote-access.html|Raspberry Pi's remote-access documentation]]. For a Chromebook with no permitted viewer, the browser-based Connect route above may be more convenient.

==== VS Code Remote extension ====

If you already have desktop Visual Studio Code and SSH working on your computer, the [[https://code.visualstudio.com/docs/remote/ssh|Remote - SSH extension]] can edit files and run commands on the Pi. Check its supported Pi hardware and OS requirements first. This is optional; it is not required for the Chromebook browser workflow.

===== School IT checklist =====

  * Confirm that the Pi can join the school's network and download OS/Python packages during setup.
  * For Connect, approve the account arrangement and required service/network access. For SSH, permit the client and computer-to-Pi connection on port 22.
  * Give each Pi a unique name and identify which student or group should use it. Use one active Marty control program per robot.
  * Record the Pi model, OS version, assigned username and access method. Keep passwords and recovery details in the school's approved password-management system.
  * Try one complete setup on an actual managed student Chromebook before preparing the whole class.

===== Next steps =====

Once you can open the Pi's terminal, follow [[martyv2:userguides:raspberry_pi:start|Adding a Raspberry Pi to Marty]] for wiring and serial configuration, and [[martyv2:userguides:python:setting_up_python_on_raspberry_pi|Setting Up Python on Raspberry Pi]] for MartyPy installation. The main guide finishes with a walking program and an each-lesson checklist.

//Documentation reviewed: 29 September 2026. Follow the linked Raspberry Pi documentation for current Imager and Connect screens.//