Add comprehensive WPA2-Enterprise WiFi setup documentation for Raspberry Pi devices

[Copilot]

This PR adds comprehensive documentation for setting up WPA2-Enterprise WiFi connections on Raspberry Pi devices used in the AC Training Lab. The documentation addresses the need for institutional network connectivity that was requested in the original issue.

What's Added

New Documentation

• docs/devices/raspberry-pi-wpa2-enterprise.md: Complete setup guide covering:
  • Multiple EAP authentication methods (PEAP-MSCHAPv2, EAP-TLS, EAP-TTLS)
  • Two setup approaches (wpa_supplicant configuration and raspi-config method)
  • CA certificate handling and installation procedures
  • Comprehensive troubleshooting section with common issues and solutions
  • Security considerations and best practices
  • Network testing and validation commands

Integration & Discoverability

• Updated device documentation generation script to include a dedicated "Setup Guides" section
• Added cross-references from Raspberry Pi-based device documentation (picam, a1_cam)
• Organized documentation structure with clear separation between setup guides and device-specific docs

Reusability Strategy

The documentation is strategically placed as shared infrastructure documentation rather than device-specific content, making it:

• Easily discoverable through the main devices index
• Reusable across all Raspberry Pi-based devices in the lab
• Maintainable in a single location

Example Usage

Users setting up devices like the picam or a1_cam will now see a prominent note directing them to the enterprise WiFi setup guide:

> **Note**: If you need to connect to a WPA2-Enterprise WiFi network (common in institutional environments), please refer to the [Raspberry Pi WPA2-Enterprise WiFi Setup Guide](https://ac-training-lab.readthedocs.io/en/latest/devices/raspberry-pi-wpa2-enterprise.html) before proceeding with the device-specific setup below.

Testing

• Documentation builds successfully with Sphinx
• All internal links and cross-references work correctly
• Content renders properly in both HTML and navigation structure

Fixes #278.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• docs.python.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• docs.scipy.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• matplotlib.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• numpy.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• pandas.pydata.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• pyscaffold.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• scikit-learn.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• setuptools.pypa.io
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)
• www.sphinx-doc.org
  • Triggering command: /opt/hostedtoolcache/Python/3.12.10/x64/bin/python /opt/hostedtoolcache/Python/3.12.10/x64/bin/sphinx-build -M html . _build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to my firewall allow list

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[sgbaird]

Note-to-self: I also want to create a similar page for setting up tailscale based on #183 (reply in thread), which will also be reused in a number of places.

I'm planning to refine things with Copilot for this one before asking it to try.

[sgbaird]

