# Ohmsville

> The early-80s spring-terminal electronics lab, alive in your browser. Real parts, real physics — LEDs glow, the speaker sings, and things smoke when you get it wrong. A shop teacher sits in the manual. Live at https://ohmsville.com.

## Opening a circuit by URL
The bench reads its whole state from the URL hash, so a circuit is a link:

`/bench#a=<activity>&b=<board>&w=<wire pairs>&c=<campaign>`

- `a=` — the manual page to open on load: an experiment (`exp-<n>`) or a recipe id (see Recipes below).
- `b=` — the board layout, present only when it differs from the standard kit. Parts are listed in spring order, comma-separated: a standard part is `id@col.row`, a part pulled from the drawer is `+kind:value@col.row` (e.g. `+resistor:2200@3.1`).
- `w=` — wires, comma-separated `spring-spring` pairs, e.g. `1-5,6-28`.
- `c=` — a campaign id (see Explore below), applied once when the page opens.

Example — experiment 1's reference wiring: `/bench#a=exp-1&w=1-5,6-28,29-38,39-2`

## Levels and experiments
### Level 1 · First Light (30 in ONE)
Batteries, resistors, LEDs and the loop that joins them.
  - exp-1 — Light the LED: Press the button and the red LED lights. Let go and it goes dark.
  - exp-2 — Dim it with the pot: Turn the knob and the LED goes from bright to almost out.
  - exp-3 — Two-transistor flasher: The red and green LEDs take turns blinking, about once a second.
  - exp-4 — Make a tone: Turn the speaker on and hear a steady tone around 700 Hz.
  - exp-5 — Light-controlled tone: Drag the light slider under the CdS cell (or turn on the camera and cover it) and the pitch changes.

### Level 2 · Timing & Control (55 in ONE)
Series and parallel, a transistor as a switch, and capacitors that set the pace.
  - exp-6 — Series LEDs: Both LEDs glow, and each is dimmer than the red one was alone through the same 1 kΩ.
  - exp-7 — Parallel LEDs: Both LEDs at full brightness at once, each on its own 330 Ω.
  - exp-8 — A knob that carries no load: Turn the pot and the LED dims, but the pot itself only ever handles microamps.
  - exp-9 — Slow on, slow off: Hold the button: the LED fades up over a couple of seconds. Let go: it stays lit and fades out slowly.
  - exp-10 — Siren knob: Turn the speaker on and turn the new pot: the pitch slides from a low buzz up to the tone of experiment 4.

### Level 3 · Sound & Sense (100 in ONE)
Stack batteries, store charge, and turn light and knobs into sound.
  - exp-11 — Twice the push: With two batteries in series the LED through 1 kΩ is about twice as bright as with one.
  - exp-12 — Capacitor battery: Hold the button to charge the 470 µF, let go, and the LED keeps glowing for about half a second as the capacitor empties.
  - exp-13 — Metronome: Turn the speaker on and hear a steady click about three times a second.
  - exp-14 — Two-tone: Turn the speaker on: the slide switch flips the tone between two pitches.
  - exp-15 — Light theremin: Turn the speaker on. The light slider plays the pitch, and the new pot tunes it: each sets one half of every cycle.

### Level 4 · Relay Logic (200 in ONE)
An electromagnet that throws a switch: NOT, memory, an alarm, and the bell.
  - exp-16 — One coil, two circuits: Green is lit at rest. Hold the button: a click, green goes out and red comes on. Let go: click, back to green.
  - exp-17 — Kickback: Hold the button: click, LED on. Let go: click, LED off, and Q1 is still alive. Now pull the diode's wires and try again: Q1 dies the moment you let go.
  - exp-18 — Dark alarm: Slide the light toward the moon: click, and the buzzer sounds. Back toward the sun: click, silence.
  - exp-19 — The relay that remembers: Slide ON. Tap the button: click, LED on, and it stays on after you let go. Slide OFF: click, LED out. Slide ON again: still off until you tap.
  - exp-20 — The electric bell: Turn the speaker on and slide ON: a low buzz, around 90 Hz, and the relay blade shivers.

