How to add new values into code?

[tp1de]

I would like to add new values / entities into the code. From Discord I got from @MichaelDvP the following introduction:

There is a guide "contributing.md" how to make the PR, but for the code structure you have to read the code.
It's mostly selfexplaining.

Start with reading a simple device like switch.cpp to see the registertelegram() with it's callback process(telegramname).
In the callback the value is read by has_update(..) and publishing the value is handled by the register _device_value().
That's neary all to do.

In thermostat for hc dependend telegrams you have to add a check in heatingcircuit(telegram).

[tp1de]

I would like to start with a first test field for the boiler:

wwsupplyDelta - delta temp for ww load from boiler to dhw :
type 0xEA, offset 0x09, type number (uint8_t), range 5 to 40

Questions: Please correct

1. What are the steps needed to introduce a new entity? (data definition, range, text to display ...)
2. Telegram type 0xEA is already registered so I haven't to do anything?
3. I understand that I need to add then has_update in boiler.cpp (line 614)
4. publishing the value is handled by the register _device_value() - what do I need to do?
5. Anything else?

[tp1de]

I am a bit confused looking in more detail to the code. In lines 619-627 in boiler.cpp wwComfort is defined with offset 9.
(I think the offset is decimal isn't it?).

On my RC310 wwComfort is at offset 0x0D with valid values {"0":"high","216":"eco"}.
On offset 0x09 the wwsuplyDelta is available.

[MichaelDvP]

Steps to do:

• add uint8_t wwSupplyDelta_; to boiler.h (line 90)
• add has_update(telegram, wwSupplyDelta_, 9); to boiler.cpp, line 776 (in telegram 0xEA)
• add register_device_value(DeviceValueTAG::TAG_DEVICE_DATA_WW, &wwSupplyDelta_, DeviceValueType::UINT, nullptr, FL_(wwSupplyDelta), DeviceValueUOM::DEGREES); to boiler.cpp line 471
• add MAKE_PSTR_LIST(wwSupplyDelta, F("wwsupplydelta"), F("supply deltatemperature")) to locale_EN.h, line 570

Min/max values are only for commands, then you have to add a set-callback and min/max to the register_device_value and declare the set-callback in boiler.h and code it in boiler.cpp.

Line 619ff is telegram 0x33, your boiler uses 0xEA, look at line 770 ff.

[tp1de]

Line 619ff is telegram 0x33, your boiler uses 0xEA, look at line 770 ff.

too much code for my old eyes :)

Thanks for the clarification and I will start testing ...

[tp1de]

@MichaelDvP the first steps work. The value is shown correctly with the dashboard and on web-api. Super !

May I get a bit help on the command to change the value?

[MichaelDvP]

Take a look at other writable values from the 0xEA telegram.

• add to the register_device_value after the uom the setting callback , MAKE_CF_CB(set_wwSupplyDelta));
• after the callback you can also add min,max values.
• create a function (around line 1352, near the other ww settings) and add function header to boiler.h.

// set ww supply Delta
bool Boiler::set_wwSupplyDelta(const char * value, const int8_t id) {
    int v = 0;
    if (!Helpers::value2temperature(value, v)) {
        return false;
    }
    write_command(0xEA, 9, v, 0xEA);
    return true;
}

Instead of 0xEA you can also use EMS_TYPE_UBAParameterWWPlus

BTW: the name delta suggests that it is a temperature difference, is it really unsigned? Also for relative values you have to use value2temperature(value, v, true)

[tp1de]

Value changes work now. Thanks, I was missing the MAKE_CF_CB(set_wwSupplyDelta) addition. 👍

I just ask myself how (and where) to add min/max values?
The min/max info should be included in web-api details for the entity as well.

BTW: the name delta suggests that it is a temperature difference, is it really unsigned? Also for relative values you have to use value2temperature(value, v, true)

Yes I just took the name I had from testing. I will check names before continuing.
(in German: Vorlauftemperatur-Erhöhung) - only positive values between 0-40 °C allowed.
Maybe use dhw_flowtemp_increase ????

[MichaelDvP]

(in German: Vorlauftemperatur-Erhöhung)

