Examples needed for Solarbank 2 schedule structure

[thomluther]

The Schedule structure for Solarbank 2 should be pretty different to Solarbank 1 since it supports weekdays and less settings per interval.
Examples are needed how the new structures look like and how it can be changed via an API Endpoint.

• Can the set_device_load endpoint be used to apply a new solarbank 2 schedule (it did not work for solarbank 1)
• What is the minimum structure that must be provided via the endpoint to create a new interval?
• What are changable fields in the schedule structure that can be modified and will be applied by Solarbank 2?

A new helper method has to be developped to simplify Solarbank 2 schedule modifications. This should NOT be merged with Solarbank 1 helper method, since that is already extremely complex to cover all cases.
Schedule modification with Solarbank 2 are not that important, since power automation can be done in AI mode via the smartmeter.

[thomluther]

Can anybody export some owner account examples with various schedules defined, using all days or just specific day intervals.
We need examples for the new SB2 schedule structure and values provided for various schedule interval settings....

[thomluther]

see here for new schedule example. Requires set and get_device_parm endpoints with dev_parrm = 6

[thomluther]

When I query device_parm with param_type 6 against SB1 site_id I get following:

  "data": {
    "param_data": "{\"mode_type\":0,\"custom_rate_plan\":null,\"blend_plan\":null,\"default_home_load\":0,\"max_load\":0,\"min_load\":0,\"step\":0}"
  },

This could be the minimum required structure to send when no SB2 type schedule is defined on the site, but typically the minimum structure should only contain the settable paramters. Not sure if the default home load can be set for SB2? For SB1 this is fix 200 W when no interval defined.
Also the min and max fields cannot be set typically, they should be filled automatically by the appliance. Maybe they are just 0 for SB1?

[Lenoirio]

@thomluther As promised, here the Rust structs that I use for deserialization/serialization of the SB2 schedules. As mentioned in the other thread, the UI make sure that those structures make sense and are not overlapping. I haven't tested how the endpoint reacts if you send non-sense schedules.

#[derive(Debug, Serialize, Deserialize)]
pub struct SchedulesParam {
    pub mode_type: i32,
    pub custom_rate_plan: Option<Vec<CustomRate>>,  // optional, in case of AI-config it could be null
    pub default_home_load: i32,                     // default 200 (power used for time-ranges not covered by the schedules)
    pub max_load: i32,
    pub min_load: i32,
    pub step: i32                                   // always 10, it's the step for +/- used by the UI
}

#[derive(Debug, Serialize, Deserialize)]
pub struct CustomRate {
    pub index: i32,
    pub week: Vec<i32>,      // weekdays this entry belongs to (0==Sunday ... 6==Saturday)
    pub ranges: Vec<RangeEntry>
}

#[derive(Debug, Serialize, Deserialize)]
pub struct RangeEntry {
    pub start_time: String,     // e.g. "08:00" or "22:30"  !UI uses a granularity of 30min!
    pub end_time: String,
    pub power: i32
}

[thomluther]

Here are 2 example responses with the same SB2 schedule:
Automatic Mode (AI): mode_type = 1
"param_data": "{\"mode_type\":1,\"custom_rate_plan\":[{\"index\":0,\"week\":[0,1,2,3,4,5,6],\"ranges\":[{\"start_time\":\"00:00\",\"end_time\":\"24:00\",\"power\":0}]}],\"blend_plan\":null,\"default_home_load\":200,\"max_load\":800,\"min_load\":0,\"step\":10}"

Manual user mode: mode_type = 3
"param_data": "{\"mode_type\":3,\"custom_rate_plan\":[{\"index\":0,\"week\":[0,1,2,3,4,5,6],\"ranges\":[{\"start_time\":\"00:00\",\"end_time\":\"24:00\",\"power\":0}]}],\"blend_plan\":null,\"default_home_load\":200,\"max_load\":800,\"min_load\":0,\"step\":10}"
So not only the schedule should be changeable with the set_device_parm endpoint, but also the user mode.
If Anker will ever support the user mode setting as part of the schedule, the whole structure would need to change, since the user mode is currently an overall setting in the structure.

