Dynamic Load Shedding Script for Energy Management

This sophisticated load-shedding script aims to maintain energy consumption within specified minimum and maximum thresholds by dynamically controlling devices. The script prioritizes devices based on predefined schedules, minimizing power usage while ensuring essential devices remain operational. It offers several strategies to optimize performance, such as setting a significant spread between minimum and maximum power limits and adjusting poll times to reduce unnecessary churn. The script supports both Shelly devices and external devices via webhooks. Notifications can be configured to alert users when devices are toggled. This solution is suitable for environments where energy management is crucial, such as solar power systems or peak demand management.

Load-shedding script will keep measured usage between a low (min) and high (max) total power (watts), by controlling power to other devices.

Key considerations:

1. Make sure the value set for max is greater than the value set for min (10% should be considered the lowest spread, 20% is a better minimum spread)
2. The greater the distance between min and max, the less "churn" you'll have. Setting ample space between these values will make your load shedding more efficient.
3. The lowest value for poll_time should be 60 - during "turn on" cycles, you should allow enough time for inrush spikes to settle.
4. Priority is in order of most important (keep on if possible) to least important.
5. Any device that isn't listed at all, or is left out from all schedules will be unmanaged--never subject to load shedding.
6. Best practice is to name all of the included devices in each schedule, in one of the sets "priority," "on," or "off".

poll_time: minimum time span between applying normal on/off steps
short_poll: when adding devices, highest priority devices are turned on, even if they are presumed to already be on, this shorter time speeds the process

        // JSON schema for input settings:
// devices = [ { "name":,"descr":,"addr":,"gen":,"type":,"id":,"notify":}, # shelly device. descr and notify are optional, notify defaults to false
//             { "name":,"descr":,"on_url":,"off_url":,"notify":},         # webhook example.
//             ...
//           ]
// notify = [ { "name":, "descr":, "url": },                               # each named notifiction can be used in a schedule
//            ...                                                          # occurences of {device}, {state}, and {wattage} will be replaced inline
//          ]
// schedules = [
//               { "name":,"enable":,"start":,"days":,                     # enable is optional, defaults to true, days optional, defaults to SMTWTFS
//                 "descr":,  
//                 "priority":[],                                          # prioritized device list. first is kept on most, last in list is first to shed
//                 "on":[],                                                # devices to keep on. may contain the single entry "ALL", or a list of devices
//                 "off":[],                                               # devices to keep off. a schedule must have at least one of priority, on, off       
//                 "min":,"max":,"poll_time":,"short_poll":,               # if priority is specified, all of these options are required
//                 "notify_on":,"notify_off"                               # notifications are optional
//               },
//               ...
//             ]



/************************   settings  ************************/

Pro4PM_channels = [ 0, 1, 2, 3 ];      // default to sum of all channels for 4PM 
Pro3EM_channels = [ 'a', 'b', 'c' ];   // similar if device is 3EM

max_ = 1200;                 // global max, used only if never defined in schedules
min_ = 900;                  //                    "                       "
poll_time = 300;             // unless overriden in a schedule, defines time between shedding or adding load
short_poll = 10;             // faster cycle time when verifying that an "on" device is still on
logging = false;
kvs_status = false;          // store status in key-value-store
simulation_power = 0;        // set this to manually test in console
simulation_hhmm = "";        // leave "" for normal operation, set to time like "03:00" to test
simulation_day = -1;         // -1 for normal operation, to test, 0=Sunday, 1=Monday...

