diff --git a/linux_unit_tests/Makefile b/linux_unit_tests/Makefile index 3d42f0a..011a166 100644 --- a/linux_unit_tests/Makefile +++ b/linux_unit_tests/Makefile @@ -57,7 +57,7 @@ INCLUDES = -I. -I../unit_tests/main -I$(DEV_TYPE_GEN_DIR) -I$(ESPNOW_DIR) \ -I$(CORE)/DeviceManager -I$(CORE)/DeviceTypes -I$(CORE)/APICommon -I$(CORE)/FileSystem \ -I$(CORE)/RestAPIEndpoints -I$(CORE)/MiniHDLC -I$(CORE)/ThreadSafeQueue -I$(CORE)/SysManager \ -I$(CORE)/SysTypes -I$(CORE)/RingBuffer -I$(CORE)/MQTT -I$(CORE)/LEDPixels \ - -I$(COMMS)/FileStreamProtocols -I$(COMMS)/ProtocolExchange -I$(COMMS)/ProtocolBase -I$(COMMS)/ProtocolRawMsg \ + -I$(COMMS)/FileStreamProtocols -I$(COMMS)/ProtocolOverAscii -I$(COMMS)/ProtocolExchange -I$(COMMS)/ProtocolBase -I$(COMMS)/ProtocolRawMsg \ -I$(COMMS)/CommsCoreIF -I$(COMMS)/CommsChannelMsg -I$(COMMS)/CommsChannels -I$(COMMS)/ProtocolRICSerial \ -I$(COMMS)/ProtocolRICFrame -I$(COMMS)/ProtocolRICJSON -I$(COMMS)/RICRESTMsg -I$(COMMS)/CommsBridgeMsg @@ -118,6 +118,7 @@ SOURCES_test_thread_safe_queue = test_thread_safe_queue.cpp $(COMMON_SOURCES) SOURCES_test_simple_buffer = test_simple_buffer.cpp $(CORE)/MiniHDLC/MiniHDLC.cpp $(COMMON_SOURCES) SOURCES_test_file_system_paths = test_file_system_paths.cpp $(COMMS_SOURCES) $(COMMON_SOURCES) SOURCES_test_mini_hdlc = test_mini_hdlc.cpp $(CORE)/MiniHDLC/MiniHDLC.cpp $(COMMON_SOURCES) +SOURCES_test_comms_framing_vectors = test_comms_framing_vectors.cpp $(CORE)/MiniHDLC/MiniHDLC.cpp $(COMMS)/ProtocolOverAscii/ProtocolOverAscii.cpp $(COMMON_SOURCES) SOURCES_test_device_action_encoder = test_device_action_encoder.cpp $(CORE)/DeviceTypes/DeviceActionEncoder.cpp $(COMMON_SOURCES) SOURCES_test_mqtt_protocol = test_mqtt_protocol.cpp $(CORE)/MQTT/MQTTProtocol.cpp $(COMMON_SOURCES) @@ -125,7 +126,7 @@ SOURCES_test_espnow_config = test_espnow_config.cpp $(ESPNOW_DIR)/ESPNowConfig.c # Tests run by "make check" TESTS = test_raft_json test_raft_utils test_device_names test_device_settings test_device_type_settings test_device_data_subscribers test_device_type_records \ - test_device_type_table test_device_type_grammar test_device_type_policy test_device_type_file test_catalogue_index test_runtime_decoder test_poll_data_decode test_bus_ident test_bus_scan_schedule test_device_poll_timing test_device_poll_scheduler test_poll_plan test_protocol_exchange test_file_upload_okto test_file_upload_background test_mini_hdlc test_mqtt_protocol test_thread_safe_queue test_simple_buffer test_file_system_paths test_led_strip_rmt_plan test_device_action_encoder + test_device_type_table test_device_type_grammar test_device_type_policy test_device_type_file test_catalogue_index test_runtime_decoder test_poll_data_decode test_bus_ident test_bus_scan_schedule test_device_poll_timing test_device_poll_scheduler test_poll_plan test_protocol_exchange test_file_upload_okto test_file_upload_background test_mini_hdlc test_mqtt_protocol test_thread_safe_queue test_simple_buffer test_file_system_paths test_led_strip_rmt_plan test_device_action_encoder test_comms_framing_vectors # Extra device type catalogues for test_device_type_records to sweep, e.g. # make check DEV_TYPE_CATALOGUES="../../RaftI2C/linux_unit_tests/TestDevTypeRecs.json" diff --git a/linux_unit_tests/README.md b/linux_unit_tests/README.md index 8532e30..25d8931 100644 --- a/linux_unit_tests/README.md +++ b/linux_unit_tests/README.md @@ -35,6 +35,7 @@ make -C linux_unit_tests check DEV_TYPE_CATALOGUES="../../RaftI2C/linux_unit_tes | `test_file_upload_okto` | `FileUploadOKTOProtocol`: when it acks - the first block, each batch, the last block, at once for the first block out of sequence (a lost block or one sent again), and on its timer - and that its acks stay in step with the host's batches after a loss or a timer ack | | `test_led_strip_rmt_plan` | `LEDStripRMTPlan`: the RMT memory (or DMA buffer) an LED strip's channel asks for - the whole frame in RMT memory when it fits in the strip's share, DMA where the chip has it when it doesn't, then smaller sizes; shares between strips, a configured size, DMA modes and when a frame is refilled | | `test_mini_hdlc` | `MiniHDLC`: frames encoded and decoded again up to 70000 bytes (past 64 KB), the frame length limit, and a 200000-byte limit (as ProtocolRICSerial sets with PSRAM) kept rather than truncated to 16 bits | +| `test_comms_framing_vectors` | Makes the shared vectors `scripts/tests/hdlc_vectors.json` and `overascii_vectors.json` from `MiniHDLC` and `ProtocolOverAscii` and fails if the files differ (the RICRESTProtocol wiki examples are checked too). Client libraries (raftjs, raftpy) test their framing against these files. After an intended change to the framing, run `./test_comms_framing_vectors --write` and copy the files to the clients | | `test_mqtt_protocol` | `MQTTProtocol`: CONNECT (with and without credentials), PUBLISH at QoS 0 and 1 with and without retain, long remaining lengths, SUBSCRIBE and PUBACK encoded as MQTT 3.1.1 specifies; broker packets decoded whether they arrive a byte at a time, several to a read or split across reads; malformed and overlong packets rejected; topic filter wildcards | | `test_thread_safe_queue` | `ThreadSafeQueue` (with its `SpiramAwareAllocator` deque): order, length limits, peek/pop/clear, many elements, and a producer and consumer on two threads | | `test_simple_buffer` | `SimpleBuffer` (MiniHDLC's frame buffers): grows geometrically and only when the memory is there (fails instead of crashing), `clear()` releases a buffer grown by a long frame; frames through MiniHDLC, including after a run longer than the limit | diff --git a/linux_unit_tests/test_comms_framing_vectors.cpp b/linux_unit_tests/test_comms_framing_vectors.cpp new file mode 100644 index 0000000..57f7b21 --- /dev/null +++ b/linux_unit_tests/test_comms_framing_vectors.cpp @@ -0,0 +1,392 @@ +///////////////////////////////////////////////////////////////////////////////////////////////////////////////// +// +// Comms framing vectors: HDLC (RICSerial) and OverAscii (serial console) +// +// Makes the shared vectors scripts/tests/hdlc_vectors.json and scripts/tests/overascii_vectors.json from the +// firmware's own MiniHDLC and ProtocolOverAscii, so that client libraries (raftjs, raftpy) frame and unframe +// exactly as the firmware does. Run as a test (make check) it makes the vectors again and fails if the files +// differ, so a change to the framing code shows up as a change to the vectors. +// +// ./test_comms_framing_vectors check the files in ../scripts/tests +// ./test_comms_framing_vectors --write [dir] write the files (default ../scripts/tests) +// +// The serial console cases split a byte stream as SerialConsole does: bytes >= 0x80 are OverAscii-encoded +// protocol bytes (decoded, then passed to HDLC), other bytes are console text. +// +///////////////////////////////////////////////////////////////////////////////////////////////////////////////// + +#include +#include +#include +#include +#include +#include +#include "testhdr.h" +#include "MiniHDLC.h" +#include "ProtocolOverAscii.h" + +typedef std::vector Bytes; + +static const uint32_t DEFAULT_MAX_LEN = 5000; + +static std::string hex(const Bytes& b) +{ + std::string s; + char buf[3]; + for (uint8_t v : b) + { + snprintf(buf, sizeof(buf), "%02x", v); + s += buf; + } + return s; +} + +static Bytes str(const char* s, bool nulTerm = false) +{ + Bytes b((const uint8_t*)s, (const uint8_t*)s + strlen(s)); + if (nulTerm) + b.push_back(0); + return b; +} + +static Bytes cat(std::initializer_list parts) +{ + Bytes out; + for (auto& p : parts) + out.insert(out.end(), p.begin(), p.end()); + return out; +} + +static std::string jsonStr(const std::string& s) +{ + std::string out = "\""; + for (unsigned char c : s) + { + if (c == '"' || c == '\\') + { + out += '\\'; + out += (char)c; + } + else if (c < 0x20 || c >= 0x7f) + { + char buf[8]; + snprintf(buf, sizeof(buf), "\\u%04x", c); + out += buf; + } + else + out += (char)c; + } + return out + "\""; +} + +// RICSerial frame payload: msgNum, (msgType << 6) | protocol, then the RICREST element +static Bytes ricrestURL(uint8_t msgNum, const char* url) +{ + return cat({{msgNum, 0x02, 0x00}, str(url, true)}); +} + +/////////////////////////////////////////////////////////////////////////////// +// HDLC using the firmware code +/////////////////////////////////////////////////////////////////////////////// + +static Bytes hdlcEncode(const Bytes& payload) +{ + MiniHDLC hdlc(nullptr, nullptr, 0xE7, 0xD7, DEFAULT_MAX_LEN, DEFAULT_MAX_LEN); + Bytes encoded(hdlc.calcEncodedLen(payload.data(), payload.size())); + uint32_t len = hdlc.encodeFrame(encoded.data(), encoded.size(), payload.data(), payload.size()); + encoded.resize(len); + return encoded; +} + +static std::vector hdlcDecode(const Bytes& stream, uint32_t maxLen) +{ + std::vector frames; + MiniHDLC hdlc(nullptr, [&](const uint8_t* pFrame, unsigned len) { frames.emplace_back(pFrame, pFrame + len); }, + 0xE7, 0xD7, maxLen, maxLen); + for (uint8_t b : stream) + hdlc.handleChar(b); + return frames; +} + +static uint16_t crc16(const Bytes& data) +{ + return MiniHDLC::crcUpdateCCITT(0xffff, data.data(), data.size()); +} + +// A payload (msg header + URL element) whose CRC has an escaped byte (0xE7 or 0xD7) in the given position +static Bytes payloadWithEscapedCRC(bool highByte) +{ + for (int i = 0; i < 100000; i++) + { + std::string url = "v" + std::to_string(i); + Bytes p = ricrestURL(1, url.c_str()); + uint16_t crc = crc16(p); + uint8_t b = highByte ? (crc >> 8) : (crc & 0xff); + if (b == 0xE7 || b == 0xD7) + return p; + } + return {}; +} + +/////////////////////////////////////////////////////////////////////////////// +// OverAscii using the firmware code +/////////////////////////////////////////////////////////////////////////////// + +static Bytes overAsciiEncode(const Bytes& data) +{ + Bytes out(data.size() * 2 + 1); + uint32_t len = ProtocolOverAscii::encodeFrame(data.data(), data.size(), out.data(), out.size()); + out.resize(len); + return out; +} + +static Bytes overAsciiDecode(const Bytes& stream) +{ + ProtocolOverAscii dec; + Bytes out; + for (uint8_t b : stream) + { + int v = dec.decodeByte(b); + if (v >= 0) + out.push_back((uint8_t)v); + } + return out; +} + +// Split a console stream as SerialConsole does +static void consoleSplit(const Bytes& stream, std::string& text, std::vector& frames) +{ + ProtocolOverAscii dec; + MiniHDLC hdlc(nullptr, [&](const uint8_t* pFrame, unsigned len) { frames.emplace_back(pFrame, pFrame + len); }, + 0xE7, 0xD7, DEFAULT_MAX_LEN, DEFAULT_MAX_LEN); + for (uint8_t b : stream) + { + if (b >= 0x80) + { + int v = dec.decodeByte(b); + if (v >= 0) + hdlc.handleChar((uint8_t)v); + } + else + text += (char)b; + } +} + +/////////////////////////////////////////////////////////////////////////////// +// Vector files +/////////////////////////////////////////////////////////////////////////////// + +static std::string framesJson(const std::vector& frames) +{ + std::string s = "["; + for (size_t i = 0; i < frames.size(); i++) + s += (i ? ", \"" : "\"") + hex(frames[i]) + "\""; + return s + "]"; +} + +static std::string makeHdlcVectors() +{ + std::string j = "{\n"; + j += " \"_about\": \"HDLC framing as RICSerial uses it. Made from RaftCore MiniHDLC by linux_unit_tests/test_comms_framing_vectors" + " --write - do not edit. Frame: flag, escaped(payload, CRC high, CRC low), flag. Bytes equal to the flag or" + " escape are sent as escape, byte ^ 0x20. CRC is CRC-16/CCITT-FALSE (poly 0x1021, init 0xffff) of the payload." + " Decoding: bytes from one flag to the next are a frame if there are at least 2 and the last 2 are the CRC of the" + " others (bytes before the first flag count as a frame too); otherwise they are dropped. A frame longer than" + " maxLen (payload + CRC) is discarded at that point and decoding starts again from the next byte.\",\n"; + j += " \"flag\": \"e7\",\n \"escape\": \"d7\",\n \"defaultMaxLen\": " + std::to_string(DEFAULT_MAX_LEN) + ",\n"; + + // CRC + struct { const char* desc; Bytes data; } crcCases[] = { + { "check value", str("123456789") }, + { "empty", {} }, + { "url v, msgNum 1", ricrestURL(1, "v") }, + }; + j += " \"crc\": [\n"; + for (size_t i = 0; i < sizeof(crcCases) / sizeof(crcCases[0]); i++) + { + char crcHex[8]; + snprintf(crcHex, sizeof(crcHex), "%04x", crc16(crcCases[i].data)); + j += std::string(" {\"desc\": ") + jsonStr(crcCases[i].desc) + ", \"data\": \"" + hex(crcCases[i].data) + + "\", \"crc\": \"" + crcHex + "\"}" + (i + 1 < sizeof(crcCases) / sizeof(crcCases[0]) ? ",\n" : "\n"); + } + j += " ],\n"; + + // Encode (and decode back) + Bytes allBytes(256); + for (int i = 0; i < 256; i++) + allBytes[i] = i; + std::vector> enc = { + { "url v, msgNum 1 (RICRESTProtocol wiki example)", ricrestURL(1, "v") }, + { "url filelist, msgNum 1 (wiki example)", ricrestURL(1, "filelist") }, + { "url v, msgNum 0xe7: flag byte escaped (wiki example)", ricrestURL(0xE7, "v") }, + { "escape byte in payload", {0x01, 0x02, 0xD7, 0x00} }, + { "flag and escape bytes together", {0xE7, 0xD7, 0xE7, 0xD7} }, + { "CRC high byte escaped", payloadWithEscapedCRC(true) }, + { "CRC low byte escaped", payloadWithEscapedCRC(false) }, + { "empty payload", {} }, + { "command frame (cmdName JSON)", cat({{0x05, 0x02, 0x03}, str("{\"cmdName\":\"ufEnd\",\"streamID\":1}", true)}) }, + { "response (msgType 1 = 0x42)", cat({{0x05, 0x42, 0x01}, str("{\"req\":\"v\",\"rslt\":\"ok\"}", true)}) }, + { "publish (msgType 2, protocol 0 = 0x80) with devbin envelope", {0x00, 0x80, 0xDB, 0x03, 0x07, 0x00, 0x08, 0x81, 0x00, 0x00, 0x00, 0x6A, 0x00, 0x05, 0x01} }, + { "file block, stream 1, position 0x0102e7", {0x09, 0x02, 0x04, 0x01, 0x01, 0x02, 0xE7, 0xAA, 0xD7, 0x55} }, + { "every byte value", allBytes }, + { "every byte and both CRC bytes escaped (longest encoding: 2 x payload + 6)", {0xD7, 0xD7, 0xD7, 0xE7, 0xE7, 0xE7, 0xE7, 0xE7, 0xD7, 0xE7, 0xD7} }, + }; + j += " \"encode\": [\n"; + for (size_t i = 0; i < enc.size(); i++) + { + Bytes encoded = hdlcEncode(enc[i].second); + std::vector back = hdlcDecode(encoded, DEFAULT_MAX_LEN); + TEST_ASSERT(back.size() == 1 && back[0] == enc[i].second, ("decodes back: " + enc[i].first).c_str()); + j += " {\"desc\": " + jsonStr(enc[i].first) + ", \"payload\": \"" + hex(enc[i].second) + + "\", \"encoded\": \"" + hex(encoded) + "\"}" + (i + 1 < enc.size() ? ",\n" : "\n"); + } + j += " ],\n"; + + // Decode streams + Bytes fA = hdlcEncode(ricrestURL(1, "v")); + Bytes fB = hdlcEncode(ricrestURL(2, "filelist")); + Bytes fC = hdlcEncode({0x00, 0x80, 0x7B, 0x7D}); + Bytes fANoStart(fA.begin() + 1, fA.end()); + Bytes fBNoStart(fB.begin() + 1, fB.end()); + Bytes fBadCRC = fA; + fBadCRC[fBadCRC.size() - 2] ^= 0x01; + Bytes zeroLenWithCRC = {0xE7, 0xFF, 0xFF, 0xE7}; + Bytes longPayload(40, 0x11); + Bytes fLong = hdlcEncode(longPayload); + Bytes escAtEnd = {0xE7, 0x01, 0xD7, 0xE7}; + std::vector>> dec = { + { "one frame", { fA, DEFAULT_MAX_LEN } }, + { "two frames, each with both flags", { cat({fA, fB}), DEFAULT_MAX_LEN } }, + { "three frames sharing flags", { cat({fA, fBNoStart, Bytes(fC.begin() + 1, fC.end())}), DEFAULT_MAX_LEN } }, + { "no opening flag: bytes before the first flag are a frame", { fANoStart, DEFAULT_MAX_LEN } }, + { "junk before the first flag is dropped (CRC fails)", { cat({str("junk"), fA}), DEFAULT_MAX_LEN } }, + { "bad CRC dropped, next frame decoded", { cat({fBadCRC, fB}), DEFAULT_MAX_LEN } }, + { "repeated flags between frames", { cat({{0xE7, 0xE7, 0xE7}, fA, {0xE7, 0xE7}, fB}), DEFAULT_MAX_LEN } }, + { "flag pairs alone: nothing", { {0xE7, 0xE7, 0xE7, 0xE7}, DEFAULT_MAX_LEN } }, + { "single byte between flags: nothing", { {0xE7, 0x01, 0xE7}, DEFAULT_MAX_LEN } }, + { "2 bytes equal to the CRC of nothing: an empty frame", { zeroLenWithCRC, DEFAULT_MAX_LEN } }, + { "escape just before the flag is dropped with the frame", { cat({escAtEnd, fB}), DEFAULT_MAX_LEN } }, + { "incomplete frame at the end: nothing yet", { Bytes(fA.begin(), fA.end() - 1), DEFAULT_MAX_LEN } }, + { "frame over maxLen dropped, next frame decoded", { cat({fLong, fA}), 20 } }, + { "frame of exactly maxLen (payload + CRC) decoded", { hdlcEncode(Bytes(18, 0x22)), 20 } }, + }; + j += " \"decode\": [\n"; + for (size_t i = 0; i < dec.size(); i++) + { + std::vector frames = hdlcDecode(dec[i].second.first, dec[i].second.second); + j += " {\"desc\": " + jsonStr(dec[i].first) + ", \"stream\": \"" + hex(dec[i].second.first) + "\", "; + if (dec[i].second.second != DEFAULT_MAX_LEN) + j += "\"maxLen\": " + std::to_string(dec[i].second.second) + ", "; + j += "\"frames\": " + framesJson(frames) + "}" + (i + 1 < dec.size() ? ",\n" : "\n"); + } + j += " ]\n}\n"; + + // Checks of the documented behaviour (the vectors record whatever the code does - these make sure it is right) + TEST_ASSERT(crc16(str("123456789")) == 0x29B1, "CRC check value 0x29b1"); + TEST_ASSERT(hex(hdlcEncode(ricrestURL(1, "v"))) == "e70102007600f4cae7", "wiki example v"); + TEST_ASSERT(hex(hdlcEncode(ricrestURL(1, "filelist"))) == "e701020066696c656c69737400d1dce7", "wiki example filelist"); + TEST_ASSERT(hex(hdlcEncode(ricrestURL(0xE7, "v"))) == "e7d7c7020076000243e7", "wiki example v, msgNum 0xe7"); + TEST_ASSERT(hdlcDecode(cat({fA, fB}), DEFAULT_MAX_LEN).size() == 2, "two frames"); + TEST_ASSERT(hdlcDecode(cat({fBadCRC, fB}), DEFAULT_MAX_LEN).size() == 1, "bad CRC dropped"); + return j; +} + +static std::string makeOverAsciiVectors() +{ + std::string j = "{\n"; + j += " \"_about\": \"OverAscii encoding used for protocol bytes on the serial console (SerialConsole), so every byte" + " sent has its top bit set and can be told apart from console text. Made from RaftCore ProtocolOverAscii by" + " linux_unit_tests/test_comms_framing_vectors --write - do not edit. Encoding: 0x00-0x0f -> 0x85, (b ^ 0x20) | 0x80;" + " 0x10-0x7f -> b | 0x80; 0x80-0x8f -> 0x8e, b ^ 0x20; 0x90-0xff -> 0x8f, b. The bytes sent over the console are" + " OverAscii(HDLC(frame)). console cases split a received stream as SerialConsole does: bytes >= 0x80 are decoded" + " and passed to HDLC, other bytes are console text.\",\n"; + + Bytes allBytes(256); + for (int i = 0; i < 256; i++) + allBytes[i] = i; + std::vector> enc = { + { "every byte value", allBytes }, + { "HDLC frame: url v, msgNum 1", hdlcEncode(ricrestURL(1, "v")) }, + { "empty", {} }, + }; + j += " \"encode\": [\n"; + for (size_t i = 0; i < enc.size(); i++) + { + Bytes encoded = overAsciiEncode(enc[i].second); + TEST_ASSERT(overAsciiDecode(encoded) == enc[i].second, ("decodes back: " + enc[i].first).c_str()); + bool allHigh = true; + for (uint8_t b : encoded) + allHigh = allHigh && (b >= 0x80); + TEST_ASSERT(allHigh, ("every encoded byte has the top bit set: " + enc[i].first).c_str()); + j += " {\"desc\": " + jsonStr(enc[i].first) + ", \"data\": \"" + hex(enc[i].second) + + "\", \"encoded\": \"" + hex(encoded) + "\"}" + (i + 1 < enc.size() ? ",\n" : "\n"); + } + j += " ],\n"; + + // Console streams: text and protocol bytes interleaved + Bytes fA = overAsciiEncode(hdlcEncode(ricrestURL(1, "v"))); + Bytes fB = overAsciiEncode(hdlcEncode(cat({{0x01, 0x42, 0x01}, str("{\"req\":\"v\",\"rslt\":\"ok\"}", true)}))); + size_t half = fB.size() / 2; + if (fB[half - 1] == 0x85 || fB[half - 1] == 0x8E || fB[half - 1] == 0x8F) + half++; + Bytes fBEscSplit; + size_t escPos = 0; + for (size_t i = 0; i < fB.size(); i++) + if (fB[i] == 0x85 || fB[i] == 0x8E || fB[i] == 0x8F) { escPos = i; break; } + std::vector> con = { + { "text only", str("I (1234) SysMan: started\r\n") }, + { "frame only", fA }, + { "log line then frame then text", cat({str("I (10) Log: hello\r\n"), fA, str("typed\r\n")}) }, + { "log text in the middle of a frame", cat({Bytes(fB.begin(), fB.begin() + half), str("W (11) mid\r\n"), Bytes(fB.begin() + half, fB.end())}) }, + { "log text between an escape and its byte", cat({Bytes(fB.begin(), fB.begin() + escPos + 1), str("txt"), Bytes(fB.begin() + escPos + 1, fB.end())}) }, + { "two frames back to back", cat({fA, fB}) }, + }; + j += " \"console\": [\n"; + for (size_t i = 0; i < con.size(); i++) + { + std::string text; + std::vector frames; + consoleSplit(con[i].second, text, frames); + j += " {\"desc\": " + jsonStr(con[i].first) + ", \"stream\": \"" + hex(con[i].second) + "\", \"text\": " + + jsonStr(text) + ", \"frames\": " + framesJson(frames) + "}" + (i + 1 < con.size() ? ",\n" : "\n"); + } + j += " ]\n}\n"; + return j; +} + +static bool readFile(const std::string& path, std::string& out) +{ + std::ifstream f(path); + if (!f.good()) + return false; + std::stringstream ss; + ss << f.rdbuf(); + out = ss.str(); + return true; +} + +int main(int argc, char** argv) +{ + bool write = (argc > 1) && (strcmp(argv[1], "--write") == 0); + std::string dir = write ? (argc > 2 ? argv[2] : "../scripts/tests") : (argc > 1 ? argv[1] : "../scripts/tests"); + struct { const char* name; std::string content; } files[] = { + { "hdlc_vectors.json", makeHdlcVectors() }, + { "overascii_vectors.json", makeOverAsciiVectors() }, + }; + for (auto& f : files) + { + std::string path = dir + "/" + f.name; + if (write) + { + std::ofstream o(path); + o << f.content; + printf("Wrote %s\n", path.c_str()); + continue; + } + std::string existing; + TEST_ASSERT(readFile(path, existing), (std::string("read ") + path).c_str()); + TEST_ASSERT(existing == f.content, (path + " matches the firmware code (regenerate with --write if the change" + " is intended)").c_str()); + } + return testSummary("test_comms_framing_vectors"); +} diff --git a/scripts/tests/hdlc_vectors.json b/scripts/tests/hdlc_vectors.json new file mode 100644 index 0000000..50ced16 --- /dev/null +++ b/scripts/tests/hdlc_vectors.json @@ -0,0 +1,43 @@ +{ + "_about": "HDLC framing as RICSerial uses it. Made from RaftCore MiniHDLC by linux_unit_tests/test_comms_framing_vectors --write - do not edit. Frame: flag, escaped(payload, CRC high, CRC low), flag. Bytes equal to the flag or escape are sent as escape, byte ^ 0x20. CRC is CRC-16/CCITT-FALSE (poly 0x1021, init 0xffff) of the payload. Decoding: bytes from one flag to the next are a frame if there are at least 2 and the last 2 are the CRC of the others (bytes before the first flag count as a frame too); otherwise they are dropped. A frame longer than maxLen (payload + CRC) is discarded at that point and decoding starts again from the next byte.", + "flag": "e7", + "escape": "d7", + "defaultMaxLen": 5000, + "crc": [ + {"desc": "check value", "data": "313233343536373839", "crc": "29b1"}, + {"desc": "empty", "data": "", "crc": "ffff"}, + {"desc": "url v, msgNum 1", "data": "0102007600", "crc": "f4ca"} + ], + "encode": [ + {"desc": "url v, msgNum 1 (RICRESTProtocol wiki example)", "payload": "0102007600", "encoded": "e70102007600f4cae7"}, + {"desc": "url filelist, msgNum 1 (wiki example)", "payload": "01020066696c656c69737400", "encoded": "e701020066696c656c69737400d1dce7"}, + {"desc": "url v, msgNum 0xe7: flag byte escaped (wiki example)", "payload": "e702007600", "encoded": "e7d7c7020076000243e7"}, + {"desc": "escape byte in payload", "payload": "0102d700", "encoded": "e70102d7f70010a4e7"}, + {"desc": "flag and escape bytes together", "payload": "e7d7e7d7", "encoded": "e7d7c7d7f7d7c7d7f783bce7"}, + {"desc": "CRC high byte escaped", "payload": "0102007632343400", "encoded": "e70102007632343400d7f7b8e7"}, + {"desc": "CRC low byte escaped", "payload": "0102007634363200", "encoded": "e7010200763436320034d7c7e7"}, + {"desc": "empty payload", "payload": "", "encoded": "e7ffffe7"}, + {"desc": "command frame (cmdName JSON)", "payload": "0502037b22636d644e616d65223a227566456e64222c2273747265616d4944223a317d00", "encoded": "e70502037b22636d644e616d65223a227566456e64222c2273747265616d4944223a317d0076f9e7"}, + {"desc": "response (msgType 1 = 0x42)", "payload": "0542017b22726571223a2276222c2272736c74223a226f6b227d00", "encoded": "e70542017b22726571223a2276222c2272736c74223a226f6b227d00efa6e7"}, + {"desc": "publish (msgType 2, protocol 0 = 0x80) with devbin envelope", "payload": "0080db03070008810000006a000501", "encoded": "e70080db03070008810000006a00050145a4e7"}, + {"desc": "file block, stream 1, position 0x0102e7", "payload": "090204010102e7aad755", "encoded": "e7090204010102d7c7aad7f7559d05e7"}, + {"desc": "every byte value", "payload": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff", "encoded": "e7000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7f7d8d9dadbdcdddedfe0e1e2e3e4e5e6d7c7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff3fbde7"}, + {"desc": "every byte and both CRC bytes escaped (longest encoding: 2 x payload + 6)", "payload": "d7d7d7e7e7e7e7e7d7e7d7", "encoded": "e7d7f7d7f7d7f7d7c7d7c7d7c7d7c7d7c7d7f7d7c7d7f7d7f7d7f7e7"} + ], + "decode": [ + {"desc": "one frame", "stream": "e70102007600f4cae7", "frames": ["0102007600"]}, + {"desc": "two frames, each with both flags", "stream": "e70102007600f4cae7e702020066696c656c69737400d443e7", "frames": ["0102007600", "02020066696c656c69737400"]}, + {"desc": "three frames sharing flags", "stream": "e70102007600f4cae702020066696c656c69737400d443e700807b7dc403e7", "frames": ["0102007600", "02020066696c656c69737400", "00807b7d"]}, + {"desc": "no opening flag: bytes before the first flag are a frame", "stream": "0102007600f4cae7", "frames": ["0102007600"]}, + {"desc": "junk before the first flag is dropped (CRC fails)", "stream": "6a756e6be70102007600f4cae7", "frames": ["0102007600"]}, + {"desc": "bad CRC dropped, next frame decoded", "stream": "e70102007600f4cbe7e702020066696c656c69737400d443e7", "frames": ["02020066696c656c69737400"]}, + {"desc": "repeated flags between frames", "stream": "e7e7e7e70102007600f4cae7e7e7e702020066696c656c69737400d443e7", "frames": ["0102007600", "02020066696c656c69737400"]}, + {"desc": "flag pairs alone: nothing", "stream": "e7e7e7e7", "frames": []}, + {"desc": "single byte between flags: nothing", "stream": "e701e7", "frames": []}, + {"desc": "2 bytes equal to the CRC of nothing: an empty frame", "stream": "e7ffffe7", "frames": [""]}, + {"desc": "escape just before the flag is dropped with the frame", "stream": "e701d7e7e702020066696c656c69737400d443e7", "frames": ["02020066696c656c69737400"]}, + {"desc": "incomplete frame at the end: nothing yet", "stream": "e70102007600f4ca", "frames": []}, + {"desc": "frame over maxLen dropped, next frame decoded", "stream": "e711111111111111111111111111111111111111111111111111111111111111111111111111111111dffde7e70102007600f4cae7", "maxLen": 20, "frames": ["0102007600"]}, + {"desc": "frame of exactly maxLen (payload + CRC) decoded", "stream": "e7222222222222222222222222222222222222fdfde7", "maxLen": 20, "frames": ["222222222222222222222222222222222222"]} + ] +} diff --git a/scripts/tests/overascii_vectors.json b/scripts/tests/overascii_vectors.json new file mode 100644 index 0000000..e7d213c --- /dev/null +++ b/scripts/tests/overascii_vectors.json @@ -0,0 +1,16 @@ +{ + "_about": "OverAscii encoding used for protocol bytes on the serial console (SerialConsole), so every byte sent has its top bit set and can be told apart from console text. Made from RaftCore ProtocolOverAscii by linux_unit_tests/test_comms_framing_vectors --write - do not edit. Encoding: 0x00-0x0f -> 0x85, (b ^ 0x20) | 0x80; 0x10-0x7f -> b | 0x80; 0x80-0x8f -> 0x8e, b ^ 0x20; 0x90-0xff -> 0x8f, b. The bytes sent over the console are OverAscii(HDLC(frame)). console cases split a received stream as SerialConsole does: bytes >= 0x80 are decoded and passed to HDLC, other bytes are console text.", + "encode": [ + {"desc": "every byte value", "data": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff", "encoded": "85a085a185a285a385a485a585a685a785a885a985aa85ab85ac85ad85ae85af909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff8ea08ea18ea28ea38ea48ea58ea68ea78ea88ea98eaa8eab8eac8ead8eae8eaf8f908f918f928f938f948f958f968f978f988f998f9a8f9b8f9c8f9d8f9e8f9f8fa08fa18fa28fa38fa48fa58fa68fa78fa88fa98faa8fab8fac8fad8fae8faf8fb08fb18fb28fb38fb48fb58fb68fb78fb88fb98fba8fbb8fbc8fbd8fbe8fbf8fc08fc18fc28fc38fc48fc58fc68fc78fc88fc98fca8fcb8fcc8fcd8fce8fcf8fd08fd18fd28fd38fd48fd58fd68fd78fd88fd98fda8fdb8fdc8fdd8fde8fdf8fe08fe18fe28fe38fe48fe58fe68fe78fe88fe98fea8feb8fec8fed8fee8fef8ff08ff18ff28ff38ff48ff58ff68ff78ff88ff98ffa8ffb8ffc8ffd8ffe8fff"}, + {"desc": "HDLC frame: url v, msgNum 1", "data": "e70102007600f4cae7", "encoded": "8fe785a185a285a0f685a08ff48fca8fe7"}, + {"desc": "empty", "data": "", "encoded": ""} + ], + "console": [ + {"desc": "text only", "stream": "4920283132333429205379734d616e3a20737461727465640d0a", "text": "I (1234) SysMan: started\u000d\u000a", "frames": []}, + {"desc": "frame only", "stream": "8fe785a185a285a0f685a08ff48fca8fe7", "text": "", "frames": ["0102007600"]}, + {"desc": "log line then frame then text", "stream": "492028313029204c6f673a2068656c6c6f0d0a8fe785a185a285a0f685a08ff48fca8fe774797065640d0a", "text": "I (10) Log: hello\u000d\u000atyped\u000d\u000a", "frames": ["0102007600"]}, + {"desc": "log text in the middle of a frame", "stream": "8fe785a1c285a1fba2f2e5f1a2baa2f6a2ac572028313129206d69640d0aa2f2f3ecf4a2baa2efeba2fd85a08fbabe8fe7", "text": "W (11) mid\u000d\u000a", "frames": ["0142017b22726571223a2276222c2272736c74223a226f6b227d00"]}, + {"desc": "log text between an escape and its byte", "stream": "8f747874e785a1c285a1fba2f2e5f1a2baa2f6a2aca2f2f3ecf4a2baa2efeba2fd85a08fbabe8fe7", "text": "txt", "frames": ["0142017b22726571223a2276222c2272736c74223a226f6b227d00"]}, + {"desc": "two frames back to back", "stream": "8fe785a185a285a0f685a08ff48fca8fe78fe785a1c285a1fba2f2e5f1a2baa2f6a2aca2f2f3ecf4a2baa2efeba2fd85a08fbabe8fe7", "text": "", "frames": ["0102007600", "0142017b22726571223a2276222c2272736c74223a226f6b227d00"]} + ] +}