### Level 5 · Logic Lane (250 in ONE)
A chip that keeps time, gates that decide, and a digit the room can read.
  - exp-21 — The pad beacon: The red lamp blinks on its own, about two thirds of a second on and two thirds off, and nothing you do to the board changes it.
  - exp-22 — Range safety: Turn the speaker on: a tone. Turn the knob and the pitch climbs from a low hum near 690 Hz to a shriek past 3 kHz.
  - exp-23 — Go / No-Go: Slide ON and hold the button: the lamp lights. Either one alone: nothing. That is AND.
  - exp-24 — Set the digit: Nothing pressed: 0. Button: 1. Slide: 2. Both: 3.
  - exp-25 — Zero: Hold the button and the clock sits at 9. Let go: 9, 8, 7, all the way to 0, about one step a second, with the lamp ticking. Then it rolls round to 9 and starts again.

## Recipes
Short circuits that show what one part does, opened the same way as an experiment (`a=<recipe-id>`):
- ohms-law — Ohm's law, by eye: The LED glows dimmer through 1 kΩ than through 330 Ω. Swap in 10 kΩ and it barely shows.
- smoke-test — Smoke test: Put 100 Ω straight across 9 V and watch it burn in a blink.
- exp-1 — Light the LED: Press the button and the red LED lights. Let go and it goes dark.
- exp-2 — Dim it with the pot: Turn the knob and the LED goes from bright to almost out.
- exp-3 — Two-transistor flasher: The red and green LEDs take turns blinking, about once a second.
- exp-9 — Slow on, slow off: Hold the button: the LED fades up over a couple of seconds. Let go: it stays lit and fades out slowly.
- exp-4 — Make a tone: Turn the speaker on and hear a steady tone around 700 Hz.
- tiny-current — Tiny current, big current: Under a tenth of a milliamp into the base lights the LED with about 8 mA.
- exp-8 — A knob that carries no load: Turn the pot and the LED dims, but the pot itself only ever handles microamps.
- divider — Voltage divider: Hover spring 18 and turn the knob: the voltage slides from 9 V down to 0.
- series-switches — Two switches in series: The LED lights only when the slide is ON and the button is held.
- parallel-switches — Two switches in parallel: Either the slide or the button lights the LED.
- light-meter — Light meter: The LED glows with the light slider toward the sun and goes dark toward the moon; or turn on the camera and cover it.
- night-light — Night light: Slide the light under the CdS cell toward the moon: the LED comes on in the dark and goes off in the light.
- exp-5 — Light-controlled tone: Drag the light slider under the CdS cell (or turn on the camera and cover it) and the pitch changes.
- click — Make it click: Turn the speaker on, then tap the button: a click on press and another on release.
- one-way-street — One-way street: The LED lights, with about 0.7 V across the 1N4001. Turn the diode round and all is dark.
- exp-17 — Kickback: Hold the button: click, LED on. Let go: click, LED off, and Q1 is still alive. Now pull the diode's wires and try again: Q1 dies the moment you let go.
- alarm-button — Alarm button: Hold the button and the buzzer sounds; let go and it stops.
- exp-18 — Dark alarm: Slide the light toward the moon: click, and the buzzer sounds. Back toward the sun: click, silence.
- exp-16 — One coil, two circuits: Green is lit at rest. Hold the button: a click, green goes out and red comes on. Let go: click, back to green.
- exp-19 — The relay that remembers: Slide ON. Tap the button: click, LED on, and it stays on after you let go. Slide OFF: click, LED out. Slide ON again: still off until you tap.
- one-shot — One shot: Tap the button and the lamp comes on and stays on for about a second, then goes out by itself. Tapping again during the second changes nothing.
- exp-21 — The pad beacon: The red lamp blinks on its own, about two thirds of a second on and two thirds off, and nothing you do to the board changes it.
- exp-22 — Range safety: Turn the speaker on: a tone. Turn the knob and the pitch climbs from a low hum near 690 Hz to a shriek past 3 kHz.
- inverter — NOT, from a NAND: The lamp is lit at rest and goes dark while you hold the button. That is NOT.
- exp-23 — Go / No-Go: Slide ON and hold the button: the lamp lights. Either one alone: nothing. That is AND.
- count-by-hand — Count by hand: Tap the button and the digit goes up by one: 0, 1, 2 … 9, and then round to 0 again.
- exp-24 — Set the digit: Nothing pressed: 0. Button: 1. Slide: 2. Both: 3.
- exp-25 — Zero: Hold the button and the clock sits at 9. Let go: 9, 8, 7, all the way to 0, about one step a second, with the lamp ticking. Then it rolls round to 9 and starts again.
- flickering-candle — Flickering candle: A yellow LED that never sits still: two clocks running at once, and the brightness is their sum.
- eyes-in-the-bushes — Eyes in the bushes: Two red LEDs blinking the opposite way round: when one is lit the other is out, about three times every two seconds.
- lightning — Lightning: A rattling burst of flashes for about three quarters of a second, then nothing for about the same, over and over.
- creaky-door — Creaky door: Hold the button to wind it up. Let go and the tone groans downward for ten seconds, slower and slower, until the door is shut.
- tripwire-scream — Tripwire scream: Keep a light on the cell and the shop is quiet. Break the beam — slide the light toward the moon, or cover the camera — and it screams.
- ghost-in-the-wires — Ghost in the wires: Slide ON to arm it. Something crosses the shadow once and the buzzer starts — and keeps going after whatever it was has gone. Only the slide shuts it up.

