CLASS SWITCH SIMULATION
=======================
A drag-and-drop AC circuit simulator focused on 3-way / 4-way light
switch wiring. Built for an electrician class demo.


HOW TO RUN
----------
1. Unzip this folder somewhere (Desktop is fine).

macOS:
    Double-click   run.command

    First launch only: macOS may say
    "run.command cannot be opened because it is from an
     unidentified developer." If so, right-click the file,
    choose "Open", then click "Open" in the dialog. After
    that, double-click works normally.

Windows:
    Double-click   run.bat

The first time it runs it sets up a local Python environment
and installs the pygame library (about 30 seconds, internet
required).  Subsequent launches are immediate and offline.

Requires Python 3 to be installed:
    https://www.python.org/downloads/

If running from a terminal instead:
    cd path/to/class_switch_simulation
    python3 -m venv .venv
    .venv/bin/pip install pygame              (Mac/Linux)
    .venv\Scripts\pip install pygame          (Windows)
    .venv/bin/python main.py                  (Mac/Linux)
    .venv\Scripts\python main.py              (Windows)


PARTS PALETTE (left side)
-------------------------
- AC Source        120V hot + neutral feed
- Breaker / Fuse   over-current protection in line with hot
- Single-Pole      regular on/off switch
- 3-Way Switch     COM + two travelers (T1, T2)
- 4-Way Switch     two pairs - flips travelers (used between two 3-ways)
- Light Bulb       the load. Lights up when the circuit is complete
- Wire Nut         splice / junction (all leads connected)
- Receptacle       standard outlet (visual only)


HOW TO USE IT
-------------
- DRAG a part from the left panel onto the blueprint to place it.
- DRAG a placed part to move it. Snaps to the grid.
- CLICK a copper terminal, then CLICK another terminal to draw a wire.
- CLICK any switch to flip it (use Shift+Drag if you want to move
  a switch instead of toggling it).
- RIGHT-CLICK a wire or part to delete it.
- ESC cancels a wire you started.

WIRE COLORS (top bar, or keys 1-5)
    1 = Black   HOT             (insulated)
    2 = White   NEUTRAL         (insulated)
    3 = Red     TRAVELER        (between two 3-ways or 4-ways)
    4 = Green   GROUND          (insulated)
    5 = Copper  BARE GROUND     (no insulation - matches NM-B cable)

Insulated wires are drawn as cables with a black jacket and a
sheen highlight, with the bare copper conductor visible at each
end where it goes under the terminal screw.  The "Copper" wire
is rendered as bare conductor along its full length, like the
ground wire in standard Romex / NM-B cable.

When the circuit is complete the active wires get glowing yellow
arrow-dots showing the conventional direction of current flow
(positive to negative).

If you ever wire HOT directly back to NEUTRAL with no load in
between, the status bar at the bottom flashes a red
"!! SHORT CIRCUIT !!" warning - this is what would trip a real
breaker. Good talking point for class.

AC mode toggle (top bar): switch between
    "AC: steady flow"     - shows one direction (easier to read)
    "AC: alternating"     - flips direction periodically so students
                            can see that AC reverses 60 times a sec
                            (slowed way down for visibility).


HOTKEYS
-------
    D   load the pre-built 3-way demo circuit
    C   clear the canvas
    1-4 select wire color
    ESC cancel current action

PRE-BUILT DEMO ( press D )
--------------------------
Loads a complete 3-way switch circuit:

    [AC Source] -- HOT --> [Breaker] -- HOT --> [3-way #1 COM]
        |                                           T1 == T2
        |                                       [3-way #2 T1 T2]
        |                                            COM
        |                                             |
        +-- NEUTRAL --[wire nut]----------------- [Bulb]

Toggle either 3-way switch and watch the light follow.  That's the
defining behavior of a 3-way circuit: either switch can control the
load from either location.


ADDING A 4-WAY (advanced)
-------------------------
1. Press D to load the 3-way demo.
2. Right-click both red traveler wires and delete them.
3. Drop a 4-Way Switch between the two 3-ways.
4. Wire 3-way#1 T1 -> 4-way LINE_IN
        3-way#1 T2 -> 4-way LINE_OUT
        4-way LOAD_IN  -> 3-way#2 T1
        4-way LOAD_OUT -> 3-way#2 T2
5. Now ANY of the three switches will toggle the light.


TROUBLESHOOTING
---------------
- Light won't turn on?  Check that:
    * Hot path leaves AC source HOT, goes through the breaker,
      through both 3-ways' COM/traveler/COM, and into the bulb.
    * Neutral path returns from the bulb back to AC source NEUTRAL.
    * Both ends of every wire are actually on a copper terminal
      (it'll connect; if you missed, redraw it).
- Wire seems to cross other wires?  That's fine - this is a
  schematic-style sim; it does not enforce physical wire routing.
- Window not opening?  Run from terminal to see the error:
      python3 ~/Desktop/class_switch_simulation/main.py
