Guessing when Stage 2 hits your suburb is a terrible automation strategy. A missed phone alert does not shed the geyser, and a static cron job does not survive a stage change. You want a live area schedule in Home Assistant—stage, next start, and “starts in N minutes”—so automations fire from facts.

This DIY installs WernerHP’s community Load Shedding integration (via HACS), wires it to the EskomSePush (ESP / SePush) API, picks a SePush v3 area ID, and sketches warning / start-end patterns from the integration’s own examples. It complements earlier MeshNest posts on smart-plug tiers and UPS/NUT: the schedule is the forecast; plugs and UPS are how you act.

Why a schedule sensor beats guessing

Home Assistant needs trustworthy triggers. Official docs cover state, numeric-state, time, and attribute triggers you will reuse: https://www.home-assistant.io/docs/automation/

With this integration you typically get:

• Stage sensor — e.g. “Stage 2” or “No Load Shedding” (README Sensor section).
• Area sensors — whether your suburb is shedding, plus attributes such as starts_in, ends_in, and end_time.
• Lead time — a 15-minute warning, then start/end actions when the area sensor flips.

Those sensors drive keep / shed / restore plug tiers and UPS monitoring from earlier MeshNest DIY posts—do not rebuild those guides here; get the schedule working first.

Step 1: Get an EskomSePush API key

The Load Shedding integration talks to the EskomSePush API. Product overview: https://sepush.co.za/

1. Read the API licence before you subscribe—esp. free-tier and reasonable-usage clauses: https://esp.info/license-agreement
2. Get a key from the official Gumroad listing: https://eskomsepush.gumroad.com/l/api
3. Per the integration README, the free tier is 50 requests per day. You can pay for a higher limit on that same page.

Quota care (do this once, do it right):

• Store the key in Home Assistant’s config flow / secrets—never paste it into a public dashboard or GitHub gist.
• The README warns: do not use more than one API key from the same IP—your key can be blocked.
• Free accounts are for non-commercial / home-residence use under the licence; keep call volume sensible and stay on the current API version.

Step 2: Install HACS (if you do not have it yet)

HACS is how most people install community integrations. Overview: https://www.hacs.xyz/ · Download by install type: https://www.hacs.xyz/docs/use/download/download/

• OS / Supervised — add https://github.com/hacs/addons, install and start Get HACS, follow its logs, restart, then add the HACS integration under Settings → Devices & services.
• Container / Core — run the official script from the docs (wget -O - https://get.hacs.xyz | bash -), restart, add HACS.

Follow HACS’s download page for your exact install—you need HACS in the sidebar before the next step.

Step 3: Install Load Shedding via HACS

Integration repository and README: https://github.com/wernerhp/ha.integration.load_shedding

1. Open HACS → Integrations → Explore & Download Repositories.
2. Search for Load Shedding.
3. Select Load Shedding: A Home Assistant integration to track your load shedding schedule and download it with HACS.
4. Restart Home Assistant if prompted.
5. Settings → Devices & services → Add Integration → search Load Shedding (or use the README’s My Home Assistant config-flow link).

Manual install (unzip into config/custom_components, restart, add integration) is documented in the same README if you prefer not to use HACS.

Step 4: Config flow — API key and area search

Paste your ESP API key and search for your area by name. Select it in the UI so you get a current SePush v3 area ID—do not hand-type old IDs from screenshots.

SePush v3 migration (existing users): area IDs changed format:

• v2 (old) — hyphens, e.g. eskde-10-fourways
• v3 (current) — underscores, e.g. za_gt_jhb_fourways_4pef

Pre-migration hyphen IDs may break. The README says the integration raises a Repairs issue (Settings → Repairs). Fix: Settings → Integrations → Load Shedding → options → remove affected area(s) → re-add by searching so you get a v3 ID.

Step 5: Sensors you will use

After a successful config flow, the integration creates sensors you can inspect under Developer Tools → States. Exact entity_id strings depend on your areas—always replace examples with your entities.

• Stage sensor — state reflects the current load-shedding stage (e.g. Stage 2) or No Load Shedding when suspended, per the README Sensor section.
• Area sensor(s) — track whether your suburb is currently in a shedding slot; example automations use attributes such as starts_in, ends_in, and end_time.

Confirm attributes on your entities before copying any YAML. Entity names in public examples are the author’s—not yours.

Step 6: Automation patterns (warning + start/end)

The integration ships example automations. Treat them as patterns: paraphrase the idea, then adapt. Official examples live under the repo’s examples/automations/ folder:

• 15-minute warning: https://github.com/wernerhp/ha.integration.load_shedding/blob/master/examples/automations/load_shedding_warning.yaml
• Start / end actions: https://github.com/wernerhp/ha.integration.load_shedding/blob/master/examples/automations/load_shedding_start_end.yaml
• Stage-change announcements and a 2-hour warning are also listed in the README Automation Ideas section.

Pattern A — 15-minute warning

Idea from the warning example: when your area sensor’s starts_in drops below 15 and stage is still active (stage > 0), notify yourself (push, TTS, Telegram). Optionally gate on a wake/sleep window so overnight alerts stay quiet.

Use the lead time to shed early—heaters, geyser relays, dishwashers—so UPS runtime stretches for keep-tier loads (router, ONT, HA host, fridge).

Pattern B — start / end of shedding for your area

Idea from the start/end example: trigger when the area sensor goes off → on. Actions are yours—dim lights, pause non-essentials, snapshot a scene to restore later. The example waits on ends_in then restores—adapt carefully and substitute your own entity_id values.

Pair with NUT UPS on-battery detection when you have it: schedule says “about to shed”; UPS says “grid dropped.” Together they cut false calm and false alarms.

Home Assistant automation triggers and conditions reference: https://www.home-assistant.io/docs/automation/

Quota and rate care (keep the free key alive)

• 50 requests/day on the free key (README). Do not add polling that hammers the API—the integration already coordinates updates.
• One key per IP — multiple keys from the same address risk a block (README warning).
• Do not share the key; the licence forbids sharing keys and creating accounts for others.
• Need more volume? Use a paid plan on the Gumroad API page—do not multiply free keys.

Next steps — plugs and UPS, not more schedule YAML

Once stage and area sensors are stable:

1. Smart-plug tiers — keep / shed-early / restore-carefully labels driven by the 15-minute warning and start/end sensors (see the earlier MeshNest DIY on load-shedding-ready smart plugs).
2. UPS / NUT — confirm real grid loss and battery percent so you shed harder when runtime is short (see the MeshNest DIY on UPS monitoring with NUT).
3. Local mesh — prefer Zigbee/MQTT plugs that keep working when the ISP path dies (see the Zigbee2MQTT USB coordinator DIY).

Dashboards are optional polish: the README links Mushroom chips, markdown status alerts, and calendar card examples under examples/dashboards/ if you want a wall panel later.

Checklist

• Read https://esp.info/license-agreement and obtain a key from https://eskomsepush.gumroad.com/l/api
• HACS installed per https://www.hacs.xyz/docs/use/download/download/
• Load Shedding downloaded from HACS; config flow completed with a v3 underscore area ID
• Stage + area sensors verified in Developer Tools
• Warning and start/end automations adapted from the official examples—with your entity IDs
• Single API key, no duplicate keys from the same IP, free quota respected

Source of truth for install, sensors, SePush v3 migration, and examples remains the integration README: https://github.com/wernerhp/ha.integration.load_shedding — product context at https://sepush.co.za/