## Lessons
The classroom's course, one lesson per idea, each with a demo on the bench:
### Charge and the loop
- what-electricity-is — What electricity is: Voltage is the push (energy per charge, measured in volts); current is the flow of charge (measured in amps). Charge does not leave a cut wire the way water leaves a cut pipe; the wire is already full of charge and the whole column moves together.
- the-loop — The loop: Current needs a closed loop from + through the parts back to −; a switch is a gap in the loop; switches in series both need to close (AND) while switches in parallel need only one (OR).

### Ohm's law
- resistance-and-ohms-law — Resistance and Ohm's law: Ohm's law: I = V / R (volts divided by ohms gives amps). A resistor's colour bands give its value; its power rating in watts is the heat it can shed, and P = V × I above that rating burns it.
- series-and-parallel — Series and parallel: In series the same current flows through each part and voltages add (resistances add). In parallel each part sees the same voltage and currents add (combined resistance drops). Batteries in series add volts; capacitors in parallel add farads.

### Parts that do something
- capacitors-and-time — Capacitors and time: A capacitor stores charge (farads = charge per volt). Charging through a resistor takes time set by R × C, about 63% per time constant. Capacitors pass changes and block steady current; electrolytics have polarity.
- diodes-and-leds — Diodes and LEDs: A diode conducts one way only and takes a fixed forward voltage (about 1.9 V for a red LED) rather than a proportional share; an LED needs a series resistor to set its current, and reversed it stays dark but undamaged.
- transistors — Transistors as switches and amplifiers: An NPN transistor lets a small base current control a collector current about beta (around 100) times larger; with the base fully on or off it is a switch, and in between it is an amplifier where the output follows the input.

### Circuits that move
- oscillators — Oscillators: The two-transistor astable multivibrator flips because each transistor turns the other off through a capacitor that recharges through a resistor; period ≈ 1.4 × R × C, so smaller C or R means a faster flip (a flasher at 100 µF, a 700 Hz tone at 0.1 µF).
- sensors — Sensors: A sensor turns a physical quantity into resistance (photocell: about 1 kΩ bright, hundreds of kΩ dark). In a voltage divider the sensor's share of the volts changes with it, and a transistor at the midpoint turns that into a switch or a control.

