Git, debugging and responsible AI

Use your own private repository as the student workspace. The public course is a reading site; it does not store answers, upload code or manage the robot. Desktop Python, MicroPython and the website are separate environments. Record which one produced each result.

First setup

Install Git and desktop Python using their official instructions. Use an editor you can explain; Cursor is optional. Create a private student repository on GitHub and clone it locally, or initialize locally before connecting a private remote. Use GitHub's documented authentication flow; never paste tokens into source files or notebook screenshots.

mkdir robotics-notebook
cd robotics-notebook
git init
mkdir code notebook data plots

Create README.md with the robot model, directory map and first challenge. Create .gitignore containing .venv/, __pycache__/, .env and editor-specific temporary files. Git does not retain empty directories; your first files make them visible. For desktop packages, use a local virtual environment; the weekly examples use only the Python standard library.

python3 -m venv .venv
source .venv/bin/activate
python3 code/w02.py

On Windows the activation path differs; use the official Python virtual-environment documentation or your editor's interpreter selector. None of the desktop examples imports the robot device library.

The session cycle

Check git status before editing; know what already changed.
Write a prediction, make one understandable change and run a small test.
Save source, raw data and a notebook entry. Review git diff for mistakes and private information.
Stage intended files explicitly and commit the reason for the change.
If connected to your own private remote, push when you want a backup. Record the tested revision in your notebook.

git status
git diff
git add code/w02.py notebook/w02-s3.md
git commit -m "Reject invalid durations before planning motion"
git rev-parse --short HEAD

Use git log --oneline to find a previous version and git show COMMIT:path/to/file to inspect it. Avoid destructive reset/clean commands when learning. A branch is useful for an experiment; a new branch does not change the robot until you transfer its code. Never assume a push uploads firmware.

Source, transfer and execution

The robot runs MicroPython with the Pololu modules. Follow the hardware guide to back up existing files, connect through Thonny/the documented method, transfer a named file and run it explicitly. First change a display message. Record desktop source commit, uploaded filename, firmware version and observed output. A source commit alone does not identify which file was executed on the device.

Debugging from evidence

Start with the smallest reproduction. Read the final exception line, then the indicated source line. Check input types and units before changing algorithms. Print named intermediate values or use a short log. Change one factor, rerun the same case and retain the before/after result.

Symptom	First check	Useful evidence
Import error	desktop versus device interpreter	interpreter/version and exact import
Zero division	duration/sample interval validity	timestamp/input values
Robot turns wrong way	signed counts and coordinate convention	raised-wheel count/command test
Distance doubled	increments versus cumulative counts	raw consecutive count pairs
PID oscillates	gain, sampling delay and limits	error/command plot with dt
Route cuts corners	waypoint tolerance and clearance	measured trajectory on surveyed map
Different results after restart	reset state/configuration	source, settings and initialization log

A physical hazard requires stopping first. Do not repeatedly rerun a motion fault merely to obtain a nicer log. Save device output, remove motor power and investigate in simulation/replay where possible.

Responsible AI assistance

Ask an LLM to explain a concept, critique a hypothesis, propose test cases or review a small diff. Give it units, environment and your observed error. Require the source for a hardware API and compare it with the actual Pololu firmware. Never transfer generated motor code just because it looks plausible.

A useful prompt is: “This desktop function converts encoder increments to metres. Here are three expected cases and my code. Explain the units, identify a failing case and suggest the smallest correction.” A weak prompt is: “Make my robot work” without a model, log or stop constraints.

Before accepting generated work, explain each line, run normal and invalid cases, verify calculations independently and identify what has not been tested. Credit material assistance in the notebook. Do not submit API guesses, synthetic measurements or an AI-written conclusion as your own collected evidence. Keep credentials and personal information out of prompts.

Clean handoff

Your student README should identify setup, firmware, configuration, run instructions, data/plots, tested versions and limitations. Ask someone to replay one desktop result from a clean clone. See Projects/Portfolio for the final deliverable checklist.

Sources: GitHub Hello World, Python tutorial, Pololu official guide. References checked 2026-10-09; follow current authentication and actual firmware instructions.