{
  "schema": "tinyskiff.lessonPacket.v0",
  "lessonCode": "TSK-DAY13-ADC",
  "course": "TinySkiff ESP32-S3 Lab",
  "day": 13,
  "title": "Read a knob as a number",
  "status": "published",
  "learnerProfile": "adult beginner; curious and capable; no electronics assumed",
  "estimatedTimeMinutes": 20,
  "mission": "Wire a rotary potentiometer to GPIO 1, upload the Arduino sketch, and watch Serial Monitor print a reading from 0 to 4095 — with its voltage — that follows every turn of the knob.",
  "mainPath": "Arduino/C++",
  "optionalSidePath": "MicroPython",
  "sourceMetadata": {
    "officialPdf": "source/Freenove_Super_Starter_Kit_for_ESP32_S3-main/C/C_Tutorial.pdf",
    "chapter": "Chapter 8 AD Converter",
    "page": 96,
    "arduinoSketch": "source/Freenove_Super_Starter_Kit_for_ESP32_S3-main/C/Sketches/Sketch_08.1_ADC/Sketch_08.1_ADC.ino",
    "micropythonFile": "source/Freenove_Super_Starter_Kit_for_ESP32_S3-main/Python/Python_Codes/08.1_AnalogRead/AnalogRead.py",
    "imageAsset": "docs/course/assets/day-13/circuit-page-96.png",
    "imageAlt": "Official Freenove circuit for reading a potentiometer: the pot's two outer pins wired to 3.3V and ground, and its middle pin wired to GPIO 1, shown as both a schematic and a breadboard photo.",
    "licenseNote": "Based on Freenove official material released under CC BY-NC-SA 3.0; preserve attribution and non-affiliation language.\n"
  },
  "parts": [
    {
      "name": "ESP32-S3 board",
      "imageAsset": "docs/course/assets/shared/item-esp32-s3-board.jpg",
      "explanation": "A development board is a friendly package around a tiny computer chip. The ESP32-S3 runs your uploaded sketch, controls pins, reads sensors, and can also use USB, Wi-Fi, and Bluetooth. In this lesson, it sends the ping signal and measures the echo time."
    },
    {
      "name": "GPIO extension board",
      "imageAsset": "docs/course/assets/shared/item-gpio-extension-board.png",
      "explanation": "GPIO means general-purpose input/output. These pins are connection points your code can use. The extension board makes them easier to see, reach, and wire without cramming everything onto the ESP32-S3 itself."
    },
    {
      "name": "Rotary potentiometer",
      "imageAsset": "docs/course/assets/shared/item-potentiometer.png",
      "explanation": "A potentiometer is a resistor with a third pin on a movable contact. Turning the shaft slides that contact along the resistor, so the voltage on the middle pin sweeps smoothly between the two ends. Wire the ends to 3.3V and ground and the knob becomes a voltage dial your ADC pin can read."
    },
    {
      "name": "3 jumper wires (M/M)",
      "imageAsset": "docs/course/assets/shared/item-jumper-wire.png",
      "explanation": "Jumper wires make temporary connections without soldering. Female-to-male wires have a socket on one end and a pin on the other, useful when a sensor module and board use different connector styles."
    },
    {
      "name": "Arduino IDE",
      "imageAsset": "docs/course/assets/shared/item-arduino-ide.png",
      "explanation": "Arduino IDE is the desktop app that opens the sketch, compiles it, uploads it to the ESP32-S3, and shows messages from the board in Serial Monitor."
    }
  ],
  "wiring": [
    {
      "partPin": "Pot outer pin 1",
      "connectTo": "3.3V",
      "reason": "Feeds one end of the knob's track with full voltage."
    },
    {
      "partPin": "Pot outer pin 2",
      "connectTo": "GND",
      "reason": "Holds the other end of the track at zero volts."
    },
    {
      "partPin": "Pot middle pin 3",
      "connectTo": "GPIO 1",
      "reason": "The wiper delivers the in-between voltage for the ADC to read."
    }
  ],
  "coachInstructions": [
    "Guide one physical connection at a time and wait for learner confirmation before proceeding.",
    "If values sit stuck at 0 or 4095, check the middle-pin wire on GPIO 1 first, then the outer pins on 3.3V and GND.",
    "If the monitor shows garbled text, set the baud rate to 115200 before touching anything else.",
    "If the monitor is blank, check board, port, and a data-capable USB cable before changing code.",
    "A few counts of jitter in a held reading is normal ADC behaviour; have the learner judge by the whole sweep.",
    "Keep the Arduino path primary; in MicroPython the atten and width lines are required to match the 0-4095 range."
  ],
  "steps": [
    "Seat the ESP32-S3 on the GPIO extension board and keep USB unplugged while you wire.",
    "Push the potentiometer into the breadboard so each of its three pins has its own row.",
    "Run a jumper from one outer pin to 3.3V and a second jumper from the other outer pin to GND.",
    "Run the third jumper from the middle pin (pin 3) to GPIO 1.",
    "Compare every wire to the chart before you plug in USB.",
    "Open Sketch_08.1_ADC.ino in Arduino IDE and upload it.",
    "Open Serial Monitor and set the baud rate to 115200.",
    "Turn the knob slowly from one end to the other and watch the numbers sweep."
  ],
  "codeFocus": {
    "arduino": [
      {
        "line": "analogRead(PIN_ANALOG_IN)",
        "explanation": "Samples the voltage on GPIO 1 and returns a number from 0 to 4095."
      },
      {
        "line": "adcVal / 4095.0 * 3.3",
        "explanation": "Converts the reading back into volts — 4095.0 is the top reading, so a full turn lands exactly on 3.30V."
      },
      {
        "line": "Serial.printf(\"ADC Val: %d, \\t Voltage: %.2fV\\r\\n\", adcVal, voltage)",
        "explanation": "Prints the raw reading and the voltage on one line, five times a second."
      }
    ],
    "micropython": [
      {
        "line": "adc.atten(ADC.ATTN_11DB)",
        "explanation": "Opens the input range so the pin can read the full 0 to 3.3V sweep."
      },
      {
        "line": "adc.width(ADC.WIDTH_12BIT)",
        "explanation": "Sets 12-bit readings — 0 to 4095 — the same scale the Arduino core uses by default."
      }
    ]
  },
  "theoryModel": {
    "plainLanguage": "The ADC measures the voltage on a pin and reports it as a number from 0 to 4095 — the knob dials which voltage it sees.",
    "formula": "voltage = reading ÷ 4095 × 3.3",
    "notes": [
      {
        "title": "Why the top is 4095",
        "body": "Twelve bits give 4096 steps numbered 0 through 4095 — so 4095 means the pin sees the full 3.3V, and the code divides by 4095.0 to match."
      },
      {
        "title": "The knob is a voltage divider",
        "body": "The track splits 3.3V along its length and the wiper taps off the share at its position — a divider you adjust by hand."
      }
    ]
  },
  "test": {
    "expectedOutputExample": [
      "ADC Val: 0, Voltage: 0.00V",
      "ADC Val: 2048, Voltage: 1.65V",
      "ADC Val: 4095, Voltage: 3.30V"
    ],
    "successCriteria": "The values track the knob — one end reads near 0, the other near 4095, and every position between prints its own pair."
  },
  "troubleshooting": [
    {
      "symptom": "Stuck at 0 or 4095",
      "firstChecks": [
        "Check the middle-pin wire on GPIO 1, then the two outer pins on 3.3V and GND."
      ]
    },
    {
      "symptom": "Garbled or random characters",
      "firstChecks": [
        "Set Serial Monitor to 115200 baud to match the sketch."
      ]
    },
    {
      "symptom": "Blank monitor",
      "firstChecks": [
        "Confirm the right board and port, then swap in a data-capable USB cable."
      ]
    },
    {
      "symptom": "Reading jitters by a few counts",
      "firstChecks": [
        "That's normal for a real ADC — judge by the whole sweep."
      ]
    }
  ],
  "challenge": "Find the knob's midpoint by numbers alone, map a few positions to their readings, and note how steadily a held value sits.",
  "logbookPrompts": [
    "What reading did your knob's midpoint give?",
    "How steady did a held position stay, and by how many counts did it drift?",
    "What would you control with a knob that reports its own position?"
  ]
}