Overview
castle_ext is the home for header-only functionality that extends Castle beyond its general-purpose core into external standards, communication protocols, and domain-specific implementations. Its scope is intended to grow over time, with each area remaining independently usable so applications can include only what they need.
So far, castle_ext provides geodetic calculations, GNSS support for NMEA 0183 and u-blox UBX, and input/output utilities under castle_ext/io: POSIX file-descriptor ownership and control with a poll() event manager, regular file access, UART, SPI and I2C device owners, and a platform-neutral GPIO abstraction. These modules complement Castle's general-purpose containers, callbacks, math, and status utilities.
These boundaries let an application use only the pieces it needs. For example, a device driver can feed bytes to a parser and decode typed messages, while a separate application layer can use geodetic calculations without depending on a transport or parser. The same modular approach provides room to add support for other external standards, protocols, and reusable automotive features without coupling them to Castle's core.
Modules
| Area | Capabilities and documentation |
|---|---|
| Checksums | Table-free streaming and one-shot CRC-8/16/32/64, Fletcher-16/32/64, and XOR checksums for deterministic, non-cryptographic error detection. CRC-8 · CRC-16 · CRC-32 · CRC-64 · Fletcher-16 · Fletcher-32 · Fletcher-64 · Fletcher engine · XOR |
| Codecs | Caller-buffered Base32 and Base64, including padded or unpadded forms and standard or URL-safe Base64, plus hexadecimal encoding and decoding. Base32 · Base64 · Hexadecimal |
| Crypto | Fixed-size AES-128/192/256 block and CTR operations, RFC 8439 ChaCha20, and streaming MD5, SHA-256, and SHA-512 hash primitives. AES · ChaCha20 · MD5 · SHA-256 · SHA-512 |
| Filter | Fixed-capacity debounce, hold, and auto-repeat state machine for sampled boolean signals such as buttons, switches, and GPIO inputs. Debounce sampling |
| Geodetic | geo_point, DMS/DDM and angle conversions, WGS-84/PZ-90.11/Krasovsky datum policies, Haversine and Vincenty distance/bearing, WGS-84/GCJ-02 transforms, and fixed-capacity circular and polygon geofences.Coordinates · Datums · Distance and bearing · Transforms · Geofences · Shared utilities |
| NMEA 0183 | Sentence framing and checksums, tokenized views, field parsing and encoding, typed sentence models, generation, streaming parsing, and a protocol-bound decoder registry. Protocol primitives · Field cursor · Sentence models · Generator · Parser · Decoder registry |
| u-blox UBX | Binary frame encoding/decoding, checksums and little-endian accessors, checked payload reading, VALSET/VALGET configuration helpers, typed messages, streaming parsing, and a protocol-bound decoder registry. Protocol primitives · Payload reader · Configuration · Message models · Parser · Decoder registry |
| I/O: file descriptors | POSIX file-descriptor helpers in castle::io::fd: move-only basic_fd ownership, flag and close control, partial and exact byte I/O, plus a fixed-capacity poll() event manager that queues ready callbacks and dispatches them outside its locks.Overview · Descriptor owner · Descriptor control · Poll event manager |
| I/O: files | Move-only basic_file / linux_file owner for ordinary POSIX files and BSP device nodes, with bounded reads and writes, seek, size, truncate and fsync.Linux file |
| I/O: UART | Move-only basic_uart / uart owner for termios-configured serial ports, covering baud rate, framing, flow control, receive timing, queue flushing, drain and pending-byte queries.UART |
| I/O: SPI | Move-only basic_spi / spi owner for Linux spidev nodes, with SPI mode, word width and clock configuration, plus a synchronous full-duplex transfer().SPI |
| I/O: I2C | Move-only basic_i2c / i2c owner for Linux i2c-dev adapters bound to a 7-bit or 10-bit target, with byte-stream I/O, repeated-START write_read() transactions and adapter capability queries.I2C |
| I/O: GPIO | Platform-neutral basic_pin and basic_port facades over a compile-time-checked backend contract, with mock, Linux value-file, and Zephyr device-tree backends.Types · Pin · Port · Backends |
| Serialization | Fixed-capacity CSV, INI, JSON, and XML documents with parsers and serializers for embedded configuration and data exchange, without heap allocation. CSV · INI · JSON · XML |
| Timing / PTP | IEEE 1588-2008 PTPv2 slave exchange with one-step and two-step Sync support, fixed-buffer Delay_Req encoding, timestamp correlation, and clock-adjustment callback integration. PTP slave prototype |
Constraints & notes
All extensions are intended to fit embedded use: their protocol and parser implementations use fixed storage and Castle callbacks rather than requiring heap allocation, exceptions, RTTI, virtual dispatch, or STL containers. See each component page for its precise limits and lifetime requirements.
I/O components are synchronous and add no hidden threads. Locking is left to the caller, except for the poll manager's own state. POSIX code is gated by CASTLE_USING_POSIX_APIS; SPI and I2C also require Linux UAPI headers.