Conv schedule

- add conversion of schedules
- cleanup readme a bit

Author: bertmelis

README.md

@@ -1,6 +1,6 @@
 # VitoWiFi
 
-Library for ESP8266 to communicate with Viessmann systems using a (DIY) serial optolink.
+Library for ESP32, ESP8266 and Linux to communicate with Viessmann systems using a (DIY) serial optolink.
 
 Based on the fantastic work on [openv](https://github.com/openv/openv/wiki).
 
@@ -10,7 +10,7 @@ Based on the fantastic work on [openv](https://github.com/openv/openv/wiki).
 
 ## Features
 
-- VS1 (KW) and VS2 (P300) support. Older systems using the GWG protocol are not supported
+- VS1 (KW) and VS2 (P300) support. The older GWG protocol is also supported.
 - Non-blocking API calls
 - For the Arduino framework and POSIX systems (Linux, tested on a Raspberry Pi 1B)
 - Possible to use `SoftwareSerial` on ESP8266
@@ -32,7 +32,7 @@ Based on the fantastic work on [openv](https://github.com/openv/openv/wiki).
 
 ## Hardware
 
-The optolink hardware for ESP8266 and ESP32 is simple. Using the circuit below you can build your own optolink.
+The optolink hardware can be really simple. Using the circuit below you can build your own optolink.
 Please also check the [openv wiki, in German](https://github.com/openv/openv/wiki/Die-Optolink-Schnittstelle) for more implementations.
 
 ```
@@ -75,7 +75,7 @@ The canonical way to use this library is simple and straightforward. A few steps
     - attach the callbacks
     - start VitoWiFi
 5. in `void loop()`:
-    - call `loop()` regularly. It keeps VitoWiFi running.
+    - call `loop()` regularly. It keeps VitoWiFi running. Ideally it is called more than once every 10ms.
 
 A simple program for ESP32 to test and query your devicetype looks like this:
 
@@ -160,11 +160,11 @@ if (currentIndex > 0) {
 
 ### More examples
 
-you can find more examples in the `examples` directory in this repo.
+You can find more examples in the `examples` directory in this repo.
 
 ## Datapoints
 
-When defining your datapoints, you need to specify the name, address, length and converion type. Datapoints in C++ looks like this:
+When defining your datapoints, you need to specify the name, address, length and conversion type. Datapoints in C++ looks like this:
 
 ```cpp
 VitoWiFi::Datapoint datapoint1("outside temp", 0x5525, 2, VitoWiFi::div10);
@@ -178,24 +178,26 @@ While name, address and length are self-explanatory, conversion type is a bit mo
 
 ### Conversion types
 
-Data is stored in binary and often needs a conversion function to transform into a more readable type. This is specified by the conversion type, the last argument in the datapoint definition.
+Data is stored in binary and often needs a conversion function to transform into a more usable type. This is specified by the conversion type, the last argument in the datapoint definition.
 
-Since C++ is a strongly typed programming language so using the right type is important (read: mandatory). Each conversion type corresponds with a certain type. Reading or writing has to be done using this specific type and failure to do so will not work or will lead to undefined results.
+C++ is a strongly typed programming language so using the right type is important (read: mandatory). Each conversion type corresponds to a certain type. Reading or writing has to be done using this specific type and failure to do so will not work or will lead to undefined results.
 
 In the table below you can find how to define your datapoints:
 
 |name|size|converter|return type|remarks|
 |---|---|---|---|---|
 |Temperature|2|div10|float||
-|Temperature short|1|noconv|uint8_t|equivalent to Mode|
-|Power|1|div2|float|also used for temperature in GWG|
-|Status|1|noconv|bool|this is the same as 'Temperature short' and 'Mode'. The  `uint8_t` value will be implicitely converted to bool.|
-|Hours|4|div3600|float|this is in fact a `Count` datapoint (seconds) converted to hours.|
+|Temperature short|1|noconv|uint8_t|Equivalent to Mode|
+|Power|1|div2|float|Also used for temperature in GWG|
+|Status|1|noconv|bool|This is the same as 'Temperature short' and 'Mode'. The  `uint8_t` value will be implicitely converted to bool.|
+|Hours|4|div3600|float|This is in fact a `Count` datapoint (seconds) converted to hours.|
 |Count|4|noconv|uint32_t||
 |Count short|2|noconv|uint16_t||
-|Mode|1|noconv|uint8_t|possibly castable to ENUM|
+|Mode|1|noconv|uint8_t|Possibly castable to ENUM|
 |CoP|1|div10|float|Also used for heating curve slope|
 
+Mind that the converters are declared within the `VitoWiFi` namespace.
+
 ## Bugs and feature requests
 
 Please use Github's facilities to get in touch. While the issue template is not mandatory to use, please use it at least as a starting point to supply the needed info for bughunting.
@@ -204,9 +206,9 @@ Please use Github's facilities to get in touch. While the issue template is not
 
 Below is an overview of all commonly used methods. For extra functions you can consult the source code.
 
-### Datapoint
+### `VitoWiFi::Datapoint`
 
-##### `Datapoint(const char* name, uint16_t address, uint8_t length, const Converter& converter)`
+##### `VitoWiFi::Datapoint(const char* name, uint16_t address, uint8_t length, const Converter& converter)`
 
 Constructor for datapoints.
 
@@ -227,16 +229,16 @@ Returns `VariantValue` which is implicitely castable to the correct datatype. Co
 
 ##### `VariantValue decode(const uint8_t* data, uint8_t length) const`
 
-Decodes the data in the supplied `data`-buffer using the converter class attached.
+Decodes the data in the supplied `data`-buffer using the Converter class attached.
 Returns `VariantValue` which is implicitely castable to the correct datatype. Consult the table above.
 
 ##### `void encode(uint8_t* buf, uint8_t len, const VariantValue& value) const`
 
-Encodes `value` into the supplied `buf` with maximum size `len`. The size should obviously be at least the length of the datapoint.
+Encodes `value` into the supplied `buf` with maximum size `len`. The size must be at least the length of the datapoint.
 
 `VariantValue` is a type to implicitely convert datatypes for use in VitoWiFi. Make sure to use the type that matches your Converter type.
 
-### `PacketVS2`
+### `VitoWiFi::PacketVS2`
 
 Only used in VS2. This type is used in the onResponse callback and contains the returned data.
 Most users will only use the following two methods and only if they want to access the raw data. Otherwise, the data can be decoded using the corresponding `Datapoint`.
@@ -249,25 +251,27 @@ Returns the number of bytes in the payload.
 
 Returns a pointer to the payload.
 
-### VitoWiFi
+### `VitoWiFi::VitoWiFi`
 
-##### `VitoWiFi<PROTOCOL_VERSION>(IFACE* interface)`
+##### `VitoWiFi::VitoWiFi<PROTOCOL_VERSION>(IFACE* interface)`
 
-Constructor of the VitoWiFi class. `PROTOCOL_VERSION` can be  `GWG`, `VS1` or `VS2`. If your Viessmann device is somewhat modern, you should use `VS2`.
+Constructor of the VitoWiFi class. `PROTOCOL_VERSION` can be  `VitoWiFi::GWG`, `VitoWiFi::VS1` or `VitoWiFi::VS2`. If your Viessmann device is somewhat modern, you should use `VitoWiFi::VS2`.
 `interface` can be any of the `HardwareSerial` interfaces (`Serial`, `Serial1`...) on Arduino boards, `SoftwareSerial` (on ESP8266) or if you are on Linux, pass the c-string depicting your device (for example `"/dev/ttyUSB0"`).
 
 ##### `void onResponse(typename PROTOCOLVERSION::OnResponseCallback callback)`
 
-Attach an onResponse callback. You can only attack one and will overwrite the previously attached callback.
+Attach an onResponse callback. You can only attach one and will overwrite the previously attached callback.
 The callback has the following signature:
-`VS1`: `void (const uint8_t*, uint8_t, const VitoWiFi::Datapoint&)`
-`VS2`: `void (const VitoWiFi::PacketVS2&, const VitoWiFi::Datapoint&)`
+
+- `VitoWiFi::VS1`: `void (const uint8_t*, uint8_t, const VitoWiFi::Datapoint&)`
+- `VitoWiFi::VS2`: `void (const VitoWiFi::PacketVS2&, const VitoWiFi::Datapoint&)`
 
 ##### `void onError(typename PROTOCOLVERSION::OnErrorCallback callback)`
 
 Attach an onError callback. You can only attack one and will overwrite the previously attached callback.
 The callback has the following signature:
-`void (VitoWiFi::OptolinkResult, const VitoWiFi::Datapoint&)`
+
+- `void (VitoWiFi::OptolinkResult, const VitoWiFi::Datapoint&)`
 
 ##### `bool begin()`
 
@@ -287,7 +291,7 @@ Read `datapoint`. Returns `true` on success.
 
 ##### `bool write(Datapoint datapoint, T value)`
 
-Write `value` with type `T` to `datapoint`. Make sure to use the correct type. consult the table with types in the "Datapoints" section.
+Write `value` with type `T` to `datapoint`. Make sure to use the correct type. Consult the table with types in the "Datapoints" section.
 
 ##### `write(Datapoint datapoint, const uint8_t* data, uint8_t length)`
 
@@ -308,11 +312,11 @@ Used in the onError callback. Possible returned values are:
 
 ##### `VW_START_PAYLOAD_LENGTH`
 
-This macro sets the initial payload (data) length VitoWiFi allocates for incoming packets. If you know beforehand the maximum data length you are going to request, you can set this to that value to prevent reallocation of dynamic memory. The default is 10 bytes.
+This macro sets the initial payload (data) length for incoming packets. VitoWiFi will increased the buffer if needed. If you know the maximum data length you are going to request beforehand, use this set to prevent dynamic memory reallocation. The default is 10 bytes.
 
 ## Bugs and feature requests
 
-Please use Github's facilities, issues and discussions, to get in touch.
+Please use Githubs facilities, issues and discussions, to get in touch.
 When creating a bug report, please use the provided template. In any case, better to include too much info than too little.
 
 ## License

src/Datapoint/ConversionHelpers.cpp

@@ -0,0 +1,107 @@
+/*
+Copyright (c) 2023 Bert Melis. All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT> or
+the LICENSE file.
+*/
+
+#include "ConversionHelpers.h"
+
+bool isDigit(const char c) {
+  return c >= '0' && c <= '9';
+}
+
+namespace VitoWiFi {
+
+std::size_t encodeSchedule(const char* schedule, std::size_t len, uint8_t* output) {
+  enum ScheduleParserStep {
+    Hours1,
+    Hours2,
+    Minutes1,
+    Minutes2,
+    Space,
+  };
+
+  std::memset(output, 0x00, 8);
+
+  std::size_t i = 0 - 1;  // first operation in iteration is ++i
+  std::size_t scheduleIndex = 0;
+  ScheduleParserStep step = ScheduleParserStep::Hours1;
+  unsigned int hour = 0;
+  unsigned int minutes = 0;
+
+  while (++i < len) {
+    if (step == ScheduleParserStep::Hours1) {
+      if (isDigit(schedule[i])) {
+        hour = schedule[i] - '0';
+        step = ScheduleParserStep::Hours2;
+        continue;
+      }
+    } else if (step == ScheduleParserStep::Hours2) {
+      if (isDigit(schedule[i])) {
+        hour = hour * 10 + (schedule[i] - '0');
+        continue;
+      } else if (schedule[i] == ':') {
+        step = ScheduleParserStep::Minutes1;
+        continue;
+      }
+    } else if (step == ScheduleParserStep::Minutes1) {
+      if (isDigit(schedule[i])) {
+        minutes = schedule[i] - '0';
+        step = ScheduleParserStep::Minutes2;
+        continue;
+      }
+    } else if (step == ScheduleParserStep::Minutes2) {
+      if (schedule[i] == '0') {
+        minutes = minutes * 10 + (schedule[i] - '0');
+        // parsing is possibly complete
+        if (hour <= 23 || minutes <= 59) {
+          output[scheduleIndex] = (0xF8 & hour << 3) | minutes / 10;
+          ++scheduleIndex;
+          step = ScheduleParserStep::Space;
+          continue;
+        }
+      }
+    } else {  // step == ScheduleParserStep::Space
+      if (schedule[i] == ' ') {
+        step = ScheduleParserStep::Hours1;
+        continue;
+      }
+    }
+    return 0;
+  }
+  if (scheduleIndex % 2 == 0 && step == ScheduleParserStep::Space) {
+    // TODO(bertmelis): hours have to be ordered
+    return (scheduleIndex + 1) / 2;
+  }
+  return 0;
+}
+
+std::size_t encodeSchedule(const char* schedule, uint8_t* output) {
+  return encodeSchedule(schedule, strlen(schedule), output);
+}
+
+std::size_t decodeSchedule(const uint8_t* data, std::size_t len, char* output, std::size_t maxLen) {
+  assert(len == 8);
+  assert(maxLen >= 48);  // 8 times 07:30, 7 spaces and 0-terminator --> 8 * 5 + 7 * 1 + 1
+
+  std::size_t pos = 0;
+  for (std::size_t i = 0; i < 8; ++i) {
+    unsigned int hour = data[i] >> 3;
+    unsigned int minutes = (data[i] & 0x07) * 10;
+    if (hour > 23 || minutes > 59) {
+      hour = 0;
+      minutes = 0;
+    }
+    int result = snprintf(&output[pos], maxLen - pos, "%.2u:%.2u", hour, minutes);
+    if (result < 0) return 0;
+    pos += result;
+    if (i < 7) {
+      output[pos++] = ' ';
+    }
+  }
+  return pos + 1;  // include 0-terminator
+}
+
+}  // end namespace VitoWiFi

src/Datapoint/ConversionHelpers.h

@@ -0,0 +1,56 @@
+/*
+Copyright (c) 2025 Bert Melis. All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT> or
+the LICENSE file.
+*/
+
+#pragma once
+
+#include <cassert>
+#include <cstdint>
+#include <cstddef>
+#include <cstring>  // strlen
+#include <cstdio>  // snprintf
+
+namespace VitoWiFi {
+
+/*
+Encodes a c-string containing a schedule to an 8-byte schedule sequence.
+Returns the number of pairs encoded
+Per byte: 
+  - b7-b3 hour
+  - b2-b1 minute * 10
+
+Output needs to be at least 8 bytes
+
+A scedule consists of time pairs with minutes rounded to a multiple of 10min.
+Hours can be with leading zero or not.
+
+Valid:
+  - 7:30 8:30 15:00 23:50
+  - 07:30 8:30 15:00 23:50
+
+Invalid:
+  - time not specified in pairs
+  - (hours not ordered earliest to latest)
+  - other formatting than colons or spaces
+  - minutes not rounded to multiples of 10
+  - whitespace not trimmed
+*/
+std::size_t encodeSchedule(const char* schedule, std::size_t len, uint8_t* output);
+std::size_t encodeSchedule(const char* schedule, uint8_t* output);
+
+/*
+Decodes a byte series to a human-readable schedule consisting of time pairs.
+Returns the number of characters written including 0-terminator
+(will always result in 48 or 0 in case of an error)
+
+Although passed as variables, the function fails when
+- len != 8
+- maxLen < 48
+*/
+std::size_t decodeSchedule(const uint8_t* data, std::size_t len, char* output, std::size_t maxLen);
+
+};  // end namespace VitoWiFi

src/Datapoint/Converter.h

@@ -9,10 +9,12 @@ the LICENSE file.
 #pragma once
 
 #include <cassert>
+#include <cstdint>
 #include <cmath>
 #include <cstring>
 
 #include "../Logging.h"
+#include "ConversionHelpers.h"
 
 namespace VitoWiFi {
 

src/GWG/GWG.cpp

@@ -199,6 +199,7 @@ void GWG::_setState(State state) {
 void GWG::_init() {
   if (_interface->available()) {
     if (_interface->read() == VitoWiFiInternals::ProtocolBytes.ENQ && _currentDatapoint) {
+      _bytesTransferred = 0;
       _setState(State::SEND);
     }
   }
@@ -220,7 +221,6 @@ void GWG::_receive() {
     _lastMillis = _currentMillis;
   }
   if (_bytesTransferred == _currentRequest.length()) {
-    _bytesTransferred = 0;
     _setState(State::INIT);
     _tryOnResponse();
   }