devices = [ { "name":"Water heater", "descr": "Shelly Pro 3EM", "addr":"192.168.1.105","gen":2, "type":"Switch", "id":100, "notify" : true },
            { "name":"EV charger", "descr": "Shelly Pro 3EM", "addr":"192.168.1.106","gen":2, "type":"Switch", "id":100, "notify" : true },
            { "name":"Pool Pump", "descr": "Shelly Pro 3EM", "addr":"192.168.1.107","gen":2, "type":"Switch", "id":100, "notify" : false },
            { "name":"Oven", "descr": "Shelly Pro 3EM", "addr":"192.168.1.108","gen":2, "type":"Switch", "id":100, "notify" : true },
            { "name":"Air Conditioner", "descr": "Shelly Pro 3EM", "addr":"192.168.1.109","gen":2, "type":"Switch", "id":100, "notify" : false },
            { "name":"Ceiling fan",  "descr": "Shelly 1PM", "addr":"192.168.1.110","gen":1, "type":"relay", "id":0, "notify" : false },
            { "name":"Hot Tub", "descr": "NodeRed endpoint to control non-shelly devices", 
                     "on_url":"http://192.168.2.1:1880/endpoint/hot_tub?state=ON",
                     "off_url":"http://192.168.2.1:1880/endpoint/hot_tub?state=ON",
                     "notify" : false },
            { "name":"Entertainment Center",  "descr": "Shelly Plus 2PM relay single channel",
                     "addr":"192.168.1.114","gen":2,"type":"relay","id":0, "notify" : true },
            { "name":"HVAC",  "descr": "Shelly Plus 1PM with contactor",
                     "addr":"192.168.1.111","gen":2,"type":"relay","id":0, "notify" : true },
            { "name":"Dishwasher",  "descr": "Shelly Plus 2PM relay first channel",
                     "addr":"192.168.1.112","gen":2,"type":"relay","id":0, "notify" : true },
            { "name":"Microwave", "descr": "Shelly Plus 2PM relay second channel",
                     "addr":"192.168.1.112","gen":2,"type":"relay","id":1, "notify" : true },
          ]

notify = [ { "name": "notify off", "descr": "IFTTT webhook to fire when a device is disabled",
              "url":"https://maker.ifttt.com/trigger/send_email/with/key/crLBieQXeiUi1SwQUmYMLn&value1=knobs" },
            { "name": "notify on",
              "url":"https://maker.ifttt.com/trigger/send_email/with/key/crLBieQXeiUi1SwQUmYMLn&value1=sally" },
         ]

schedules = [ { "name":"Daytime Solar", "enable": true, "start":"07:00", "days":"SMTWTFS",
                "descr":"Weekdays, starting 7AM, when solar production ramps up",
                "priority":["HVAC","Oven","Microwave","Entertainment Center","Water heater","EV charger","Dishwasher","Ceiling fan","Pool Pump"],
                "min":2500, "max":3500, "poll_time":300, short_poll:10 },
             { "name":"Evening Time of Use-Peak Demand", "enable": true, "start":"17:00", "days":".MTWTF.",
                "descr":"Weekdays, starting 5PM, returning to grid, time of use/peak demand rates apply with penalty",
                "priority":["HVAC","Ceiling fan","Entertainment Center","Microwave","Dishwasher"],
                "off" : ["Pool Pump"],
                "min":2000, "max":3000, "poll_time":300, short_poll:10,
                "notify_on" : "notify on", "notify_off" : "notify off" },
             { "name":"Weekend Nights Grid", "enable": true, "start":"17:00", "days":"S.....S",
                "descr":"Saturday/Sunday after solar, no Time of Use rates",
                "on" : ["ALL"] },
             { "name":"All Nights Grid", "enable": true, "start":"20:00", "days":"SMTWTFS",
                "descr":"Every day, starting 8PM, returning to grid, time of use/peak demand rates have ended",
                "on" : ["ALL"] },
           ]

/***************   program variables, do not change  ***************/

ts = 0;
idx_next_to_toggle = -1;
last_cycle_time = 0;
channel_power = { };
verifying = false;
days = "SMTWTFS";
last_schedule = -1;
schedule = -1;
device_map = {};
schedule_map = {};
notify_map = {};
priority = [];
queue = []
in_flight = 0;
kvs = { device_states : { }, power : 0, schedule : "none", direction : "coasting" };
last_kv = "";
notify_on = "";
notify_off = "";

function total_power( ) {
    if ( simulation_power ) return simulation_power;
    let power = 0;
    for( let k in channel_power )
       power += channel_power[ k ];
    return power;
}

function callback( result, error_code, error_message, user_data ) {
    in_flight--;
    if ( error_code != 0 ) {
        print( "fail " + user_data );
        // TBD: currently we don't have any retry logic
    } else {
        if ( logging ) print( "success" );
    }
}

