MycilaJSY.h

// SPDX-License-Identifier: MIT
/*
 * Copyright (C) 2023-2025 Mathieu Carbou
 */
#pragma once
 
#include <HardwareSerial.h>
 
#include <mutex>
 
#ifdef MYCILA_JSON_SUPPORT
  #include <ArduinoJson.h>
#endif
 
#define MYCILA_JSY_VERSION          "15.3.1"
#define MYCILA_JSY_VERSION_MAJOR    15
#define MYCILA_JSY_VERSION_MINOR    3
#define MYCILA_JSY_VERSION_REVISION 0
 
// #define MYCILA_JSY_DEBUG 1
 
// broadcast address to send requests to all devices
#define MYCILA_JSY_ADDRESS_BROADCAST 0x00
// default factory JSY address
#define MYCILA_JSY_ADDRESS_DEFAULT 0x01
// constant returned when device address is unknown
#define MYCILA_JSY_ADDRESS_UNKNOWN 0x00
 
// Model value for unknown JSY device
#define MYCILA_JSY_MK_UNKNOWN 0x0000
// Model value for JSY1031 family
#define MYCILA_JSY_MK_1031 0x1031
// Model value for JSY-MK-163 family
#define MYCILA_JSY_MK_163 0x0163
// Model value for JSY-MK-193 family
#define MYCILA_JSY_MK_193 0x0193
// Model value for JSY-MK-194 family
#define MYCILA_JSY_MK_194 0x0194
// Model value for JSY-MK-227 family
#define MYCILA_JSY_MK_227 0x0227
// Model value for JSY-MK-229 family
#define MYCILA_JSY_MK_229 0x0229
// Model value for JSY-MK-333 family
#define MYCILA_JSY_MK_333 0x0333
 
#define MYCILA_JSY_MK_1031_NAME "JSY1031"
#define MYCILA_JSY_MK_163_NAME  "JSY-MK-163"
#define MYCILA_JSY_MK_193_NAME  "JSY-MK-193"
#define MYCILA_JSY_MK_194_NAME  "JSY-MK-194"
#define MYCILA_JSY_MK_227_NAME  "JSY-MK-227"
#define MYCILA_JSY_MK_229_NAME  "JSY-MK-229"
#define MYCILA_JSY_MK_333_NAME  "JSY-MK-333"
 
#ifndef MYCILA_JSY_ASYNC_CORE
  #define MYCILA_JSY_ASYNC_CORE 1
#endif
 
#ifndef MYCILA_JSY_ASYNC_PRIORITY
  #define MYCILA_JSY_ASYNC_PRIORITY 5
#endif
 
#ifndef MYCILA_JSY_ASYNC_STACK_SIZE
  #define MYCILA_JSY_ASYNC_STACK_SIZE 4094
#endif
 
// time in milliseconds to wait between each read in async mode
#ifndef MYCILA_JSY_ASYNC_READ_PAUSE_MS
  #define MYCILA_JSY_ASYNC_READ_PAUSE_MS 0
#endif
 
// Maximumtime in milliseconds to wait for bytes to arrive when reading a JSY response
// This value is conservative and work with all JSY.
// If you happen to only use specific JSY models, you can reduce this value to speed up the read process.
// Only JSY1031 are slow and require such a big timeout.
// For other models, the timeout can be decreased safely to 500 ms.
#ifndef MYCILA_JSY_READ_TIMEOUT_MS
  #define MYCILA_JSY_READ_TIMEOUT_MS 1000
#endif
 
#ifndef MYCILA_JSY_RETRY_COUNT
  #define MYCILA_JSY_RETRY_COUNT 3
#endif
 
namespace Mycila {
  class JSY {
    public:
      enum BaudRate : uint32_t {
        UNKNOWN = 0,
        // Supported by: JSY-MK-163, JSY-MK-193, JSY-MK-194, JSY-MK-227, JSY-MK-229
        BAUD_1200 = 1200,
        // Supported by: JSY-MK-163, JSY-MK-193, JSY-MK-194, JSY-MK-227, JSY-MK-229
        BAUD_2400 = 2400,
        // Default for: JSY-MK-163, JSY-MK-194
        // Supported by: JSY1031, JSY-MK-163, JSY-MK-193, JSY-MK-194, JSY-MK-227, JSY-MK-229, JSY-MK-333
        BAUD_4800 = 4800,
        // Default for: JSY1031, JSY-MK-193, JSY-MK-227, JSY-MK-229, JSY-MK-333
        // Supported by: JSY1031, JSY-MK-163, JSY-MK-193, JSY-MK-194, JSY-MK-227, JSY-MK-229, JSY-MK-333
        BAUD_9600 = 9600,
        // Supported by: JSY1031, JSY-MK-193, JSY-MK-194, JSY-MK-333
        BAUD_19200 = 19200,
        // Supported by: JSY-MK-193, JSY-MK-194
        BAUD_38400 = 38400,
      };
 