@Lenoirio When you got some time, can you please try whether you can switch the user mode just by passing back the schedule structure with changed mode_type setting?
If that works reliably, there is an automated way to switch user mode as well

[thomluther]

The api cache and solarbank monitor now support the new SB2 schedule query and display.
Example:

Schedule  (Now): 09:44:27 UTC +0200      System Preset :    0 W
Usage Mode     : Manual (3)              Sched. Preset :  120 W
ID Start End   Output Weekdays
 0 00:00 24:00  110 W Sun,Sat
 1 00:00 08:00  100 W Mon,Tue,Wed,Thu,Fri
 1 08:00 22:00  120 W Mon,Tue,Wed,Thu,Fri
 1 22:00 24:00   90 W Mon,Tue,Wed,Thu,Fri

This needs further testing for correctness:

• Is the Sched. Preset reflecting the correct output according to the defined schedule and weekday?
• Is the Usage mode correctly displayed
• Is it correct, that weekdays cannot overlap in the daily range definitions? In other words, can a weekday be selected only once for a schedule definition, where in the structure each day schedule has a separate index number. So same weekday must not occur in two different index numbers. Otherwise there could be conflicting definitions for a day schedule...
• I wonder whether there exists Usage mode 2. I assume there should be a temporary manual mode when Automatic mode is active but connection between Solarbank and Smartmeter is lost. Maybe some could test that in reality, whether this will change the mode number as well...

[Lenoirio]

"So same weekday must not occur in two different index numbers."
(Seen from UI): Yes, as soon as you select one day for an entry (which can have several time-ranges), it's no longer possible to select that day in a complete new entry. So a week-number (0..6) can only appear in one of the week-arrays.

"Is the Sched. Preset reflecting the correct output according to the defined schedule and weekday"
Where do you get that number from? If it's the "retain_load" from scene-info, then yes, this is the value that comes from the schedule-setup (changes immediately, no update of the SolarBankInfo needed (that is_display_data=false misery))

Regarding the AI/manual switch, I'll test that later. I can only check what the UI shows tough because I have no Anker-smartmeter installed (yet).

[thomluther]

"So same weekday must not occur in two different index numbers." (Seen from UI): Yes, as soon as you select one day for an entry (which can have several time-ranges), it's no longer possible to select that day in a complete new entry. So a week-number (0..6) can only appear in one of the week-arrays.

Thanks for confirming this

"Is the Sched. Preset reflecting the correct output according to the defined schedule and weekday" Where do you get that number from? If it's the "retain_load" from scene-info, then yes, this is the value that comes from the schedule-setup (changes immediately, no update of the SolarBankInfo needed (that is_display_data=false misery))

The Sched preset is what the Api extracts from the schedule depending on actual time. It is what will be used to update the number entity in the HA integration which allows to modify the system output preset.
What you see under Retain Load is what the system is applying, depending on usage mode and scheduled preset and for SB1 also on other settings in the schedule interval.

• Sched. Preset = what SHOULD be applied actually if the schedule is used.
• Retain Load = what is applied actually by the appliance

Regarding the AI/manual switch, I'll test that later. I can only check what the UI shows tough because I have no Anker-smartmeter installed (yet).

OK that is interesting. I thought you have one. So maybe mode 1 is not the standard Automatic mode, because you cannot use that mode without Smartmeter. It would always default back to the schedule when no smart meter installed.
That could mean, the normal automatic mode is maybe 2?

[Lenoirio]

@thomluther I did the test with AI / manual
3 = manual mode as we already figured out
1 = AI mode. In my case I got an error-message in the UI telling me that my smartmeter is not correctly working. Which is somewhat true because I have none installed ;-) (but request itself got an Code=0;success)

I could easily set it to 3 again with the next request and everything is still working.

[thomluther]

@Lenoirio
You ran into an interesting point that probably should be prevented by the Api.
So you say that the change request to mode 1 was accepted without error in the Api, and also shown as mode 1 after requery?
But no indication in the response, that this mode cannot be used? So the Api would not receive any indication that the change is really applied?
My hope was that in such missing smart meter connection case, it would apply any other mode or reflect this error somehwere....

