187 lines
6.7 KiB
Markdown
187 lines
6.7 KiB
Markdown
# Exploring Uncertainties
|
||
|
||
An interactive Arduino installation using 12 push buttons and a 240-LED thermometer strip. Players answer 4 questions by pressing buttons; correct answers cool the thermometer down, wrong answers heat it up. Getting all 4 right brings the temperature to zero and triggers a rainbow win animation.
|
||
|
||
---
|
||
|
||
## Hardware
|
||
|
||
| Component | Details |
|
||
|---|---|
|
||
| Microcontroller | Arduino Uno |
|
||
| LED strip | WS2812B, 60 LEDs/m, 5V — 4 strips of 60 connected in series (240 LEDs total) |
|
||
| Buttons | 12× momentary push buttons (IP65 aluminium, 19 mm, 1NO) |
|
||
| Reset button | 1× additional momentary button (on A1) |
|
||
| Power | External 5V PSU for LED strip; USB powers the Arduino |
|
||
|
||
## Wiring Summary
|
||
|
||
See [Wiring.md](Wiring.md) for full details and diagrams.
|
||
|
||
| Component | Arduino pin |
|
||
|---|---|
|
||
| LED strip data | A0 (= digital pin 14) |
|
||
| Button 1 (Q1-A) | D2 |
|
||
| Button 2 (Q1-B) | D3 |
|
||
| Button 3 (Q1-C) | D4 |
|
||
| Button 4 (Q2-A) | D5 |
|
||
| Button 5 (Q2-B) | D6 |
|
||
| Button 6 (Q2-C) | D7 |
|
||
| Button 7 (Q3-A) | D8 |
|
||
| Button 8 (Q3-B) | D9 |
|
||
| Button 9 (Q3-C) | D10 |
|
||
| Button 10 (Q4-A) | D11 |
|
||
| Button 11 (Q4-B) | D12 |
|
||
| Button 12 (Q4-C) | D13 |
|
||
| Reset button | A1 (= digital pin 15) |
|
||
|
||
All buttons wired with `INPUT_PULLUP`: connect each button between its pin and GND. LOW = pressed.
|
||
|
||
---
|
||
|
||
## Game Rules
|
||
|
||
- **4 questions**, each answered by 3 physical buttons: 1 correct, 1 half-correct, 1 wrong.
|
||
- The LED strip acts as a **thermometer** starting at the midpoint (4 of 8 sections lit).
|
||
|
||
| Button type | LED feedback | Temperature |
|
||
|---|---|---|
|
||
| Correct | Blinks **green** | −1 section |
|
||
| Half-correct | Glows **orange/yellow** | +1 section |
|
||
| Wrong | Blinks **red** | +1 section |
|
||
|
||
- You can change an answer at any time by pressing a different button in the same group.
|
||
- **Win condition**: all 4 correct answers selected → thermometer reaches 0 → rainbow win animation plays → game automatically resets and starts over.
|
||
- Press the **reset button** (A1) at any time to reset all answers and return the thermometer to the midpoint.
|
||
- If no button is pressed for **5 minutes** (`INACTIVITY_TIMEOUT`), the game resets automatically.
|
||
|
||
---
|
||
|
||
## Folder Structure
|
||
|
||
```
|
||
ExploringUncertanties/
|
||
├── README.md ← this file
|
||
├── Wiring.md ← full wiring diagrams and pin assignments
|
||
├── game.md ← game design notes (Ilo's spec)
|
||
├── hardware.md ← hardware specs and purchase links
|
||
├── einkaufsliste.md ← shopping list
|
||
├── ExploringUncertanties.ino ← MAIN SKETCH — upload this to the Arduino
|
||
├── LEDStrip/
|
||
│ ├── test/
|
||
│ │ └── test.ino ← LED strip test / setMirroredLED reference implementation
|
||
│ └── betterwinanimation-only.ino ← standalone win animation prototype
|
||
└── button_test/
|
||
└── button_test.ino ← standalone button wiring test
|
||
```
|
||
|
||
**The sketch to upload is `ExploringUncertanties.ino` in the project root.**
|
||
|
||
---
|
||
|
||
## For Claude
|
||
|
||
This section captures the full technical context so future conversations can pick up without re-reading every file.
|
||
|
||
### LED strip physical layout
|
||
|
||
Four 60-LED WS2812B strips are connected end-to-end, alternating direction (snake pattern), giving 240 physical LEDs total. The data pin is A0 (Arduino digital pin 14).
|
||
|
||
The strips form two mirrored pairs:
|
||
|
||
```
|
||
Strip A leds[0..59] → forward (bottom to top)
|
||
Strip B leds[119..60] → reversed (top to bottom) — mirrors strip A
|
||
Strip C leds[120..179] → forward (bottom to top) — mirrors strip A
|
||
Strip D leds[239..180] → reversed (top to bottom) — mirrors strip D
|
||
```
|
||
|
||
Because of this layout, `setMirroredLED(i, color)` is the **only** function you should call to set LEDs. It writes to all four physical positions at once so all strips show the same image:
|
||
|
||
```cpp
|
||
void setMirroredLED(int i, CRGB color) {
|
||
// i ranges 0..59 (BASE_LEDS - 1)
|
||
leds[i] = color; // Strip A
|
||
leds[119 - i] = color; // Strip B (reversed)
|
||
leds[120 + i] = color; // Strip C
|
||
leds[239 - i] = color; // Strip D (reversed)
|
||
}
|
||
```
|
||
|
||
Never write to `leds[]` directly — always go through `setMirroredLED`.
|
||
|
||
### Thermometer model
|
||
|
||
| Constant | Value | Meaning |
|
||
|---|---|---|
|
||
| `BASE_LEDS` | 60 | Total logical positions (0–59) |
|
||
| `NUM_SECTIONS` | 8 | Thermometer sections |
|
||
| `LEDS_PER_SECTION` | 7 | LEDs per section |
|
||
| `ACTIVE_LEDS` | 56 | 56 thermometer positions; i=0–3 always off (physical bottom), i=4–59 active |
|
||
| `LED_BOTTOM_OFFSET` | 4 | Bottom 4 LEDs always off; thermometer starts at i=4 |
|
||
| `BASELINE_SECTIONS` | 4 | Starting state (midpoint) |
|
||
|
||
Color gradient: **blue** (i = 4, cold) → **red** (i = 59, hot) via `blend(CRGB(0,0,180), CRGB(180,0,0), pos)`. Positions 0–3 are always black (physical bottom of the strip).
|
||
|
||
Active LEDs (below the current temperature level) are rendered at `BRIGHT_BRIGHTNESS`. Inactive LEDs (above) are rendered at `DIM_BRIGHTNESS` — still colored, so the full gradient is always visible.
|
||
|
||
### Game state
|
||
|
||
```cpp
|
||
int selectedAnswer[4]; // per question: -1 = no answer, 0/1/2 = button index within group
|
||
int tempSections; // current lit sections (0–8)
|
||
bool gameWon;
|
||
```
|
||
|
||
`tempSections = BASELINE_SECTIONS + wrong_count - correct_count`, clamped to [0, 8].
|
||
|
||
Win = all 4 `selectedAnswer[q] == CORRECT_ANSWER[q]`.
|
||
|
||
### Button mapping
|
||
|
||
```
|
||
buttonIdx = question * 3 + answerWithinGroup
|
||
question = buttonIdx / 3 (0..3)
|
||
answer = buttonIdx % 3 (0..2)
|
||
```
|
||
|
||
Correct answers are configured in `CORRECT_ANSWER[4]` — update these when the actual questions are finalised.
|
||
|
||
### Answer type system
|
||
|
||
Each question has three button types: `ANSWER_CORRECT`, `ANSWER_HALF`, `ANSWER_WRONG`.
|
||
|
||
In `ExploringUncertanties.ino`, find:
|
||
|
||
```cpp
|
||
const int CORRECT_BUTTON[NUM_QUESTIONS] = {0, 1, 2, 0};
|
||
const int HALF_BUTTON[NUM_QUESTIONS] = {1, 2, 0, 1};
|
||
```
|
||
|
||
Each value (0, 1, or 2) is the button index within that question's group. The remaining button is automatically `ANSWER_WRONG`. Update both arrays when the content is finalised.
|
||
|
||
`getAnswerType(question, button)` returns the `AnswerType` enum value for any button press.
|
||
|
||
### Feedback animations
|
||
|
||
| Type | Animation | Temp effect |
|
||
|---|---|---|
|
||
| `ANSWER_CORRECT` | Green blink × 3 | −1 section |
|
||
| `ANSWER_HALF` | Orange/yellow steady glow (700 ms) | +1 section |
|
||
| `ANSWER_WRONG` | Red blink × 3 | +1 section |
|
||
|
||
After any feedback animation, the thermometer is immediately redrawn before the slide animation runs.
|
||
|
||
### Win animation
|
||
|
||
Rainbow HSV sweep forward then backward across all 60 logical positions (using `setMirroredLED`). Plays in a loop until the reset button is pressed.
|
||
|
||
### FastLED setup
|
||
|
||
```cpp
|
||
FastLED.addLeds<WS2812, DATA_PIN, RGB>(leds, NUM_LEDS);
|
||
FastLED.setBrightness(84);
|
||
```
|
||
|
||
Note: the strip is WS2812 (not WS2812B) with `GRB` color order.
|