function turn( pdevice, dir, notify, wattage ) {
    let device = devices[ device_map[ pdevice ] ];
    let cmd = "";
    if ( dir == "on" && device.presumed_state == "on" )
        verifying = true;
    else
        verifying = false;
    if ( dir != device.presumed_state )
        kvs.device_states[ device.name ] = dir;

    device.presumed_state = dir;
    let on = dir == "on" ? "true" : "false";
    print( "Turn " + device.name + " " + dir );

    if ( simulation_hhmm || simulation_power || simulation_day > -1 ) return;
    if ( def( device.notify ) && device.notify ) {
        if ( dir == "on" && notify_on != "" )
            cmd = notify[ notify_map[ notify_on ] ];
        if ( dir == "off" && notify_off != "" )
            cmd = notify[ notify_map[ notify_off ] ];
        if ( cmd != "" ) {
            cmd = cmd.replace( "{device}", device.name );
            cmd = cmd.replace( "{state}", dir );
            cmd = cmd.replace( "{wattage}", wattage );
            Shelly.call( "HTTP.GET", { url: cmd }, callback, device.name );
            in_flight++;
        }
    }

    if ( def( device.gen ) ) {
        if ( device.gen == 1 )
            cmd = device.type+"/"+device.id.toString()+"?turn="+dir
        else
            cmd = "rpc/"+device.type+".Set?id="+device.id.toString()+"&on="+on
        Shelly.call( "HTTP.GET", { url: "http://"+device.addr+"/"+cmd }, callback, device.name );
        in_flight++;
    }
    if ( def( device.on_url ) && dir == "on" ) {
        Shelly.call( "HTTP.GET", { url: device.on_url }, callback, device.name );
        in_flight++;
    }
    if ( def( device.off_url ) && dir == "off" ) {
        Shelly.call( "HTTP.GET", { url: device.off_url }, callback, device.name );
        in_flight++;
    }
}

function qturn( device, dir, notify, wattage ) {
    if (!def(device)) {
        print("undef in qturn");
        return;
    }
    queue.push( { "device": device, "dir": dir, "notify": notify, "wattage": wattage } )
}

function pad0( s, n ) {
    s = s.toString();
    if ( s.length < n )
        return '0' + s;
    return s;
}

function find_active_schedule( ) {
    let sched = -1;
    let sched_time = '00:00';
    let last_sched = 0;
    let last_time = '00:00';
    let now = new Date();
    let hour = now.getHours();
    let minute = now.getMinutes();
    let start_time = schedules[ 0 ].start;
    let day = now.getDay();
    let hhmm = pad0(hour,2) + ':' + pad0(minute,2);
    if ( simulation_day > -1 )
        day = simulation_day;
    if ( simulation_hhmm != "" )
        hhmm = simulation_hhmm;
    for ( n in schedules ) {
        let s = schedules[ n ];
        if ( def( s.enable ) && ! s.enable ) continue;
        if ( s.start > last_time ) {
            last_time = s.start;
            last_sched = n;
        }
        if ( ! def( s.days ) || s.days[ day ] == days[ day ] ) {
            if ( hhmm >= s.start && s.start >= sched_time && s.start > sched_time ) {
                sched_time = s.start;
                sched = n;
            }
        }
    }
    if ( sched == -1 ) sched = last_sched;
    return sched;
}

function toggle_all( dir, notify, wattage ) {
    for ( let d in devices ) {
        qturn( devices[ d ].name, dir, notify, wattage );
    }
}

function check_queue( ) {
    if ( queue.length > 0 && in_flight < 2 ) {
        let t = queue[0];
        queue = queue.slice(1);
        turn( t.device, t.dir, t.notify, t.wattage );
    }
}

function process_kv( result, error_code, error_message ) {
    if ( last_kv != result.value ) {
        last_kv = result.value;
        let j = JSON.parse( result.value );
        if ( def( j.settings ) ) {
            for ( s in j.settings ) {
                 let setting = j.settings[ s ];
                 if ( def( setting.schedule ) &&
                      def( setting.kvs ) &&
                      setting.schedule in schedule_map  )
                     for ( k in setting.kvs ) {
                         kv = setting.kvs[ k ];
                         if ( def( kv.key ) &&
                              def( kv.value )
                         ) schedules[ schedule_map[ setting.schedule ] ][ kv.key ] = kv.value;
                     }
            }
        }
    }
}