If that is not the case, at least any helper method to change the mode for the given site ID should only apply it when the site has also a smartmeter device listed, otherwise a change will be applied that is not going to work and Api user has no clue about this issue...

[Lenoirio]

@thomluther I just repeated the test to answer if I can read-back mode=1. Yes it reads it back.
And for what ever reason: this time the UI didn't show an error but told me that I'm in AI-mode.

Unfortunatley I didn't read-back the first time I tried (when the UI gave me the error-message). But the set_schedule_param call returned Ok in both tries.

[thomluther]

@Lenoirio OK thanks for checking. So definitely no separate mode code when there is no smartmeter connection....
Does the App allow you to switch to AI mode if no smartmeter in the system?
If not, than such an Api request can definitely put the Solarbank in a weird condition which is not possible in the App and it needs to be prevented...

[Lenoirio]

The AI option is greyed if no SmartMeter is installed. Btw: in the meantime I also got a system-msg. (error in SmartMeter-setup) for my second try. So if someone activates AI by API it will lead to a notification sooner or later.

[thomluther]

Ok thx. So I will plan to prevent this switch also in HA with the entity (and later also with the schedule services once that would be implemented)

[thomluther]

@stephan-l @nicolinuxfr
Can someone please export a system as owner after clearing all schedule definitions, so the manual usage mode has no definitions at all?
I need to understand what is the minimal schedule structure that is provided by SB2.

I also need some basic validations of how the request payload must look like for the SB2 schedule to be applied as valid schedule.
You can test that with a custom python module (see the example in README)

The basic code to apply a new schedule is following where myapi is the authenticated api client. It tries to set the new schedule, which will also re_query the device schedule and update the api devices cache, so the print will show the resulting schedule structure. For proper application of the structure, you will also need to check it in the App.

            siteId="your_site_id"
            deviceSn="your_solarbank_sn"
            print(json.dumps((await myapi.set_device_parm(siteId=siteId, paramData=scheduleSB2, paramType="6", deviceSn=deviceSn)), indent=2))
            print(json.dumps(myapi.devices,indent=2))
            print(f"Api Requests: {myapi.request_count}")

For scheduleSB2 please test following minimal structures and let me know which of them works (verified in the App), or which kind of weird effects you might see. The request response might be valid and successfull, and even the subsequent query may show correct schedule structure applied, but it may not be always the case (is sometimes a problem for SB1 when a single range interval was applied)

1. Minimal without read-only fields or rate plan

If there is a rate plan set, will this delete all schedule settings and can be used to reset all to default?

            scheduleSB2 = {
                "mode_type": 3,
                "custom_rate_plan": None,           => Maybe needs to change to [] for passing an empty list to wipe all schedule definitions?
                "blend_plan": None,
            }

2. Minimal with subset of rate plan fields.

Will index number and week days automatically be set?

            scheduleSB2 = {
                "mode_type": 3,
                "custom_rate_plan": [
                    {
                        "ranges": [
                            {
                            "start_time": "00:00",
                            "end_time": "24:00",
                            "power": 110
                            }
                        ]
                    },
                ],
                "blend_plan": None,
            }

3. Minimal with complete rate plan item but no blend plan.

Day range is also incomplete, will that be applied as a full day range like for SB1 schedules? Will the remaining weekdays kept off the applied schedule?

            scheduleSB2 = {
                "mode_type": 3,
                "custom_rate_plan": [
                    {
                        "index": 0,
                        "week": [
                            0,
                            6
                        ],
                        "ranges": [
                            {
                            "start_time": "12:00",
                            "end_time": "18:00",
                            "power": 110
                            }
                        ]
                    },
                ],
            }

4. Complete plan but changed read only fields for default and max setting.

