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, u-blox UBX, and RTCM 3.x correction input, application protocols (CoAP, DNS, HTTP, and MQTT), PTP timing, a common diagnostics manager, BSD TCP/UDP networking, 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, a platform-neutral GPIO abstraction, a classic CAN bus abstraction over SocketCAN, Zephyr, and a mock backend, and an RPMsg device and endpoint abstraction over OpenAMP or a mock backend. 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/24Q/32/64, Fletcher-16/32/64, and XOR checksums for deterministic, non-cryptographic error detection. CRC-8 · CRC-16 · CRC-24Q · 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, Camellia-128/192/256, and SM4 block and CTR operations, RFC 8439 ChaCha20, streaming MD5, SHA-256, and SHA-512 hash primitives, and a repeating-key XOR cipher for obfuscation only. AES · ChaCha20 · MD5 · SHA-256 · SHA-512 · Camellia · SM4 · XOR |
| Diagnostics | Compile-time configured diagnostic_manager that qualifies fault conditions by update count or steady-clock duration, combines qualified faults into composite diagnostics, pauses selected monitors, and invokes a recovery callback once when a fault becomes active. It is polled from the application loop and creates no background task.Overview · Diagnostic manager |
| 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, fixed-capacity circular and polygon geofences, and fixed-depth Geohash encoding in base-32 and binary forms.Coordinates · Datums · Distance and bearing · Transforms · Geofences · Geohash · 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 |
| RTCM 3.x input | Encode-only RTCM 3 frame building for correction data sent to a u-blox GNSS receiver: frame header and CRC-24Q, an MSB-first bit writer, and observation, station, descriptor, and MSM message models. Frames are sent to the receiver port unchanged, and RTCM input is enabled with UBX configuration items. Specification · Framing · Bit writer · Message models · u-blox input mapping |
| CoAP | RFC 7252 datagram codec, a polling UDP client with bounded outstanding exchanges, retransmission and duplicate suppression, and a fixed-capacity resource server with exact Uri-Path dispatch. Overview · Types · Codec · Client · Server |
| DNS | Allocation-free stub resolver that queries over UDP, retries on timeout, falls back to TCP when a response is truncated, and reads address, CNAME, NS, and MX answers into fixed-capacity storage. Overview · Types · Message · Client |
| HTTP | Allocation-free HTTP/1.1 and HTTP/2 client with HPACK header compression, plus a fixed-capacity HTTP/1.1 server. Client and server I/O are driven by the application's poll() loop.Overview · HTTP/1.1 · HTTP/2 · HPACK · Client · Server |
| MQTT | Allocation-free MQTT client and single-process broker sharing one packet codec and topic matcher, with broker-side subscriptions, retained messages, and QoS 1/2 acknowledgements. Progress is made only through poll().Overview · Codec · Topic · Client · Broker |
| 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 |
| I/O: CAN | Platform-neutral basic_bus facade for classic CAN with frame, identifier/mask filter, can_config and bus_status, over Linux SocketCAN, Zephyr and mock backends selected at compile time; MCP2515 on SPI is supported through the Linux mcp251x driver or the Zephyr microchip,mcp2515 driver. CAN FD is out of scope.Overview · Frame · Filter · Types · Bus · Slot table · Mock · SocketCAN · Zephyr |
| I/O: RPMsg | Platform-neutral RPMsg device and endpoint facades with message, name_service and types, over an OpenAMP backend (enabled by CASTLE_RPMSG_ENABLE_OPENAMP) or an in-memory mock backend selected at compile time.Overview · Types · Message · Name service · Backend · Device · Endpoint · Umbrella · Mock · OpenAMP |
| Networking: TCP/UDP | Numeric IPv4/IPv6 endpoint, move-only tcp_socket/udp_socket over BSD sockets, tcp_client/udp_client with an inline receive callback, and fixed-capacity tcp_server/udp_server with generation-checked client handles and per-peer callbacks, without heap allocation.Overview · endpoint · socket · client · server |
| 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, and a stateless proportional servo that yields step or bounded ppb frequency corrections. PTP slave prototype · PTP servo |
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.