/*
 * sppro.h - Portable C parser for Selectronic SP PRO serial data.
 *
 * Pure, no-I/O, no-malloc decoder for the SP PRO "Q/W" memory protocol, plus
 * an optional transport-based session layer (login + query/write) that runs on
 * a host (Linux termios) or an MCU (ESP32) by supplying a read/write callback.
 *
 * Ported from the open-source Python implementation neerolyte/selpi:
 *   memory/crc.py, memory/request.py, memory/response.py,
 *   memory/variable.py, memory/converter.py, memory/protocol.py
 *
 * Protocol (all multi-byte values little-endian):
 *   Query  : 'Q' | (words-1) | addr[4] | crc16[2]            (8 bytes)
 *   QueryR : <echo of 8-byte query> | data[words*2] | crc16[2]
 *   Write  : 'W' | (words-1) | addr[4] | crc16(hdr6)[2] | data[words*2] | crc16(all)[2]
 *   WriteR : <echo of the write request>
 * A received frame is valid when crc16 over the whole message == 0.
 *
 * C99, freestanding-friendly: depends only on <stdint.h>/<stddef.h>.
 */
#ifndef SPPRO_H
#define SPPRO_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Serial line settings for the SP PRO RS-232 port (8N1). */
#define SPPRO_BAUD 57600

/* Well-known addresses. */
#define SPPRO_ADDR_LOGIN_HASH   0x1f0000u  /* 8 words: challenge in, response out */
#define SPPRO_ADDR_LOGIN_STATUS 0x1f0010u  /* 1 word: == 1 when authenticated     */
#define SPPRO_ADDR_SCALES       41000u     /* 6 consecutive scale-factor words     */

/* Maximum bytes in a request/response we will build or accept. A frame carries
 * at most 256 words: 8 header + 256*2 data + 2 crc = 522 bytes. */
#define SPPRO_MAX_FRAME 522
#define SPPRO_MAX_WORDS 256

/* Return / error codes (functions return >=0 on success). */
typedef enum {
    SPPRO_OK            = 0,
    SPPRO_ERR_ARG       = -1,  /* bad argument (NULL, word count, odd length) */
    SPPRO_ERR_BUFFER    = -2,  /* caller buffer too small                     */
    SPPRO_ERR_LENGTH    = -3,  /* response not the expected length            */
    SPPRO_ERR_CRC       = -4,  /* CRC check failed                            */
    SPPRO_ERR_ECHO      = -5,  /* response header did not echo the request    */
    SPPRO_ERR_IO        = -6,  /* transport read/write error or timeout       */
    SPPRO_ERR_LOGIN     = -7,  /* login status was not 1                      */
    SPPRO_ERR_UNKNOWN   = -8,  /* unknown register name                       */
} sppro_status_t;

/* --------------------------------------------------------------------------
 * Layer 1: CRC and little-endian word access (pure).
 * ------------------------------------------------------------------------ */

/* Kermit / reflected CRC-CCITT, init 0x0000, as used by the SP PRO. */
uint16_t sppro_crc16(const uint8_t *msg, size_t len);

uint16_t sppro_u16(const uint8_t *p);
int16_t  sppro_s16(const uint8_t *p);
uint32_t sppro_u32(const uint8_t *p);
int32_t  sppro_s32(const uint8_t *p);

/* --------------------------------------------------------------------------
 * Layer 2: frame build / parse (pure, into caller buffers).
 * ------------------------------------------------------------------------ */

/* Build an 8-byte query for `words` (1..256) words starting at `address`.
 * Returns the byte count written (8) or a negative sppro_status_t. */
int sppro_build_query(uint8_t *out, size_t out_cap, uint32_t address, int words);

/* Build a write request: header(8) + data + crc(2). `data_len` must be even
 * and 2..512. Returns bytes written or a negative sppro_status_t. */
int sppro_build_write(uint8_t *out, size_t out_cap, uint32_t address,
                      const uint8_t *data, size_t data_len);

/* Expected total response length for a query of `words` words. */
size_t sppro_query_response_len(int words);

/* Validate a query response and locate its data payload.
 * Checks length, CRC==0 over the whole frame, and that the echoed header
 * matches (type 'Q', address, word count). On success sets *data_out to point
 * inside `resp` and *data_len_out to words*2. Returns SPPRO_OK or negative. */
int sppro_parse_query_response(const uint8_t *resp, size_t resp_len,
                               uint32_t address, int words,
                               const uint8_t **data_out, size_t *data_len_out);

/* --------------------------------------------------------------------------
 * Layer 3: register map and unit conversion (pure).
 * ------------------------------------------------------------------------ */