Will the default or max changes have any effect (change the max output setting or the default home load for undefined intervals?
Using 5 minute granularity for times and incomplete day range with gaps (will day gaps be filled when applied?). Does the App show the set time granularity (works for SB1)

            scheduleSB2 = {
                "mode_type": 3,
                "custom_rate_plan": [
                    {
                        "index": 0,
                        "week": [
                            0,
                            6
                        ],
                        "ranges": [
                            {
                            "start_time": "00:00",
                            "end_time": "07:45",
                            "power": 100
                            },
                            {
                            "start_time": "17:05",
                            "end_time": "21:20",
                            "power": 200
                            }
                        ]
                    },
                ],
                "blend_plan": None,
                "default_home_load": 100,
                "max_load": 600,
                "min_load": 0,
                "step": 10
            }

[nicolinuxfr]

I tried to export, but got this error (I just pulled the project) :

Traceback (most recent call last):
  File "/home/nicolas/anker-solix-api/./export_system.py", line 33, in <module>
    import common  # type: ignore  # noqa: PGH003
    ^^^^^^^^^^^^^
  File "/home/nicolas/anker-solix-api/common.py", line 71
    f"{'Usage Mode':<{t1}}: {str(SolarbankUsageMode(usage_mode).name if usage_mode in iter(SolarbankUsageMode) else 'Unknown').capitalize()+' ('+str(usage_mode)+')':<{t2+t3+t4}} {'Def. Preset':<{t3}}: {plan.get("default_home_load",'----'):>4} W"
                                                                                                                                                                                                                    ^^^^^^^^^^^^^^^^^
SyntaxError: f-string: unmatched '('

[thomluther]

Ah right change the double quotes to single quotes in line 71:

  File "/home/nicolas/anker-solix-api/common.py", line 71
    f"{'Usage Mode':<{t1}}: {str(SolarbankUsageMode(usage_mode).name if usage_mode in iter(SolarbankUsageMode) else 'Unknown').capitalize()+' ('+str(usage_mode)+')':<{t2+t3+t4}} {'Def. Preset':<{t3}}: {plan.get("default_home_load",'----'):>4} W"

plan.get("default_home_load",'----')
I will fix that on the common.py on next commit

[nicolinuxfr]

So first, an export with no schedule defined in the app :
no-schedule.zip

For the rest, I'm sorry but I'm always confused on how to create the files. I tried, but get an error each time. Here's what I tried :

import logging, json
import asyncio
from aiohttp import ClientSession
from api import api
import common

_LOGGER: logging.Logger = logging.getLogger(__name__)
# _LOGGER.setLevel(logging.DEBUG)    # enable for detailed Api output

async def main() -> None:
    """Create the aiohttp session and run the example."""
    async with ClientSession() as websession:
        """put your code here, example"""
        myapi = api.AnkerSolixApi(
            common.user(), common.password(), common.country(), websession, _LOGGER
        )
        await myapi.update_sites()
        await myapi.update_site_details()
        await myapi.update_device_details()
        await myapi.update_device_energy()
        
        scheduleSB2 = {
                "mode_type": 3,
                "custom_rate_plan": None,
                "blend_plan": None,
            }
        
        siteId="REDACTED"
        deviceSn="REDACTED"
        print(json.dumps((await myapi.set_device_parm(siteId=siteId, paramData=scheduleSB2, paramType="6", deviceSn=deviceSn)), indent=2))
        print(json.dumps(myapi.devices,indent=2))
        print(f"Api Requests: {myapi.request_count}")


# run async main
if __name__ == "__main__":
    try:
        asyncio.run(main())
    except Exception as err:
        print(f"{type(err)}: {err}")

[thomluther]

Thx for the export, that prooves that the min custom_rate_plan is an empty list, in contrast to the blend_plan which is null !?!
Well, that's the way it is, another inconsistency of the api structures.

  "data": {
    "param_data": "{\"mode_type\":1,\"custom_rate_plan\":[],\"blend_plan\":null,\"default_home_load\":200,\"max_load\":800,\"min_load\":0,\"step\":10}"
  },

So the custom_rate_plan object for SB2 seems to be similar to the ranges object for SB1 schedule responses.
When passing an empty list for custom_rate_plan in the set_device_parm request, this should wipe everything what the user has defined for schedules....
So maybe test 1) above with None for the rate plan may fail, but should work with empty list []. Added that to the section.

