anker-shelly-bridge/docs/RULES.md

Power profiles

A power profile is a plain YAML file linking one Anker SOLIX device to one Shelly switch channel. You can edit it in any text editor.

The Anker device is read-only. The engine reads its telemetry and never sends it a command. The only thing that gets switched is the Shelly.

Layout

device-profiles/anker/     generated, one file per Anker device
device-profiles/shelly/    generated, one file per Shelly device
power-profiles/            yours, hand-edited
state/runtime.json         last known target state per profile
logs/automation.log        action history

Workflow

solixauto discover-anker
solixauto discover-shelly
solixauto new-profile solar-failover --template solar
solixauto fields A1782-<serial>
solixauto run solar-failover --test
solixauto run solar-failover

Anatomy of a rule

- name: grid assist when solar drops
  when: pv_total < 150
  for: 90s
  then: target.on
  priority: 0

when is an expression over any field listed in the Anker device profile, under readable or derived. solixauto fields <device> prints them with current sample values.

for is the dwell time. The condition must stay true for this long before anything happens. Without it, a cloud passing over your array would cycle the relay repeatedly.

then is target.on, target.off, or none.

priority breaks ties. If two rules are ready at the same moment and disagree, the higher number wins. A low-battery override should outrank normal solar logic.

Use a deadband

This is the single most important thing to get right:

# WRONG - will chatter around 200W
- when: pv_total < 200
  then: target.on
- when: pv_total > 200
  then: target.off

# RIGHT - 150W of deadband between the two
- when: pv_total < 150
  then: target.on
- when: pv_total > 300
  then: target.off

--test warns when it detects the same threshold used for both directions.

Useful automations

Solar failover. Solar covers the load most of the day; pull from the wall only when production drops.

- name: grid assist when solar drops
  when: pv_total < 150
  for: 90s
  then: target.on

- name: release grid when solar recovers
  when: pv_total > 300
  for: 2m
  then: target.off

Low-battery charge. No solar involved.

- name: charge when battery is low
  when: battery_soc <= 15
  for: 30s
  then: target.on

- name: stop charging when battery is healthy
  when: battery_soc >= 60
  for: 2m
  then: target.off

Overnight top-up. Combine conditions.

- name: cheap overnight charging
  when: battery_soc < 80 and pv_total < 20
  for: 5m
  then: target.on

Load shedding. Cut a non-essential circuit when the battery is draining.

- name: shed load
  when: battery_soc < 30 and ac_input_power == 0
  for: 2m
  then: target.off

Thermal guard. Higher priority so it outranks everything else.

- name: stop charging when hot
  when: temperature >= 45
  for: 60s
  then: target.off
  priority: 200

Safety settings

stale_after and on_stale control what happens when telemetry stops arriving. Rules are never evaluated against stale data.

• hold keeps the relay wherever it is. Default and safest.
• safe_state drives the relay to the safe_state: value.
• stop exits the engine.

limits is a hard backstop independent of dwell times:

limits:
  min_seconds_between_actions: 60
  max_actions_per_hour: 20

If a rule somehow oscillates, this caps the damage.

Notifications

Turn them on in the profile:

notifications:
  enabled: true
  channels: [ntfy]
  title: "{profile}"
  template: >-
    {source_name} battery {battery_soc}%, solar {pv_total}W.
    {target_name} turned {action}.
  throttle: 5m
  on:
    - action

Then per rule, notify: on or notify: off to include or exclude it. Omit it to inherit. A rule can also carry its own wording:

- name: emergency charge on low battery
  when: battery_soc <= 15
  for: 30s
  then: target.on
  priority: 100
  notify:
    template: >-
      {source_name} has {battery_soc}% battery remaining.
      {target_name} turned on AC power.
    priority: high

Template fields

Any field from the device profile works, plus:

{profile}         power profile name
{rule}            rule that fired
{condition}       the rule's when expression
{action}          ON or OFF
{action_word}     on or off
{source_name}     Anker device name, falling back to model
{source_model}    e.g. SOLIX F3000
{source_serial}
{target_name}     Shelly device name, falling back to model
{target_model}
{target_host}
{time}

--test checks every field name in your templates against the device profile, so a typo is caught before it ships a message reading battery ?%.

Channels

Credentials live in ../notifications.yaml, which is created with owner-only permissions. Power profiles stay free of secrets.

• ntfy - recommended. Free, no account. Install the app, pick an unguessable topic name, subscribe. Anyone who knows the topic can read your alerts, so make it long.
• pushover - $5 once per platform. Priority 2 alerts repeat until you acknowledge them.
• email - SMTP. Gmail requires an App Password.
• telegram - free bot.
• webhook - Slack, Discord, or generic JSON.
• desktop - local notification on the machine running the engine. Uses osascript on macOS, notify-send on Linux, PowerShell on Windows. Run solixauto doctor to see which backend was detected.

The Anker app and the Shelly app cannot receive custom push messages from an external program, so neither is an option here.

Test a channel:

solixauto notify-test
solixauto notify-test --channel ntfy

Throttling

throttle is per rule. An identical repeated message inside the window is dropped. This is separate from the switching rate limits, so a stuck condition cannot flood your phone even if the relay is behaving.

Other events

on:
  - action
  - stale

stale fires once when telemetry stops arriving and is worth enabling if you depend on the automation.

Testing

solixauto run <profile> --test

Validates syntax, checks that every field you reference actually exists on the device, warns about missing deadbands and short dwell times, connects to both devices, and prints what each rule would do right now. Nothing is switched.

solixauto run <profile> --test --offline

Same checks without connecting. Rules are evaluated against the sample values captured during discovery.