this is implemented as wwFlowTempOffset_ for the ems-boilers, you only have to add it to 0xEA and modify the set_ww_flowTempOffset to

    if (is_fetch(EMS_TYPE_UBAParameterWWPlus)) {
        write_command(EMS_TYPE_UBAParameterWWPlus, 9, v, EMS_TYPE_UBAParameterWWPlus);
    } else {
        write_command(EMS_TYPE_UBAParameterWW, 5, v, EMS_TYPE_UBAParameterWW);
    }

to add the limits:

    register_device_value(DeviceValueTAG::TAG_DEVICE_DATA_WW,
                          &wwFlowTempOffset_,
                          DeviceValueType::UINT,
                          nullptr,
                          FL_(wwFlowTempOffset),
                          DeviceValueUOM::DEGREES_R,
                          MAKE_CF_CB(set_ww_flowTempOffset),
                          0, 
                          40);

[tp1de]

this is implemented as wwFlowTempOffset_ for the ems-boilers, you only have to add it to 0xEA and modify the set_ww_flowTempOffset to

So I should cancel my changes I made until now?

[MichaelDvP]

So I should cancel my changes I made until now?

Adapt them to use same names as other boilers. Yes, sometimes we have to revoke changes if we find a better way.

[tp1de]

@MichaelDvP
I try to understand how to handle/define enums and link enum entries to hex-values for read an write.

I see that the enum texts are in locale_EN.h but I do not really understand the steps needed to introduce a new enum list and allocate the enum entries to hex-values for read and write.

Could you please advice how to do this?

[tp1de]

For a first try I would like to introduce boiler.wwcomfort - type 0xEA offset 0x0D with values {"0":"high","216":"eco"}

[MichaelDvP]

Enums are normaly numbered 0, 1, 2.., having the DeviceValueType::ENUM and a pointer to a list of entries in the option field of register_device_value(). The list is created in locale_EN.h with MAKE_PSTR_LIST() makro.
Reading is with has_update() or, if the index starts not at zero, with has_enumupdate() where the startvalue is set.
For writing there is the Helpers::value2enum() giving back the index of the text from the enum list..

boiler.wwcomfort is a bit special, because it's not really enum, but contains some fixed signed values for reducing the ww temperature. "eco" is -40°C (0xD8) and "intelligent" -20°C (0xEC). I'm not sure if other values are accepted in this field, my boiler does not have it (fixed to 0x00 (hot), not writable). You can copy the logic from telegram 0x33 to 0xEA offset 13 and modfiy the set_ww_mode() to check EA telegram and write to it.

[tp1de]

boiler.wwcomfort is a bit special, because it's not really enum, but contains some fixed signed values for reducing the ww temperature. "eco" is -40°C (0xD8) and "intelligent" -20°C (0xEC). I'm not sure if other values are accepted in this field, my boiler does not have it (fixed to 0x00 (hot), not writable). You can copy the logic from telegram 0x33 to 0xEA offset 13 and modfiy the set_ww_mode() to check EA telegram and write to it.

The wwcomfort logic on my RC310 is different. If comfort is set to high, then the defined hysteris is used and the ww storage is heated whenever temp is below defined hysteresis - so with 6°C hysteresis approx. 5-6 times a day. With the use of eco the hysteresis is approx. 2-2.5 times as large and 2 heating cycles per day are enough. But in between the ww temp will be lower then with comfort=high.

[tp1de]

The existing wwcomfort has 3 enum entries: Hot, Eco, Intelligent.
The RC310 only has 2 possible values: High, Eco.

What would you recommend? Use the existing one or make a new one wwcomfort1 ?

[MichaelDvP]

I do not really understand what I have to do there? After line 204 because thermostat id = 0x10 for RC310?

RC310 is a master-thermostat, there is no adaptation needed. RC200 is compatible, but a single hc thermostat (0x18 for hc 1, 0x19 for hc2, etc, Combining multiple RC200 is matched there to a "master" at 0x18). The 0x10 section is only for junkers, where 0x10 controlls hc1 and hc2 and for hc3 there is an extra thermostat.
Please add the telegrams to the 0x18 section, then RC200 can use the values too.

[tp1de]

@MichaelDvP @proddy

I do have some difficulties reading the new variables / telegrams. Is there any way to create console or system log messages for debugging ?

[MichaelDvP]

Sure, insert wherever you want a LOG_DEBUG(F("some text with value %d"),value); or to another loglevel like LOG_INFO(...);

[tp1de]

Seems to work now. Thanks so far.

[tp1de]