@nicolinuxfr , in regards to your pyhton errors, your example works in my runtime (I use VSC with the HA core dev build).
So I assume it is a wrong python runtime setup on your system. If you launch the python code in a virtual environment, you need to make sure that the required pip modules are installed there as well:

• pip install cryptography
• pip install aiohttp
• pip install aiofiles

You can also comment the following lines that just fill the api cache structures to save requests when testing this routine:

       #await myapi.update_sites()
       #await myapi.update_site_details()
       #await myapi.update_device_details()
       #await myapi.update_device_energy()

The set_device_parm helper method does not need it since you have to pass the site ID and device SN.

You may have to run following for your pipenv if you use it, since the aiofiles I had to add later and its not included into the pipfile.lock yet, that is used to sync your venv with the required packages.

pipenv install aiofiles

Running the above will install the package aiofiles and add it to the default packages section in the Pipfile.lock.

[nicolinuxfr]

So I assume it is a wrong python runtime setup on your system. If you launch the python code in a virtual environment, you need to make sure that the required pip modules are installed there as well:

I'm always using this command to launch the files, it works great to export the system : source .venv/bin/activate && pipenv run ./export_system.py

I don't really know Python (obviously…), just enough to know I have to be very careful in order to not mess everything on this computer where Home Assistant (among other things) is also running. 😅

Anyway, even with the aiofiles command, I still have the same error, sorry about that.

[thomluther]

@stephan-l, @chiefymuc, @philippreissing, @lumeenous, is someone of you able to try various schedule formats against the SB2 as described above ?
I'm pretty much done with the Api library for the SB2 and the Smartreader and have the HA Integration ready for most of the stuff.
But need confirmation on what is the minimal schedule to change the usage mode.
Also how to clear the SB schedule completely. Those 2 features should make it in the first release.
Adapting the manual preset via schedule is something that can be added later, this will require another complex helper method once you confirm how the applicable schedule formats have to look like and what will not work.

[andsk8]

My device is currently sleeping, and I have the system configured to aischedule, so I have not set a manual schedule, ever.
This is the export in the state it is right now, I dont know how much it will help, I will play around tomorrow with the manual schedule and export every configuration as a separate zip file.
Let me know if an export like this is what you need or I should change something in how the export is being done.
aischedule.zip

My setup is a Solarbank 2 Pro and the Smart Meter with 2x 445W IBC panels

[thomluther]

My device is currently sleeping, and I have the system configured to aischedule, so I have not set a manual schedule, ever. This is the export in the state it is right now, I dont know how much it will help, I will play around tomorrow with the manual schedule and export every configuration as a separate zip file. Let me know if an export like this is what you need or I should change something in how the export is being done. aischedule.zip

My setup is a Solarbank 2 Pro and the Smart Meter with 2x 445W IBC panels

@andsk8 , one export of this kind after creating a schedule and while the device is online during the day would help to have an actual example config for the latest Api.

However, it does not help so much with the Schedule test cases above.
Those would have to be applied and only the resulting schedule structure returned from the Api is of interest, and of course whether this is also applied by the device itself. There have meen minor flaws with SB1 applying the preset correctly, but I hope this is not the case with SB2 anymore.
Basically I know the schedule structure, but it is open how much of the structure has to be provided for a change, and whether changes through the Api are applied properly.
So the schedule response for each of the test cases above would be sufficient as a starting point

[philippreissing]

@thomluther I tested the above scenarios. All with these commands as described:

print(json.dumps((await myapi.set_device_parm(siteId=siteId, paramData=scheduleSB2, paramType="6", deviceSn=deviceSn)), indent=2))
print(json.dumps(myapi.devices,indent=2))

serial number replaced with <devicesn>.

1. Minimal without read-only fields or rate plan

Output:

