Files
2026-04-14 13:39:03 +02:00

192 lines
7.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 | Affected sections light up **green** bottom→top, then fade out | −1 section (−2 if switching from wrong) |
| Half-correct | Affected sections light up **yellow** bottom→top, then fade out | +1 section |
| Wrong | Affected sections light up **red** bottom→top, then fade out | +1 section |
The animation always plays on every button press, even if the temperature doesn't change (re-press). If switching from a wrong answer to correct, 14 LEDs (2 sections) are animated.
- 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
├── dataLogging/
│ ├── README.md ← setup instructions for Raspberry Pi auto-logging
│ ├── log_serial.py ← Python script: logs Arduino serial output with timestamps
│ └── arduino-logger.service ← systemd unit file for auto-start on boot
├── 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
All three types share `playTempAnimation(fromSections, toSections, color)`:
- **Dropping** (correct): animates sections `toSections..fromSections-1` in green
- **Rising** (wrong/half): animates sections `fromSections..toSections-1` in red/yellow
- **Re-press** (no change): animates one section at the current boundary for feedback
The preview temp is computed before state is updated, so the animation always targets the right LEDs.
### 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.