LibOSPD v4.0 Release Plan

[sidcha]

A lot of things have changed in LibOSDP in preparation for a major release. The following things have to be documented. This issue will track all those topics as a todo list before making the major release.

v4.0 breaking / behavior-changing items (API & protocol)

• App-owned queue data (b5823c0) OPT_OSDP_APP_OWNED_QUEUE_DATA is gone — always-on. Apps that submit queued payloads must now register osdp_cp_set_command_completion_callback / osdp_pd_set_event_completion_callback.
• Single channel per OSDP context (04a0851) osdp_cp_setup() / osdp_pd_setup() take a struct osdp_channel * argument. channel removed from osdp_pd_info_t; id removed from struct osdp_channel. Multi-bus deployments must create one osdp_t per channel.
• Retire inline MFGREP support (34cda90) Positive return from pd_command_callback_t for OSDP_CMD_MFG is no longer honored as an inline MFGREP. pd_command_callback_t contract is now 0 = ACK, -ve = NAK, +ve reserved. MFGREP must be emitted asynchronously via osdp_pd_submit_event().
• File-transfer completion is notification-driven (f0990cd) Querying file-transfer status now advances the FSM to idle on terminal states. Callers must consume the new OSDP_NOTIFICATION_FILE_TX_DONE (payload enum osdp_file_tx_outcome) to learn the outcome.
• osdp_event_notification renamed to osdp_notification (dfbf978) — the struct is shared by CP events and PD commands, so the event_ prefix was misleading. Enum type and enumerators were also renamed: enum osdp_event_notification_type → enum osdp_notification_type, and OSDP_EVENT_NOTIFICATION_* → OSDP_NOTIFICATION_* (the EVENT_ infix is dropped).
• PD-mode notifications now fire the command callback (c07d953) — OSDP_FLAG_ENABLE_NOTIFICATION was previously a PD no-op. It now delivers link / SC transitions via pd_command_callback_t wrapped in osdp_cmd with id OSDP_CMD_NOTIFICATION. PD apps that set the flag must handle or ignore the new command id.
• OSDP_NOTIFICATION_COMMAND.arg1 semantics (c01cc92) Changed from 1 = success, 0 = failure (bool-as-int) to the documented 0 = success, -1 = failure. Consumers comparing against the old values read every success as a failure (caught the pytest suite).
• Log callback signature changed (e506db6) — osdp_log_callback_fn_t gained a leading int pd argument: (int pd, int log_level, ...). Every osdp_set_log_callback() consumer must update its callback signature. Silent break (compiles with a warning at best); rides in the same commit as minimal-logger mode.
• PD online/offline tracking + OSDP_NOTIFICATION_PD_STATUS (dfbf978 enum, 756046a behavior) — PD now derives online/offline from CP link activity and emits a third notification type, OSDP_NOTIFICATION_PD_STATUS (governed by OSDP_PD_ONLINE_TOUT_MS). Extends the c07d953 item beyond link/SC transitions.
• Adaptive CRC/Checksum handling along with strict capabilities based check-character gating
• A more complete/compliant sequence-repeat reply-resend handling; Fixes in spirit Add support for sequence repeat (CP) and reply resend (PD) features #41 (71556a6, 0d229b5, 333bb9b, 78b2357)
• Fix a plethora of multi-drop issues (b892a91, 0bf084d, a93deec, 7764466, 5d8296a, 810d33d, 3214e90, 37580a6)

Build, packaging & platform

• Public headers install under include/libosdp/ (03e159b; cmake 5436dd3, 6c9344a, 6c8b0c5) — installed consumers must switch #include <osdp.h> → #include <libosdp/osdp.h>. pkg-config Cflags and find_package(libosdp) were updated to match; README documents find_package consumption (CMake ≥ 3.14).
• Crypto backend selection (7f4eea5, 3cbe8e0, 6c8b0c5) — --crypto / OPT_OSDP_CRYPTO_BACKEND now takes auto|openssl|mbedtls|tinyaes, default auto (probes openssl → mbedtls → tinyaes). TinyAES is now bundled in-tree. Behavior change: a build that specifies no backend now auto-selects a system lib instead of falling back to TinyAES-with-warning.
• Windows / MSVC build support (3a7176e, 862b8bc, c8fce4e, f795700, b65ce5e, 20bbbab, deff403) — libosdp now builds cross-platform on Windows/MSVC; new --lib-only flag for that path.
• Python: dropped EOL Python 3.8 (5f45087) — minimum supported Python raised for wheel builds.

New features that need explicit documentation or callouts

• Zero-copy RX (772ba9e) OPT_OSDP_RX_ZERO_COPY is a compile-time switch, no fallback. The old buffered osdp_read_fn_t path is removed in zero-copy builds. Python bindings do not support zero-copy builds.
• Static CP builds (19596c9) --static-pd / OPT_OSDP_STATIC_PD renamed to --static / OPT_OSDP_STATIC (old names kept as deprecated aliases). Static builds now include CP, not just PD. Downstream build systems referencing the old preprocessor symbol must update.
• tick_t and its width (c23e05e) Internal timestamps and osdp_millis_now() / osdp_millis_since() switched from int64_t to tick_t. New build flags --bare-metal and --use-32bit-tick-t (requires --bare-metal) let embedded targets opt into a 32-bit tick. Bare-metal apps that override the __weak osdp_millis_now() must change their return type to tick_t.
• Minimal logger mode (e506db6) Opt-in mode where libosdp skips filtering/formatting and hands logs to the app as-is, with a static logger context (lower RAM). Useful for apps that already have a host logging subsystem.
• Link/protocol metrics API (61fbe31) — new exported int osdp_get_metrics(osdp_t *ctx, int pd_idx, struct osdp_metrics *out) plus public struct osdp_metrics. The only net-new exported function in this release.
• Security: secure-channel keys zeroized at function exit (b281fee) — hardening; worth a dedicated security line in the changelog.

Minor / housekeeping

• C++ header sync + constness fixes (52abc71, e600d30) — may affect strict C++ consumers of osdp.hpp.
• Static pools overlaid when role is exclusive (8d7a243) — memory refinement under OPT_OSDP_STATIC; sub-note to the static-build item.
• CHANGELOG migrated to split per-file format (3fd5b15) — maintenance/process note.