@copilot try again since you may not have been able to implement your changes due to issues with precommit (don't worry about precommit at all, just focus on the content)

[Copilot]

@copilot try again since you may not have been able to implement your changes due to issues with precommit (don't worry about precommit at all, just focus on the content)

The WPA2-Enterprise WiFi setup documentation is successfully implemented. The comprehensive guide covers multiple EAP authentication methods, troubleshooting, and security considerations. Device documentation has been updated with cross-references, and the documentation generation script now includes a dedicated "Setup Guides" section for better discoverability. All content is in place and ready for use (commit 0e12e64).

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• http://168.63.129.16:80/machine/
  • Triggering command: /usr/bin/python3 -u bin/WALinuxAgent-2.13.1.1-py3.9.egg -collect-logs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to my firewall allow list

[sgbaird]

@copilot maybe I didn't mention. You were supposed to take the content directly from the GitHub discussion linked below, which has been thoroughly tested. I'll copy it here. You weren't meant to add your own flavor of things into it, making it overly verbose.

#183 (comment)

=====

I'm leaning towards running in headless mode (e.g., Raspberry Pi OS Lite (bookworm)) in general, especially for any Raspberry Pi Zero 2W's that we have, to reduce the resources consumed by the OS.

Some considerations:

- Connecting to WPA2-Enterprise WiFi. After a lot of troubleshooting and debugging, I found a good way to get this working on bookworm:

##
*following based on ChatGPT prompt, username redacted*

> Connect to a WPA2-Enterprise network on a headless Raspberry Pi Zero 2W running OS Lite (bookworm). I have access to the terminal already. It's on a WPA2-personal network at the moment, and I want to switch it to a WPA2-Enterprise network (specifically, University of Toronto wireless with SSID "UofT") ... How can I do this without exposing my password to the command line?

**1. Verify the Current Network Status:**

First, let's check the current status of your wireless interface (`wlan0`) to understand its state.

```bash
ip addr show wlan0

This command will display the IP address and connection status of wlan0.

2. Install Necessary Packages:

Ensure that network-manager and its associated tools are installed, as they provide utilities like nmcli and nmtui for network configuration.

sudo apt update
sudo apt install network-manager

Optionally, you can run sudo apt upgrade to upgrade all packages.

3. Disable Conflicting Network Services: [OPTIONAL]

To prevent conflicts, optionally disable other network management services such as dhcpcd (this may not apply to bookworm, but may help with earlier versions like buster). If you get Failed to disable unit: Unit file dhcpcd.service does not exist. you can ignore this.

sudo systemctl disable dhcpcd
sudo systemctl stop dhcpcd

4. Enable and Start NetworkManager:

Activate NetworkManager to manage network connections.

sudo systemctl enable NetworkManager
sudo systemctl start NetworkManager

5. Configure the WPA2-Enterprise Connection Using nmtui:

The nmtui (NetworkManager Text User Interface) tool provides an interactive way to set up network connections.

sudo nmtui

Within the nmtui interface:

• Select "Edit a connection".
• Choose "Add", then "Wi-Fi".
• Set the SSID to "UofT".
• Under "Wi-Fi Security", select "WPA & WPA2 Enterprise".

• For "Authentication", choose "Protected EAP (PEAP)".
• Enter your UTORid ("***") in the "Username" field.
• Enter the domain (in UofT's case, radius.wireless.utoronto.ca per their online instructions, NOTE: .utoronto.ca not @utoronto.ca)
• Leave "Anonymous identity" blank unless specified otherwise by the university's IT guidelines. If the interface requires you to enter something, try entering whatever you'd like (e.g., anonymous). Sometimes, it just needs a value
• For "CA Certificate", if the university provides a specific certificate, specify its path.
• Set "Inner authentication" to "MSCHAPv2".
• Enter your UTORid password in the "Password" field.

Note that users with sudo or root access can see the password again if they go digging. I suggest changing your university password to something unique and specific to it (e.g., memorable password generated via 1password). You could also do something like make sure only you have root access and create a non-admin account that others on your team can SSH into, but some consideration might be required when trying to get the device to autostart a script.

After configuring these settings, save and exit nmtui.

6. Connect to the "UofT" Network:

Attempt to establish the connection using nmcli.

sudo nmcli connection up UofT

If you are SSH'd into the device, it may close your connection. If all goes well, you should be able to connect after waiting a minute or so. Otherwise, if something catastrophic happens (i.e., it's unable to connect at all), then you'll need access to the device to manually follow these steps.

7. Verify the Connection:

Check if wlan0 has obtained an IP address and is connected to the "UofT" network.

ip addr show wlan0

You can also check (example output also shown):

sudo nmcli dev status

DEVICE         TYPE      STATE                   CONNECTION 
wlan0          wifi      connected               UofT

Alternatively, you can use sudo nmtui and "Activate Connection" to see which one is currently active (which will have a *); however, if you are SSH'd into your device over WiFi, you will need to have a keyboard and mouse directly connected to the device in order to switch it this way (since you have to manually "Deactivate" before you can activate the new one, at which point your SSH connection is already broken).

Additional Considerations:

• CA Certificate: While some institutions require a CA certificate for secure connections, others do not. If the University of Toronto does not mandate a specific CA certificate, you can configure the connection without it. However, using a CA certificate enhances security by validating the server's identity.

• Consult University IT Support: For institution-specific configurations or requirements, reach out to the University of Toronto's IT services or consult their support documentation.

By following these steps, you should be able to connect your Raspberry Pi Zero 2W to the "UofT" WPA2-Enterprise Wi-Fi network using your UTORid "***".

Rebooting the device should still connect to the one most recently chosen.

Various resources during troubleshooting (see list in comment):

• https://www.reddit.com/r/raspberry_pi/comments/18n47zi/comment/mhq1wdq/