      enum class EventType {
        // JSY has successfully read the data
        EVT_READ,
        // wrong data received when reading values
        EVT_READ_ERROR,
        // timeout reached when reading values
        EVT_READ_TIMEOUT,
        // wrong JSY device read
        EVT_READ_PEER
      };
 
      enum class Mode {
        UNKNOWN,
        AC,
        DC
      };
 
      class Metrics {
        public:
          float frequency = NAN; // Hz

          float voltage = NAN;

          float current = NAN;

          float activePower = NAN;

          float powerFactor = NAN;

          float apparentPower = NAN;

          float reactivePower = NAN;

          uint32_t activeEnergy = 0;

          uint32_t activeEnergyImported = 0;

          uint32_t activeEnergyReturned = 0;

          uint32_t reactiveEnergy = 0;

          uint32_t reactiveEnergyImported = 0;

          uint32_t reactiveEnergyReturned = 0;

          uint32_t apparentEnergy = 0;

          float phaseAngleU = NAN;

          float phaseAngleI = NAN;

          float phaseAngleUI = NAN;

          float thdU = NAN;

          float thdI = NAN;

          float thdi(float phi = 0) const;

          float resistance() const;

          float dimmedVoltage() const;

          float nominalPower() const;
 
          // clear all values
          void clear();
 
          // compare two metrics
          bool operator==(const Metrics& other) const;
          // compare two metrics
          bool operator!=(const Metrics& other) const { return !(*this == other); }
          // add two metrics, averaging the voltage
          Metrics& operator+=(const Metrics& other);
          // copy a metric
          void operator=(const Metrics& other);
 
#ifdef MYCILA_JSON_SUPPORT
          void toJson(const JsonObject& root) const;
#endif
      };
 
      class Data {
        public:
          uint8_t address = MYCILA_JSY_ADDRESS_UNKNOWN; // device address
          uint16_t model = MYCILA_JSY_MK_UNKNOWN;       // device model
 
          // For JSY1031: aggregate == single()
          // For JSY-MK-163: aggregate == single()
          // For JSY-MK-194: aggregate == channel1() + channel2()
          // For JSY-MK-333: aggregate == phaseA() + phaseB() + phaseC()
          Metrics aggregate;
 
          // JSY-MK-163 and JSY1031
          const Metrics& single() const { return _metrics[0]; }
 
          // JSY-MK-194 (channel 1)
          const Metrics& channel1() const { return _metrics[0]; }
          // JSY-MK-194 (channel 2)
          const Metrics& channel2() const { return _metrics[1]; }
 
          // JSY-MK-333 (phase A)
          const Metrics& phaseA() const { return _metrics[0]; }
          // JSY-MK-333 (phase B)
          const Metrics& phaseB() const { return _metrics[1]; }
          // JSY-MK-333 (phase C)
          const Metrics& phaseC() const { return _metrics[2]; }
 
          // clear all values
          void clear();
 
          // compare two data
          bool operator==(const Data& other) const;
          // compare two data
          bool operator!=(const Data& other) const { return !(*this == other); }
          // copy a data
          void operator=(const Data& other);
 
#ifdef MYCILA_JSON_SUPPORT
          void toJson(const JsonObject& root) const;
#endif
 
        private:
          friend class JSY;
          Metrics _metrics[3];
      };
 
      typedef std::function<void(EventType eventType, const Data& data)> Callback;
 
      ~JSY() { end(); }

      void begin(HardwareSerial& serial, // NOLINT
                 int8_t rxPin,
                 int8_t txPin,
                 bool async,
                 uint8_t core = MYCILA_JSY_ASYNC_CORE,
                 uint32_t stackSize = MYCILA_JSY_ASYNC_STACK_SIZE,
                 uint32_t pause = MYCILA_JSY_ASYNC_READ_PAUSE_MS) {
        begin(serial, rxPin, txPin, BaudRate::UNKNOWN, MYCILA_JSY_ADDRESS_BROADCAST, MYCILA_JSY_MK_UNKNOWN, async, core, stackSize, pause);
      }

      void begin(HardwareSerial& serial, // NOLINT
                 int8_t rxPin,
                 int8_t txPin,
                 BaudRate baudRate = BaudRate::UNKNOWN,
                 uint8_t destinationAddress = MYCILA_JSY_ADDRESS_BROADCAST,
                 uint16_t model = MYCILA_JSY_MK_UNKNOWN,
                 bool async = false,
                 uint8_t core = MYCILA_JSY_ASYNC_CORE,
                 uint32_t stackSize = MYCILA_JSY_ASYNC_STACK_SIZE,
                 uint32_t pause = MYCILA_JSY_ASYNC_READ_PAUSE_MS);

      void end();

      bool setDeviceAddress(uint8_t newAddress) { return setDeviceAddress(_destinationAddress, newAddress); }