### The shop
- reading-schematics — Reading schematics: A schematic shows connections, not positions: the same schematic wires many ways. Symbols carry meaning (curved capacitor plate is the electrolytic's −, LED triangle points the way current flows, NPN arrow points out of the emitter), and reading starts at the battery + and follows the loop.
- measuring — Measuring: A voltmeter goes across a part (parallel, very high resistance); an ammeter goes in the loop (series, very low resistance) and must never be clipped across a part. Voltages around a loop add to the source voltage; currents into a junction equal currents out.
- safety-and-real-parts — Safety and real parts: Danger is set by current through the body, not volts alone: 9 V through skin is under a tenth of a milliamp and safe, mains at 120–240 V can push tens of milliamps across the chest and is not. Heat, polarity (electrolytics, LEDs, battery), and part tolerance are the real-world details the simulator only hints at.

## Parts catalogue
Every part in the drawer, unlimited supply, grouped by kind:
- **resistor**: 10 Ω, 22 Ω, 47 Ω, 100 Ω, 220 Ω, 330 Ω, 470 Ω, 1 kΩ, 2.2 kΩ, 4.7 kΩ, 10 kΩ, 22 kΩ, 47 kΩ, 100 kΩ, 220 kΩ, 470 kΩ, 1 MΩ
- **capacitor**: 1 nF, 10 nF, 100 nF, 1 µF, 10 µF, 100 µF, 470 µF
- **led**: LED red, LED green, LED yellow
- **npn**: NPN 2N2222
- **pot**: 10 kΩ pot, 100 kΩ pot
- **switch**: Pushbutton, Slide switch
- **speaker**: Speaker 8 Ω
- **photocell**: CdS cell
- **diode**: 1N4001
- **buzzer**: Buzzer
- **relay**: Relay 9 V
- **timer555**: NE555
- **gate**: NAND gate, NOR gate
- **sevenseg**: 7-segment
- **counter**: Counter up, Counter down
- **battery**: 9 V, 1.5 V

## Explore
- [Home](/)
- [The Ladder](/ladder) — the levels, in order, with what each unlocks.
- [Classroom](/classroom) — the course above, read as lessons.
- [Mission Control](/campaign/mission-control) — Five circuits stand between you and a launch.
- [Spooky Shack](/campaign/spooky-shack) — The shop is shut, the lights are off, and something in the 200-in-1 is still running.
- [Halloween](/halloween) — the Spooky Shack pack: seven circuits, the October mission, and the write-up.
- [Blog](/blog) — dev log, how the kit works, and the history behind the campaigns.
- [For agents & developers](/agents) — this file, read as a page, plus the URL grammar worked out, the API and the MCP connector setup.

## API
The same content as JSON, plus a simulator that runs the real solver. No key, no
sign-up, CORS open to any origin. Base: https://ohmsville.com/api

- `GET /api/experiments`, `GET /api/experiments/{id}` — the manual, with each experiment's goal, wiring, circuit document, bench link and schematic.
- `GET /api/recipes`, `GET /api/recipes/{id}` — the short per-part circuits.
- `GET /api/lessons`, `GET /api/lessons/{id}` — the classroom's course.
- `GET /api/parts` — the standard board, the drawer, and the pin names of every part kind.
- `POST /api/links` — a circuit document in, a bench link out (plus the canonical document that link carries).
- `GET /api/circuit?url=` — a bench link in, a circuit document out.
- `POST /api/simulate` — settle a circuit, apply knob changes step by step, and read volts, milliamps, LED brightness, transistor region, relay state and speaker pitch. Caps: 40 wired parts, 120 wires, 3 000 ms of circuit time, a 6 s wall clock; over the wall clock you get the steps that finished and `"complete": false`.
- `POST /api/ask` — ask the shop teacher about a circuit. Needs an `X-Api-Key`; `POST /api/keys` with your email mails you one, good for 50 questions a UTC day.
- `GET /api/openapi.json`, `GET /api/docs` — the whole thing, machine- and human-readable.

A circuit is a JSON document, not a URL hash: its schema is at `/api/schema/circuit.json`. The 21 standard
parts are always on the board, so `parts` lists only what you took from the drawer, and every wire endpoint is
`"<part>.<pin>"` (or a bare spring number). Experiment 1, in full:

```json
{
  "format": "circuit-city.circuit",
  "version": 1,
  "activity": "exp-1",
  "wires": [
    [
      "battery.+",
      "r330a.a"
    ],
    [
      "r330a.b",
      "led-red.a"
    ],
    [
      "led-red.k",
      "pushbutton.a"
    ],
    [
      "battery.-",
      "pushbutton.b"
    ]
  ]
}
```

### MCP

`https://ohmsville.com/mcp` is a remote MCP server (Streamable HTTP, stateless). Add it as a connector in
Claude.ai or ChatGPT, or in Claude Code with
`claude mcp add --transport http ohmsville https://ohmsville.com/mcp`.

Tools: `list_experiments`, `get_experiment`, `list_recipes`, `list_lessons`, `list_parts`,
`simulate_circuit`, `make_link`, `parse_link`, `ask_teacher`. Resources:
`ohmsville://experiments/{id}`, `ohmsville://lessons/{id}`, `ohmsville://schema/circuit`.
Prompt: `design_circuit`. Everything but `ask_teacher` is keyless; `ask_teacher` takes the same
key `POST /api/ask` does, as an `Authorization: Bearer` header or an `apiKey` argument.

## Optional
- [llms-full.txt](/llms-full.txt) — this file plus every experiment's and lesson's full concept text, wiring, and the schematic drawing DSL.
- [Agent card](/.well-known/agent-card.json) — an A2A-style description of the shop teacher as an agent.