Power & Sleep

Two power realities, two different owners. Light sleep — standby, suspend-to-idle — belongs to the kernel's idle policy: it happens automatically whenever nothing is running, and there is nothing to call. Soft-off — the deepest state — is explicit-entry only: off() for good, offFor(ms) for a timed sleep.

singleton

Power

import { Power } from '@typecad/hal'

The power-state surface. off() enters the deepest declared power state — deep sleep / soft-off — via sys_poweroff(). The call doesn't return.

Example first

power-down.ts

import { Power, Time } from '@typecad/hal';

// flush whatever matters — RAM is not retained past off()
saveSettings();

await Time.sleep(500);   // let the serial line drain
Power.off();             // enters soft-off — this line never "returns"

Expect the console to go silent — that silence is the effect. RAM isn't retained; there is no resuming the program after off().

Waking back up

wake.ts

// after off(), the board wakes by:
//   • reset — the power / EN button
//   • a wake source — ESP32: a GPIO armed as a wake trigger;
//     STM32: the WKUP pin (PA0 on the Black Pill)
//
// and boot starts over — setup runs from the top, like power-on.

Arming a wake source happens on the pin side — an ESP32 GPIO configured as a wake trigger, or the STM32 WKUP pin. off() only enters the state; what may end it is decided before you call it.

All methods

Method	What it does
off()	Soft-off now — wake by reset or an armed wake source
offFor(ms)	Soft-off with the RTC wake timer armed — reboot after ms milliseconds

method

offFor — the battery cycle

Power.offFor(60_000)

Sleep for a duration: offFor(ms) arms the SoC's RTC wake timer, then enters soft-off. The board reboots on wake (RAM isn't retained), so the semantics are 'sleep for N ms, then run from the top' — the shape of every battery-powered sensor.

Example first

duty-cycle.ts

import { Power } from '@typecad/hal';

// the classic battery pattern: read, publish, sleep, repeat
const readings = await sampleSensors();
await publish(readings);

Power.offFor(60_000);   // soft-off; the RTC wakes the board in one minute
// boot starts from the top — microamps in between

Why light sleep isn't a method

The SoC's devicetree declares its power states as facts, and typeCAD harvests them into the board module (zephyr.power.states.* — inspectable with board()). Of those, the light states are policy: the kernel enters them when the scheduler has nothing to run, which is exactly what an idle embedded program wants. Giving the app a "sleep light" verb would only invite fighting the governor — so in v1 there is no op surface for it. Your program's job is to reach the idle state; the power savings are automatic.

Previous On-Chip Peripherals Next Clock (RTC)