Just a question: For RC300/310 the typeids have 8 entries in thermostat.cpp.
But the RC300/RC310 supports only 4 heating circuits. So why 8 entries?

[MichaelDvP]

Long time we had only 4 entries, and than came this guy with more than four heatingcircuits. see #294, #297

[tp1de]

Ok understood. I made the PR for wwprio (RC310) with only 4 entries since the typeids numbers are not in a row.

[MichaelDvP]

With only 4 entries you have to take care not access or to loop through higher indices. Some loops use monitor_typeids as loopcount. I'll comment in the PR.

[tp1de]

@MichaelDvP Thanks so far for your support, quality checks and patience 👍

I started to work on the holiday modes now.

How can I find out within the thermostat code how many heating circuits are installed within the system?
As far as I understand the code there is only one dhw-system supported - Is this right? (RC310 supports 2)

[proddy]

it's been a while since I looked at that code. I don't think there is a function to return the number of heating circuits. You could write a small function that goes through the registered ones and only counts the active ones, something like

uint8_t Thermostat::count_heating_circuits() const {
  uint8_t count = 0;
  for (const auto & heating_circuit : heating_circuits_) {
     if (heating_circuit->is_active()) {
       count++;
     }
  }
  return count;
}

[tp1de]

As far as I understand the code for set_switchtime() within ems-esp, the code can handle Json Data for Change Value .
Is this right? If yes how could I initiate a JSON Change Value Window?

[proddy]

set_switchtime() is a command function and bound to an entity so its set up correctly the web code should automatically take care of the Change Value window. e.g. for the RC35:

register_device_value(tag, &hc->switchtime1, DeviceValueType::STRING, FL_(tpl_switchtime), FL_(switchtime1), DeviceValueUOM::NONE, MAKE_CF_CB(set_switchtime1));

[tp1de]

@proddy yes that's what I have seen.

I just ask myself if the Change Value window supports a Json-Structure -> multiple field-values to be entered in one window?
If yes, how could I manage to use it?

One holidaymode on the RC310 consists of multiple parameters. Could I enter them in one Change Value window?

[proddy]

it only supports a single value, but maybe we can introduce a multiline if needed. Do you have a use-case or example of what an input json would look like? My thermostat doesn't have switching times so I've never seen this in action

[tp1de]

it only supports a single value, but maybe we can introduce a multiline if needed

Thanks for making it clear - I was not sure.

Do you have a use-case or example of what an input json would look like?

I am still trying to find the best way of implementing the 5 holiday modes of the RC310.
Each holiday mode consist of the following parameters: (hcmode & dhwmode are enums). Example:

{"startStop":"01.01.2004-01.01.2005", "hcmode":1,"fixTemp":16,"hmmode":0,"assignedTo":[hc1,hc2,dhw1]}

So minimum 5 entities per holidaymode - maximum 25 entities in total which is too much.
I do have a version on test where I only have one set of parameters for hm1 - hm2 to hm5 are either read only or hm1 parameters are copied to the all hm's. I thought if Json input would be available I could control all parameters within one entity with Json-Content.

It would be the logic same for the RC310 switchtimes. Multiple times and parameters per day, per hc, ww and circulation pump.
So even more content then for holiday modes.

I do not know if it is worthwhile implementing this additional functionality. Maybe I should implement just hm1?
What do you think?

[proddy]

I think we should implement a special Web UI 'value change' dialog to handle this. Anything we can replicate from a physical thermostat and make it easier for a human is a good addition and a huge differentiator for ems-esp. EMS-ESP was always about making lives easier, for free.

[tp1de]

I think we should implement a special Web UI 'value change' dialog to handle this.

The Key question would be up to what extend do you want to invest efforts? Here is the dialog from the MyBuderus App in respect to the holiday modes:

[tp1de]

Is there anything I could do by myself to create a new Change Value Dialog?

[MichaelDvP]

The json in set_switchtime is a old test. Proddy has merged this with my changes like mqtt single-value and fahrenheit.
I allowed setting the switchtime as single string <nn> [ not_set | day hh:mm on|off ] or as json {"no"=<no>,"day"=<day>,"time"=<time>,"mode"=<on>}, But with refactoring the command-api it's not working anymore, mqtt need a single string that is set to the value field of a new json. Since this was the only command i've checked for json it does not matter.

[tp1de]

