Pour light from the magic light cup into an LED

The magic light cup module has a tilt switch and an LED in one. Tip it over like a cup and its light slowly "pours" into an LED on the breadboard; stand it up again and the light flows back....
  • Level:Beginner
  • Duration: 30 min
  • Ages 10+
  • Platform: Arduino

What you'll need

Tools for this lesson

Helpful for this build. Open a tool to see tips and more projects that use it.

Pour light from the magic light cup into an LED – EEMENTOR STEM™ lesson

Imagine holding a glass of light: tip it over and the light pours out into another glass, slowly, until the first one is empty. With the magic light cup module from the 45-in-1 Sensor Kit you can make exactly this trick. The little board has a tilt switch and an LED on it. Hold it upright and its LED shines; tip it over and the light fades out of the cup and into an LED on your breadboard, as if it were flowing across. Stand it up again and the light flows back. The fading is done with PWM, and the trick that keeps the total amount of light the same is one line of maths.

What you'll learn

  • How a tilt switch tells upright from tipped over
  • How analogWrite() and PWM make an LED fade smoothly
  • How to change a value a little at a time with millis(), without delay()
  • How to share one amount between two LEDs, so the total always stays the same

What you need

  • UNO R3 board and USB cable (UNO R3 Starter Kit)
  • Magic light cup module (45-in-1 Sensor Kit)
  • 1 yellow LED and 1 resistor, 220 Ω (UNO R3 Starter Kit)
  • Breadboard and jumper wires (UNO R3 Starter Kit)

Meet the magic light cup

The module has four pins. S is the tilt switch, L is the module's LED (it already has its own resistor on the board), + is the supply and G is GND. Inside the little silver or glass tube there is a ball or a drop of metal. When the module stands upright it rolls down and connects two contacts; tip it over and it rolls away, and the contacts open. Some modules use a tiny drop of mercury in a glass tube. Mercury is poisonous, so never break the tube, and don't play with a cracked one.

Wiring

Breadboard wiring diagram: Pour light from the magic light cup into an LED
Breadboard view. Check each connection against the wiring table below.

Build it step by step

Plug in all the parts first, then add the wires in this order. In each picture the new wires are bright and the ones from earlier steps are faded. Click a picture to see it larger.

Step 1 of 3: Power rails: 5V and GND from the UNO
Step 1. Power rails: 5V and GND from the UNO
Step 2 of 3: Magic light cup: G and + to the rails, S → pin 2, L → pin 5
Step 2. Magic light cup: G and + to the rails, S → pin 2, L → pin 5
Step 3 of 3: Glass LED: pin 6 through a 220 Ω resistor
Step 3. Glass LED: pin 6 through a 220 Ω resistor
From To
Magic light cup G GND
Magic light cup + 5V
Magic light cup S UNO pin 2
Magic light cup L UNO pin 5
UNO pin 6 220 Ω resistor → yellow LED long leg
Yellow LED short leg GND

Sensor modules from different makers can label and order their pins differently. Always follow the labels printed on your module.

Pins 5 and 6 both have a ~ next to them on the UNO: they can make PWM, which is needed for fading. The yellow LED is the second "glass".

FREE

Build this circuit in EEMENTOR Lab

Wire it yourself in your browser before you touch a real wire. No sign-up, nothing to install.

The UNO and the parts for this lesson laid out in EEMENTOR Lab, ready to wireBuild it yourself
  1. The UNO and this lesson’s parts are already placed. Wire them using the wiring table above. Pins with no wire show red.
  2. Missing a part? Add it from the parts list on the left.
  3. Press Run, then try the inputs: click, hold or slide them under Selected.
  4. Then try this lesson’s sketch: paste it into the Code tab and press Compile & Run.

EEMENTOR Lab is free and in beta. Results are a guide; a real build can differ slightly. About the Lab

The sketch

// Pour light from the magic light cup into an LED: tilt the cup and the light flows over, slowly.
const int SWITCH_PIN = 2;      // magic light cup S: its tilt switch
const int CUP_LED = 5;         // magic light cup L: its own LED (a PWM pin)
const int GLASS_LED = 6;       // the LED on the breadboard (a PWM pin)
const int STEP_MS = 8;         // time between two small steps: bigger = slower pouring
const bool SWAP = false;       // true if the light flows the wrong way when you tilt

int cup = 255;                 // how bright the cup is (0 to 255); the glass gets the rest
int lastShown = -1;
unsigned long lastStep = 0;

