Start project
This commit is contained in:
+202
@@ -0,0 +1,202 @@
|
||||
/*
|
||||
* 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 */
|
||||
Reference in New Issue
Block a user