      bool setDeviceAddress(uint8_t address, uint8_t newAddress);

      uint16_t readModel() { return readModel(_destinationAddress); }

      uint16_t readModel(uint8_t address);

      uint16_t getModel() const { return _model; }
 
      const char* getModelName() const { return getModelName(_model); }

      static const char* getModelName(uint16_t model);

      Mode readMode() { return _readMode(_destinationAddress, _model); }

      Mode readMode(uint8_t address) { return _readMode(address, readModel(address)); }

      bool setMode(Mode mode) { return _setMode(_destinationAddress, _model, mode); }

      bool setMode(uint8_t address, Mode mode) { return _setMode(address, readModel(address), mode); }

      bool read() { return _read(_destinationAddress, _model); }

      bool read(uint8_t address) { return _read(address, readModel(address)); }

      bool resetEnergy() { return resetEnergy(_destinationAddress); }

      bool resetEnergy(uint8_t address);
 
      // Try to change the baud rate of the JSY. Returns true if the baud rate was changed.
      // This function is blocking until the change is confirmed or the timeout is reached.

      bool setBaudRate(BaudRate baudRate) { return setBaudRate(_destinationAddress, baudRate); }

      bool setBaudRate(uint8_t address, BaudRate baudRate);
 
#ifdef MYCILA_JSON_SUPPORT
      void toJson(const JsonObject& root) const;
#endif
 
      gpio_num_t getRXPin() const { return _pinRX; }
      gpio_num_t getTXPin() const { return _pinTX; }
      bool isEnabled() const { return _enabled; }
      BaudRate getBaudRate() const { return _baudRate; }

      uint8_t getDestinationAddress() const { return _destinationAddress; }
 
      BaudRate getMinAvailableBaudRate() const;
      static BaudRate getMinAvailableBaudRate(uint16_t model);

      BaudRate getMaxAvailableBaudRate() const;
      static BaudRate getMaxAvailableBaudRate(uint16_t model);

      bool isBaudRateSupported(BaudRate baudRate) const;
      static bool isBaudRateSupported(uint16_t model, BaudRate baudRate);

      uint8_t getLastAddress() const { return _lastAddress; }

      uint32_t getTime() const { return _time; }
 
      // check if the device is connected to the grid, meaning if last read was successful
      bool isConnected() const { return _data.aggregate.frequency > 0; }
 
      void setCallback(Callback callback) { _callback = callback; }
 
    private:
      Callback _callback = nullptr;
      gpio_num_t _pinRX = GPIO_NUM_NC;
      gpio_num_t _pinTX = GPIO_NUM_NC;
      HardwareSerial* _serial = nullptr;
      std::mutex _mutex;
      TaskHandle_t _taskHandle;
      uint32_t _time = 0;
      uint32_t _pause = MYCILA_JSY_ASYNC_READ_PAUSE_MS;
      uint8_t _destinationAddress = MYCILA_JSY_ADDRESS_BROADCAST;
      uint8_t _lastAddress = MYCILA_JSY_ADDRESS_UNKNOWN;
      BaudRate _baudRate = BaudRate::UNKNOWN;
      bool _enabled = false;
      uint16_t _model = MYCILA_JSY_MK_UNKNOWN;
      // buffer to read/write data
      // biggest need is for JSY-MK-333: 102 registers of 2 bytes each + 5 bytes for the response: 209 bytes
      // we use 14 blocks of 16 bytes: 224 bytes
      uint8_t _buffer[224];
      Data _data;
 
    private:
      enum class ReadResult {
        READ_SUCCESS = 0,
        READ_TIMEOUT,
        READ_ERROR_COUNT,
        READ_ERROR_CRC,
        READ_ERROR_ADDRESS,
      };
 
      bool _set(uint8_t address, uint8_t newAddress, BaudRate newBaudRate);
      bool _read(uint8_t address, uint16_t model);
      Mode _readMode(uint8_t address, uint16_t model);
      bool _setMode(uint8_t address, uint16_t model, Mode mode);
 
      bool _canRead(uint8_t address, BaudRate baudRate);
      ReadResult _timedRead(uint8_t expectedAddress, size_t expectedLen, BaudRate baudRate);
      void _send(uint8_t address, size_t len);
      size_t _drop();
      void _openSerial(BaudRate baudRate);
      BaudRate _detectBauds(uint8_t address);
 
      static uint16_t _crc16(const uint8_t* buffer, size_t len);
      static uint8_t _register8(const uint8_t* buffer, uint16_t registerStart, uint16_t registerSize, uint16_t registerAddress, uint8_t index = 0);
      static uint16_t _register16(const uint8_t* buffer, uint16_t registerStart, uint16_t registerSize, uint16_t registerAddress);
      static uint32_t _register32(const uint8_t* buffer, uint16_t registerStart, uint16_t registerSize, uint16_t registerAddress);
      static void _jsyTask(void* pvParameters);
  };
} // namespace Mycila