void setup() {
  pinMode(SWITCH_PIN, INPUT_PULLUP);
  pinMode(CUP_LED, OUTPUT);
  pinMode(GLASS_LED, OUTPUT);
  Serial.begin(9600);
  Serial.println("Tilt the cup to pour the light");
}

void loop() {
  bool tilted = digitalRead(SWITCH_PIN) == HIGH;   // the switch opens when the cup is tipped over
  if (SWAP) tilted = !tilted;

  if (millis() - lastStep >= STEP_MS) {            // one small step every 8 ms
    lastStep = millis();
    if (tilted && cup > 0) cup--;                  // pour from the cup into the glass
    if (!tilted && cup < 255) cup++;               // stand it up again: the light flows back
  }

  analogWrite(CUP_LED, cup);                       // together they always make 255
  analogWrite(GLASS_LED, 255 - cup);

  int percent = cup * 100L / 255;
  if (percent % 25 == 0 && percent != lastShown) { // report at 100, 75, 50, 25 and 0 %
    lastShown = percent;
    Serial.print("Cup: ");
    Serial.print(percent);
    Serial.print(" %   Glass: ");
    Serial.print(100 - percent);
    Serial.println(" %");
  }
}

Try it

  1. Upload the sketch and open the Serial Monitor at 9600 baud. With the module upright, its LED is bright and the yellow LED is off: "Cup: 100 % Glass: 0 %".
  2. Slowly tip the breadboard (or bend the module on its pins) until the module lies on its side. The module's LED fades out while the yellow LED fades in, in about 2 seconds.
  3. The Serial Monitor counts the pouring in quarters: 75 %, 50 %, 25 %, 0 %.
  4. Stand it up again: the light flows back into the cup.
  5. Tip it over and stand it up again after about one second: the light turns round halfway and flows back, with both LEDs glowing for a moment.
  6. If the light flows the wrong way (the cup empties while it stands upright), set SWAP = true and upload again. Make it pour slower with a bigger STEP_MS.

What you should see

Serial Monitor at 9600 baud counting the pour in quarters, and four states of the magic light cup and the yellow LED: upright, tipped for 1 s, on its side and stood up again.

How it works

Inside the tilt switch a ball closes or opens two contacts, read with INPUT_PULLUP as LOW or HIGH; PWM waveforms for 0, 128 and 255; cup plus glass always make 255.

The tilt switch is read with INPUT_PULLUP: the UNO connects pin 2 to 5V through a resistor inside the chip. Upright, the switch is closed and pulls the pin to GND, so it reads LOW. Tipped over, the switch opens and the pull-up makes it read HIGH. The sketch calls HIGH "tilted".

An Arduino pin can only be on or off, but analogWrite() switches it on and off about 1000 times a second. The share of time it is on (the duty cycle) sets how bright the LED looks: 255 means always on, 128 means half the time, 0 means off. Your eye is too slow to see the flicker and sees a dimmer light instead. This is PWM, pulse-width modulation.

The variable cup holds how bright the cup is. Every 8 ms, while the module is tilted, it gets one step smaller; while it is upright, one step bigger. The cup gets cup and the glass gets 255 - cup, so together they always add up to 255: no light is lost or made, it only moves, like water. Using millis() instead of delay() keeps the loop free to read the switch all the time, so the pouring changes direction the moment you tip the cup back. The tilt alarm uses a tilt switch too, and the digital hourglass "pours" sand LED by LED.

Try this next

  • Make it pour faster the further you tip it: add the ball tilt switch module as a second sensor, and pour twice as fast when both are tilted.
  • Your eye sees brightness unevenly: the change from 0 to 50 looks much bigger than from 200 to 250. Use analogWrite(GLASS_LED, (255L - cup) * (255 - cup) / 255) for a smoother-looking pour (this is called gamma correction).
  • Add a passive buzzer that plays a rising note while the glass fills up, like water filling a bottle.
  • Use the RGB LED module as the glass and let the colour change from blue to white as it fills, as in mixing colours with the RGB LED.

Troubleshooting

  • Nothing changes when you tip it: check the S wire on pin 2 and the module's + and G. Tip it fully on its side: some tilt switches only open past 45°.
  • The light flickers back and forth while you hold it still: the switch is right at its tipping point and bouncing. Hold it more upright or more tipped.
  • The module's LED never lights: check the L wire on pin 5. On some modules the pins are in a different order: follow the labels on your board.
  • The yellow LED never lights: turn it round (long leg to the resistor) and check the wire on pin 6.
  • It pours the wrong way: set SWAP = true.