typedef enum {
    SPPRO_T_U16,  /* unsigned 16-bit, 1 word  */
    SPPRO_T_S16,  /* signed 16-bit,   1 word  */
    SPPRO_T_U32,  /* unsigned 32-bit, 2 words */
    SPPRO_T_S32   /* signed 32-bit,   2 words */
} sppro_type_t;

typedef enum {
    SPPRO_C_RAW,          /* no scaling                                 */
    SPPRO_C_AC_W,         /* AC power (always positive)                 */
    SPPRO_C_AC_W_SIGNED,  /* AC power, signed                           */
    SPPRO_C_AC_WH,        /* AC energy                                  */
    SPPRO_C_DC_W,         /* DC power                                   */
    SPPRO_C_DC_WH,        /* DC energy                                  */
    SPPRO_C_DC_V,         /* DC volts                                   */
    SPPRO_C_TEMPERATURE,  /* degrees C                                  */
    SPPRO_C_PERCENT,      /* state of charge etc.                       */
    SPPRO_C_SHUNT_NAME    /* enum; use sppro_shunt_name() for the label */
} sppro_conv_t;

typedef struct {
    const char  *name;        /* selpi variable name                  */
    uint32_t     address;
    sppro_type_t type;
    sppro_conv_t conv;
    const char  *units;       /* "V", "W", "Wh", "C", "%", ""         */
    const char  *description;
} sppro_reg_t;

/* The register table (a curated, useful subset of selpi's MAP). */
extern const sppro_reg_t SPPRO_REGISTERS[];
extern const size_t       SPPRO_REGISTER_COUNT;

const sppro_reg_t *sppro_reg_by_name(const char *name);

int sppro_type_words(sppro_type_t type);  /* 1 or 2 */

/* Raw, unscaled scale-factor words read from SPPRO_ADDR_SCALES (41000..41005). */
typedef struct {
    uint16_t ac_volts;
    uint16_t ac_current;
    uint16_t dc_volts;
    uint16_t dc_current;
    uint16_t temperature;
    uint16_t internal_voltages;
} sppro_scales_t;

/* Parse the 12-byte payload of a 6-word query at SPPRO_ADDR_SCALES. */
int sppro_parse_scales(const uint8_t *data, size_t data_len, sppro_scales_t *out);

/* Apply a conversion to an unscaled raw value. SPPRO_C_RAW / SPPRO_C_SHUNT_NAME
 * return the value unchanged. */
double sppro_convert(sppro_conv_t conv, double raw, const sppro_scales_t *scales);

/* Read a register's raw bytes (type-aware sign) and return the scaled value. */
double sppro_decode(const sppro_reg_t *reg, const uint8_t *data,
                    const sppro_scales_t *scales);

const char *sppro_shunt_name(int raw);

/* --------------------------------------------------------------------------
 * Login helper (pure). The full handshake needs I/O; see the session layer.
 * ------------------------------------------------------------------------ */

/* Compute the 16-byte login response from the 16-byte challenge `seed` and the
 * serial-port `password` (padded/truncated to 32 bytes with spaces):
 *   md5(seed[16] + password_padded[32]) then swap each adjacent byte pair. */
void sppro_login_response(const uint8_t seed[16], const char *password,
                          uint8_t out[16]);

/* --------------------------------------------------------------------------
 * Layer 4: transport-based session (portable I/O via caller callbacks).
 * ------------------------------------------------------------------------ */

/* read  : place up to `len` bytes into buf, return count read (>=0, 0==none) or <0 on error.
 * write : send `len` bytes, return count written or <0 on error. */
typedef struct {
    int (*read)(void *ctx, uint8_t *buf, size_t len);
    int (*write)(void *ctx, const uint8_t *buf, size_t len);
    void *ctx;
} sppro_transport_t;

/* Send a query and read+validate the response. Copies words*2 data bytes into
 * `data_out` (capacity `data_cap`). Returns data length (bytes) or negative. */
int sppro_session_query(const sppro_transport_t *t, uint32_t address, int words,
                        uint8_t *data_out, size_t data_cap);

/* Send a write and verify the device echoes the request. Returns SPPRO_OK or negative. */
int sppro_session_write(const sppro_transport_t *t, uint32_t address,
                        const uint8_t *data, size_t data_len);

/* Perform the MD5 challenge/response login. Returns SPPRO_OK or negative. */
int sppro_session_login(const sppro_transport_t *t, const char *password);

/* Read the six scale-factor registers in one query. Returns SPPRO_OK or negative. */
int sppro_session_read_scales(const sppro_transport_t *t, sppro_scales_t *out);

/* Read one register by definition and return its scaled value via *value_out. */
int sppro_session_read(const sppro_transport_t *t, const sppro_reg_t *reg,
                       const sppro_scales_t *scales, double *value_out);

#ifdef __cplusplus
}
#endif

#endif /* SPPRO_H */