true
{
  "<devicesn>": {
    "device_sn": "<devicesn>",
    "schedule": {
      "mode_type": 3,
      "custom_rate_plan": null,
      "blend_plan": null,
      "default_home_load": 200,
      "max_load": 800,
      "min_load": 0,
      "step": 10
    },
    "preset_system_output_power": 200,
    "preset_allow_export": true,
    "preset_charge_priority": 80,
    "preset_power_mode": null,
    "preset_device_output_power": null
  }
}

Result in the app: All schedules deleted.

2. Minimal with subset of rate plan fields.
Output:

(10004) Anker Api Error: Failed to request.
Response Text: {"code":10004,"msg":"Failed to request.","trace_id":"3915abb00626ed6c274b53036ab54908"}
<class 'api.errors.AnkerSolixError'>: (10004) Anker Api Error: Failed to request.

3. Minimal with complete rate plan item but no blend plan.
Output:

true
{
  "<devicesn>": {
    "device_sn": "<devicesn>",
    "schedule": {
      "mode_type": 3,
      "custom_rate_plan": [
        {
          "index": 0,
          "week": [
            0,
            6
          ],
          "ranges": [
            {
              "start_time": "12:00",
              "end_time": "18:00",
              "power": 110
            }
          ]
        }
      ],
      "blend_plan": null,
      "default_home_load": 200,
      "max_load": 800,
      "min_load": 0,
      "step": 10
    },
    "preset_system_output_power": 200,
    "preset_allow_export": true,
    "preset_charge_priority": 80,
    "preset_power_mode": null,
    "preset_device_output_power": null
  }
}

Result in the app:

4. Complete plan but changed read only fields for default and max setting.
Output:

true
{
  "<devicesn>": {
    "device_sn": "<devicesn>",
    "schedule": {
      "mode_type": 3,
      "custom_rate_plan": [
        {
          "index": 0,
          "week": [
            0,
            6
          ],
          "ranges": [
            {
              "start_time": "00:00",
              "end_time": "07:45",
              "power": 100
            },
            {
              "start_time": "17:05",
              "end_time": "21:20",
              "power": 200
            }
          ]
        }
      ],
      "blend_plan": null,
      "default_home_load": 200,
      "max_load": 800,
      "min_load": 0,
      "step": 10
    },
    "preset_system_output_power": 200,
    "preset_allow_export": true,
    "preset_charge_priority": 80,
    "preset_power_mode": null,
    "preset_device_output_power": null
  }
}

Result in the app:

Max load remains at 800W.

I hope this helps!

[thomluther]

@philippreissing Thank you very much for the testing.
It is pretty much what I was expecting. So in principle that can be used to build a helper method for the SB2 schedule modifications and it is only the rate_plan structure that needs to be build from scratch if not existing. The remainder of the schedule object always exists even without defined schedule and can simply be re-used for composing the new schedule object.

One thing that puzzles me are the SB1 preset fields returned by the Api devices cache, They should not be contained in the cache for an SB2 device.

    "preset_allow_export": true,
    "preset_charge_priority": 80,
    "preset_power_mode": null,
    "preset_device_output_power": null

Did you use the latest Api version in main branch for your testing?
Also the usage mode is missing in the output, which is indicating to me that this was probably an older version before I implemented the Usage mode support..

[andsk8]

@thomluther sorry for the delay.

here two exports.

1st: setting the Power usage scneario to Custom mode, and not setting any schedule, so defaulting to 200W as the app mentions. Legend is: "You have not added a solar consumption plan. Your home will be set a 200W output for appliance power consumption"

2nd: Setting an Energy Plan to repeat every day and with a schedule of 800W delievered from 12:00 to 15:00

Let me know if you need different settings.
custom-mode-no-schedule-200w.zip
custom-mode-everyday-12-15-800w.zip

[philippreissing]

@thomluther : I tested with revision 1955faf (1955faf). Should that already include the changes?

[thomluther]

@philippreissing I found the reason for this. Its because the update_sites poller was never run before, so the Solarbank PN and generation was not classified yet. That explains why the SB1 preset fields are generated from the schedule...
Not really a problem, would not happen if the update_sites method is also run before testing the helper method for the schedule update...

[thomluther]

Full schedule modification is now supported with release 2.1.0