Understood Michael. This leads to the question how to implement EMS+ switch times and holiday modes?

• There are 5 holiday modes for EMS+ thermostats. Each hm has 5 entities. If the holiday modes will be plain values this will result in max. 25 entities. Or alternatively max 5 json values. Let me recommend to have plain values for hm1 (to be managed by dashboard and have enum texts available within the dialog box) and use json for hm2-hm5 (for web-API interface - e.g. to ioBroker)

• There are 2 switch programs per hc (A & B) and on for ww and one for the circulation pump. So for me with 2 hc's (radiators / floor heating) in total 6 switch programs - maximum will be 12 switch programs since the RC310 supports 4 hc's and 2 ww circuits.

• Each switch program can consist of up to 6 switch points per day. Each switch point has 3 data fields: (example from km200)
  {"dayOfWeek": "Mo", "setpoint": "comfort2", "time": 330 }, {"dayOfWeek": "Mo", "setpoint": "eco", "time": 1320 },.........

• So with 7 days x 6 switch points this will result in max. 42 entries with 3 values if not within one json.
  This for up to 12 switch programs !!!

Conclusion and open questions:

• For supporting the web-API I would recommend a json to be sent/received (similar to the km200 json structure).
• The Change Value dialog box should be left aligned and should accept multiple lines ( "\n")
• For the EMS+ holiday modes Change Value dialog with 2 lines would be still convenient to change values
• But for EMS+ switch programs the (small) Change Value dialog box is not really usable.
• I can't imagine what will be the result for HA / MQTT? You are the experts there.

What would be your recommendations?

[MichaelDvP]

For the switch programs this was a long discussion (see #182) and a lot of tries until we had this solution for RC35. The set_switchtime is used for dhw, circulation and the 2 programs per hc. The same scheme and functions are used for Moduline 400 in #467, and i think it can be adapted for RC300 too. But there are more opinions about program presentation than users and i don't like to discuss this anymore.

If we want to add json commands forwarded to the set_function this is only a few lines to add if we mark the command: Normally only the {"value":<value>} (or "data") is send to the setting function and a missing value gives the info back. For the set_switchtime we can use a json like:
{"data":"json","no":0,"day":"mo","time":06:30","mode":"eco"} and add to command.cpp, L152:

    if (data.is<const char *>()) {
        // check for a json command marked with {"data":"json"}
        if (!strcmp(data.as<const char *>(), "json")) {
            char jsondata[128];
            serializeJson(input, jsondata, sizeof(jsondata));
            return_code = Command::call(device_type, command_p, jsondata, is_admin, id_n, output);
        } else {
            return_code = Command::call(device_type, command_p, data.as<const char *>(), is_admin, id_n, output);
        }

This works for api and mqtt.

[tp1de]

I am not sure if I understood completely:

Does this mean that on dashboard only the first switch point of the switch program is shown?
And does every switch point has to be updated by a single command? Or will it work with a complete json containing all switch points similar to the km200?

km200 example:

[{"dayOfWeek": "Mo","setpoint": "comfort2","time": 300},
{"dayOfWeek": "Mo","setpoint": "eco","time": 1320},
{"dayOfWeek": "Tu","setpoint": "comfort2","time": 300},
{"dayOfWeek": "Tu","setpoint": "eco","time": 1320},
{"dayOfWeek": "We","setpoint": "comfort2","time": 300},
{"dayOfWeek": "We","setpoint": "eco","time": 1320},
{"dayOfWeek": "Th","setpoint": "comfort2","time": 300},
{"dayOfWeek": "Th","setpoint": "eco","time": 1320},
{"dayOfWeek": "Fr","setpoint": "comfort2","time": 300},
{"dayOfWeek": "Fr","setpoint": "eco","time": 1320},
{"dayOfWeek": "Sa","setpoint": "comfort2","time": 300},
{"dayOfWeek": "Sa","setpoint": "eco","time": 1320},
{"dayOfWeek": "Su","setpoint": "comfort2", "time": 300},
{"dayOfWeek": "Su","setpoint": "eco","time": 1320}]

[MichaelDvP]

Does this mean that on dashboard only the first switch point of the switch program is shown?

No, only one switchpoint at a time, but each can be displayed, see #461.

[tp1de]

No, only one switchpoint at a time, but each can be displayed, see #461.

That's what I had understood as well. Would it work to send the whole json with the whole switch program by api?