commit 996dc608ccc5daac4f0065c7f23ec94898afd682 Author: Scott Penrose Date: Tue Jun 16 04:33:39 2026 +1000 Start project diff --git a/README.md b/README.md new file mode 100644 index 0000000..fd2f42e --- /dev/null +++ b/README.md @@ -0,0 +1,20 @@ +# SPPro Access + +Build a system that can connect to an SPPro Serial Port to get sensible data out of it to display it on a serial console and be used in other projects. + +PyAware seems to already decode Serial Data. Look at porting that to portable C for decoding. + +* Hardware necessary to connect to SPPro + * https://www.selectronic.com.au/documents/TechNotes/TN0050_02%20SP%20PRO%20Serial%20Port%20Pin-out.pdf + * How to connect this to an ESP32 +* Parse Serial Data + * A simple C parser, portable to allow parsing + + +## See Also + +* pyAWARE - not open source +* selpi - a Python set for seletronics + * https://github.com/neerolyte/selpi +* splink-influx + * https://github.com/angus-g/splink-influx diff --git a/src/md5.c b/src/md5.c new file mode 100644 index 0000000..c0a0659 --- /dev/null +++ b/src/md5.c @@ -0,0 +1,259 @@ +/* + * This is an OpenSSL-compatible implementation of the RSA Data Security, Inc. + * MD5 Message-Digest Algorithm (RFC 1321). + * + * Homepage: + * http://openwall.info/wiki/people/solar/software/public-domain-source-code/md5 + * + * Author: + * Alexander Peslyak, better known as Solar Designer + * + * This software was written by Alexander Peslyak in 2001. No copyright is + * claimed, and the software is hereby placed in the public domain. + * In case this attempt to disclaim copyright and place the software in the + * public domain is deemed null and void, then the software is + * Copyright (c) 2001 Alexander Peslyak and it is hereby released to the + * general public under the following terms: + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted. + * + * There's ABSOLUTELY NO WARRANTY, express or implied. + * + * (This is a heavily cut-down "BSD license" with the obnoxious clauses + * removed, as is permitted by law.) + * + * This is a portable implementation, optimized for clarity and correctness + * rather than speed. + */ + +#include "md5.h" +#include + +/* The basic MD5 functions. */ +#define F(x, y, z) ((z) ^ ((x) & ((y) ^ (z)))) +#define G(x, y, z) ((y) ^ ((z) & ((x) ^ (y)))) +#define H(x, y, z) (((x) ^ (y)) ^ (z)) +#define H2(x, y, z) ((x) ^ ((y) ^ (z))) +#define I(x, y, z) ((y) ^ ((x) | ~(z))) + +/* The MD5 transformation for all four rounds. */ +#define STEP(f, a, b, c, d, x, t, s) \ + (a) += f((b), (c), (d)) + (x) + (t); \ + (a) = (((a) << (s)) | (((a) & 0xffffffff) >> (32 - (s)))); \ + (a) += (b); + +/* + * SET reads 4 input bytes in little-endian byte order and stores them in a + * properly aligned word in host byte order. + */ +#define SET(n) \ + (ctx->block[(n)] = \ + (uint32_t)ptr[(n) * 4] | \ + ((uint32_t)ptr[(n) * 4 + 1] << 8) | \ + ((uint32_t)ptr[(n) * 4 + 2] << 16) | \ + ((uint32_t)ptr[(n) * 4 + 3] << 24)) +#define GET(n) (ctx->block[(n)]) + +/* + * This processes one or more 64-byte data blocks, but does NOT update the bit + * counters. There are no alignment requirements. + */ +static const void *body(MD5_CTX *ctx, const void *data, unsigned long size) +{ + const unsigned char *ptr; + uint32_t a, b, c, d; + uint32_t saved_a, saved_b, saved_c, saved_d; + + ptr = (const unsigned char *)data; + + a = ctx->a; + b = ctx->b; + c = ctx->c; + d = ctx->d; + + do { + saved_a = a; + saved_b = b; + saved_c = c; + saved_d = d; + + /* Round 1 */ + STEP(F, a, b, c, d, SET(0), 0xd76aa478, 7) + STEP(F, d, a, b, c, SET(1), 0xe8c7b756, 12) + STEP(F, c, d, a, b, SET(2), 0x242070db, 17) + STEP(F, b, c, d, a, SET(3), 0xc1bdceee, 22) + STEP(F, a, b, c, d, SET(4), 0xf57c0faf, 7) + STEP(F, d, a, b, c, SET(5), 0x4787c62a, 12) + STEP(F, c, d, a, b, SET(6), 0xa8304613, 17) + STEP(F, b, c, d, a, SET(7), 0xfd469501, 22) + STEP(F, a, b, c, d, SET(8), 0x698098d8, 7) + STEP(F, d, a, b, c, SET(9), 0x8b44f7af, 12) + STEP(F, c, d, a, b, SET(10), 0xffff5bb1, 17) + STEP(F, b, c, d, a, SET(11), 0x895cd7be, 22) + STEP(F, a, b, c, d, SET(12), 0x6b901122, 7) + STEP(F, d, a, b, c, SET(13), 0xfd987193, 12) + STEP(F, c, d, a, b, SET(14), 0xa679438e, 17) + STEP(F, b, c, d, a, SET(15), 0x49b40821, 22) + + /* Round 2 */ + STEP(G, a, b, c, d, GET(1), 0xf61e2562, 5) + STEP(G, d, a, b, c, GET(6), 0xc040b340, 9) + STEP(G, c, d, a, b, GET(11), 0x265e5a51, 14) + STEP(G, b, c, d, a, GET(0), 0xe9b6c7aa, 20) + STEP(G, a, b, c, d, GET(5), 0xd62f105d, 5) + STEP(G, d, a, b, c, GET(10), 0x02441453, 9) + STEP(G, c, d, a, b, GET(15), 0xd8a1e681, 14) + STEP(G, b, c, d, a, GET(4), 0xe7d3fbc8, 20) + STEP(G, a, b, c, d, GET(9), 0x21e1cde6, 5) + STEP(G, d, a, b, c, GET(14), 0xc33707d6, 9) + STEP(G, c, d, a, b, GET(3), 0xf4d50d87, 14) + STEP(G, b, c, d, a, GET(8), 0x455a14ed, 20) + STEP(G, a, b, c, d, GET(13), 0xa9e3e905, 5) + STEP(G, d, a, b, c, GET(2), 0xfcefa3f8, 9) + STEP(G, c, d, a, b, GET(7), 0x676f02d9, 14) + STEP(G, b, c, d, a, GET(12), 0x8d2a4c8a, 20) + + /* Round 3 */ + STEP(H, a, b, c, d, GET(5), 0xfffa3942, 4) + STEP(H2, d, a, b, c, GET(8), 0x8771f681, 11) + STEP(H, c, d, a, b, GET(11), 0x6d9d6122, 16) + STEP(H2, b, c, d, a, GET(14), 0xfde5380c, 23) + STEP(H, a, b, c, d, GET(1), 0xa4beea44, 4) + STEP(H2, d, a, b, c, GET(4), 0x4bdecfa9, 11) + STEP(H, c, d, a, b, GET(7), 0xf6bb4b60, 16) + STEP(H2, b, c, d, a, GET(10), 0xbebfbc70, 23) + STEP(H, a, b, c, d, GET(13), 0x289b7ec6, 4) + STEP(H2, d, a, b, c, GET(0), 0xeaa127fa, 11) + STEP(H, c, d, a, b, GET(3), 0xd4ef3085, 16) + STEP(H2, b, c, d, a, GET(6), 0x04881d05, 23) + STEP(H, a, b, c, d, GET(9), 0xd9d4d039, 4) + STEP(H2, d, a, b, c, GET(12), 0xe6db99e5, 11) + STEP(H, c, d, a, b, GET(15), 0x1fa27cf8, 16) + STEP(H2, b, c, d, a, GET(2), 0xc4ac5665, 23) + + /* Round 4 */ + STEP(I, a, b, c, d, GET(0), 0xf4292244, 6) + STEP(I, d, a, b, c, GET(7), 0x432aff97, 10) + STEP(I, c, d, a, b, GET(14), 0xab9423a7, 15) + STEP(I, b, c, d, a, GET(5), 0xfc93a039, 21) + STEP(I, a, b, c, d, GET(12), 0x655b59c3, 6) + STEP(I, d, a, b, c, GET(3), 0x8f0ccc92, 10) + STEP(I, c, d, a, b, GET(10), 0xffeff47d, 15) + STEP(I, b, c, d, a, GET(1), 0x85845dd1, 21) + STEP(I, a, b, c, d, GET(8), 0x6fa87e4f, 6) + STEP(I, d, a, b, c, GET(15), 0xfe2ce6e0, 10) + STEP(I, c, d, a, b, GET(6), 0xa3014314, 15) + STEP(I, b, c, d, a, GET(13), 0x4e0811a1, 21) + STEP(I, a, b, c, d, GET(4), 0xf7537e82, 6) + STEP(I, d, a, b, c, GET(11), 0xbd3af235, 10) + STEP(I, c, d, a, b, GET(2), 0x2ad7d2bb, 15) + STEP(I, b, c, d, a, GET(9), 0xeb86d391, 21) + + a += saved_a; + b += saved_b; + c += saved_c; + d += saved_d; + + ptr += 64; + } while (size -= 64); + + ctx->a = a; + ctx->b = b; + ctx->c = c; + ctx->d = d; + + return ptr; +} + +void MD5_Init(MD5_CTX *ctx) +{ + ctx->a = 0x67452301; + ctx->b = 0xefcdab89; + ctx->c = 0x98badcfe; + ctx->d = 0x10325476; + + ctx->lo = 0; + ctx->hi = 0; +} + +void MD5_Update(MD5_CTX *ctx, const void *data, unsigned long size) +{ + uint32_t saved_lo; + unsigned long used, available; + + saved_lo = ctx->lo; + if ((ctx->lo = (saved_lo + size) & 0x1fffffff) < saved_lo) + ctx->hi++; + ctx->hi += (uint32_t)(size >> 29); + + used = saved_lo & 0x3f; + + if (used) { + available = 64 - used; + + if (size < available) { + memcpy(&ctx->buffer[used], data, size); + return; + } + + memcpy(&ctx->buffer[used], data, available); + data = (const unsigned char *)data + available; + size -= available; + body(ctx, ctx->buffer, 64); + } + + if (size >= 64) { + data = body(ctx, data, size & ~(unsigned long)0x3f); + size &= 0x3f; + } + + memcpy(ctx->buffer, data, size); +} + +#define OUT(dst, src) \ + (dst)[0] = (unsigned char)(src); \ + (dst)[1] = (unsigned char)((src) >> 8); \ + (dst)[2] = (unsigned char)((src) >> 16); \ + (dst)[3] = (unsigned char)((src) >> 24); + +void MD5_Final(unsigned char *result, MD5_CTX *ctx) +{ + unsigned long used, available; + + used = ctx->lo & 0x3f; + + ctx->buffer[used++] = 0x80; + + available = 64 - used; + + if (available < 8) { + memset(&ctx->buffer[used], 0, available); + body(ctx, ctx->buffer, 64); + used = 0; + available = 64; + } + + memset(&ctx->buffer[used], 0, available - 8); + + ctx->lo <<= 3; + OUT(&ctx->buffer[56], ctx->lo) + OUT(&ctx->buffer[60], ctx->hi) + + body(ctx, ctx->buffer, 64); + + OUT(&result[0], ctx->a) + OUT(&result[4], ctx->b) + OUT(&result[8], ctx->c) + OUT(&result[12], ctx->d) + + memset(ctx, 0, sizeof(*ctx)); +} + +void sppro_md5(const void *data, size_t size, unsigned char digest[16]) +{ + MD5_CTX ctx; + MD5_Init(&ctx); + MD5_Update(&ctx, data, (unsigned long)size); + MD5_Final(digest, &ctx); +} diff --git a/src/md5.h b/src/md5.h new file mode 100644 index 0000000..729db08 --- /dev/null +++ b/src/md5.h @@ -0,0 +1,30 @@ +/* + * This is an OpenSSL-compatible implementation of the RSA Data Security, Inc. + * MD5 Message-Digest Algorithm (RFC 1321). + * + * Written by Alexander Peslyak (Solar Designer) in 2001 and placed in the + * public domain. There are absolutely no warranties. + * + * See md5.c for the full notice. Trimmed to the API used by sppro. + */ +#ifndef SPPRO_MD5_H +#define SPPRO_MD5_H + +#include +#include + +typedef struct { + uint32_t lo, hi; + uint32_t a, b, c, d; + unsigned char buffer[64]; + uint32_t block[16]; +} MD5_CTX; + +void MD5_Init(MD5_CTX *ctx); +void MD5_Update(MD5_CTX *ctx, const void *data, unsigned long size); +void MD5_Final(unsigned char *result, MD5_CTX *ctx); + +/* Convenience one-shot: digest must point to 16 bytes. */ +void sppro_md5(const void *data, size_t size, unsigned char digest[16]); + +#endif /* SPPRO_MD5_H */ diff --git a/src/sppro.h b/src/sppro.h new file mode 100644 index 0000000..92f189e --- /dev/null +++ b/src/sppro.h @@ -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 : | data[words*2] | crc16[2] + * Write : 'W' | (words-1) | addr[4] | crc16(hdr6)[2] | data[words*2] | crc16(all)[2] + * WriteR : + * A received frame is valid when crc16 over the whole message == 0. + * + * C99, freestanding-friendly: depends only on /. + */ +#ifndef SPPRO_H +#define SPPRO_H + +#include +#include + +#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 */