function check_power( msg ) {
    if (!def(msg)) return;
    check_queue();
    let now = Date.now() / 1000;
    let poll_now = false;
    if ( def( msg.delta ) ) {
        if ( def( msg.delta.apower ) && msg.id in Pro4PM_channels )
            channel_power[ msg.id ] = msg.delta.apower;
        if ( def( msg.delta.a_act_power ) )
            for ( let k in Pro3EM_channels )
                channel_power[ Pro3EM_channels[k] ] = msg.delta[ Pro3EM_channels[k] + '_act_power' ];
    }
    kvs.power = total_power( );

    let schedule = find_active_schedule( ); 
    if ( schedule != last_schedule ) {
        kvs.schedule = schedules[ schedule ].name;
        print( "activated " + kvs.schedule );
        let s = schedules[ schedule ]
        if ( def( s.priority ) )
            priority = s.priority;
        else
            priority = [];
        kvs.direction = "loading";
        idx_next_to_toggle = 0;
        if ( def( s.min ) ) min_ = s.min;
        if ( def( s.max ) ) max_ = s.max;
        if ( def( s.poll_time ) ) poll_time = s.poll_time;
        if ( def( s.short_poll ) ) short_poll = s.short_poll;
        if ( def( s.notify_on ) ) notify_on = s.notify_on;
        if ( def( s.notify_off ) ) notify_off = s.notify_off;
        if ( def( s.off ) ) for  (let  d in s.off ) if ( s.off[d] == "ALL" ) toggle_all( "off", notify, kvs.power ) else qturn( s.off[d], "off", notify, kvs.power );
        if ( def( s.on ) ) for ( let d in s.on ) if ( s.on[d] == "ALL" ) toggle_all( "on", notify, kvs.power ) else qturn( s.on[d], "on", notify, kvs.power );
    } 

    if ( now > last_cycle_time + poll_time || verifying && now > last_cycle_time + short_poll ) {
        last_cycle_time = now;
        poll_now = true;
    }
    if ( priority.length ) {
        if ( kvs.power > max_ ) {
            if ( kvs.direction !== "shedding" ) {
                kvs.direction = "shedding";
                idx_next_to_toggle = priority.length -1;
            }
        } else if ( kvs.power < min_ ) {
            if ( kvs.direction !== "loading" ) {
                kvs.direction = "loading";
                idx_next_to_toggle = 0;
            }
        } else if ( kvs.direction !== "coasting" ) {
            kvs.direction = "coasting";
        }

        if ( def( msg.delta ) || schedule != last_schedule ) {
            if ( poll_now ) {
                if ( kvs.direction === "loading" ) {
                    qturn( priority[ idx_next_to_toggle ], "on", notify, kvs.power );
                    if ( idx_next_to_toggle < priority.length -1 ) idx_next_to_toggle += 1;
                }
                if ( kvs.direction === "shedding" ) {
                    qturn( priority[ idx_next_to_toggle ], "off", notify, kvs.power );
                    if ( idx_next_to_toggle > 0 ) idx_next_to_toggle -= 1;
                }
            }
        }
    } else if ( poll_now )
        Shelly.call( "KVS.get", {key:"load-shed-setting"}, process_kv )

    last_schedule = schedule;
    check_queue();
    if ( poll_now && kvs_status )
        Shelly.call( "KVS.set", { key : "load-shed-status", value : JSON.stringify( kvs ) } )
}

function def( o ) {
    return typeof o !== "undefined";
}

function check_devices( l, t, s ) {
    for ( let d in l )
        if ( ! ( l[d] in device_map ) && l[d] != "ALL" )
            print( "Undefined device " + l[d] + " in list '" + t + "' of schedule " + s.name );
}

function init( ) {
    for ( let d in devices ) {
        device_map[ devices[d].name ] = d;
        d.presumed_state = "unknown";
    }
    for ( let sched in schedules ) {
        schedule_map[ schedules[ sched ].name ] = sched;
        let s = schedules[sched];
        s.start = pad0( s.start, 5);
        if ( def(s.off) ) check_devices(s.off, "off", s );
        if ( def(s.on) ) check_devices(s.on, "on", s );
        if ( def(s.priority) ) check_devices(s.priority, "priority", s );
    }
    for ( let n in notify )
        notify_map[ notify[ n ].name ] = n;
}

init();

Shelly.addStatusHandler( check_power );