Battery — tdlidar_battery

Wire a long-running install meter that quietly shows whether the phone is on mains or slowly running itself flat.

Category: Device · Tier: Free · Needs: any iPhone (no special hardware)

What it does

Reports the phone’s own battery so your TouchDesigner project can react when the device starts to drain. You get a level from empty to full plus a charging state (unknown / unplugged / charging / full). It is the simplest way to keep an unattended installation honest: dim the show, post a warning, or log when the phone has fallen off the charger.

OSC in

| address | type | range | rate | |—|—|—|—| | /tdlidar/motion/battery/level | float | 0–1 | on change + ~2 Hz | | /tdlidar/motion/battery/state | float | 0 unknown, 1 unplugged, 2 charging, 3 full | on change |

Outputs

  • out1 (CHOP) — two channels: tdlidar/motion/battery/level (0–1) and tdlidar/motion/battery/state (0–3).

Parameters

| par | default | what it does | |—|—|—| | OSC Port | 9000 | UDP port to listen on (match the app) |

Quick start (beginner)

  1. In the app, the Battery sensor is part of the device/motion bundle — enable it.
  2. Drop tdlidar_battery into your network.
  3. Look at out1: level reads as a 0–1 fader (0.62 = 62%) and state jumps to 2 the moment you plug the phone in.
  4. Wire level into a Text TOP (% formatted) for an at-a-glance battery readout on a status page.

Advanced patterns

  • “On mains vs running down” meter: feed state into a Logic CHOP set to equals 1 (unplugged). When it goes high, you know the phone is now living on its own battery — start a countdown or fade your show toward a safe idle.
  • Low-battery trigger: Math/Range CHOP isn’t needed; just a Logic CHOP on level less than 0.15 to fire a “swap the phone” alert (email DAT, OSC out to a controller, or a flashing Text TOP).
  • Smooth the meter: the level only updates ~2 Hz, so put a Lag CHOP (lag 1–2 s) after it if you are driving an animated gauge — otherwise the needle steps.
  • Drain rate: a Slope CHOP on level gives you discharge speed; a sudden steeper slope often means a heavy GPU mode kicked in on the phone.

Gotchas

  • state is a float even though it encodes 4 discrete states — compare with Logic CHOP, don’t expect clean integers if you do math on it.
  • level only ticks on change plus a slow 2 Hz heartbeat; do not build a smooth animation directly off it without a Lag CHOP.
  • A phone reporting state = 3 (full) while still plugged in is normal — it is not draining, so don’t treat “full” as “about to die.”