API: Introduce a new link/protocol metrics tracker

This patch exposes some metrics from LibOSDP which can be used to gauge
the quality of RS485 link and the state of the protocol for each PD.

These are intended to be used by products like OsprioMini and OsprioPro
will extract this data, mix it with other system metrics which are then
used create a dashboards which allow deployment health monitoring.

Signed-off-by: Siddharth Chandrasekaran <sidcha.dev@gmail.com>

Author: sidcha

configure.sh

@@ -170,7 +170,7 @@ fi
 
 ## Declare sources
 LIBOSDP_SOURCES+=" src/osdp_common.c src/osdp_phy.c src/osdp_sc.c src/osdp_file.c src/osdp_pd.c"
-LIBOSDP_SOURCES+=" src/osdp_cp.c"
+LIBOSDP_SOURCES+=" src/osdp_cp.c src/osdp_metrics.c"
 LIBOSDP_SOURCES+=" utils/src/list.c utils/src/queue.c utils/src/utils.c"
 LIBOSDP_SOURCES+=" utils/src/disjoint_set.c utils/src/crc16.c"
 if [[ -z "${LOG_MINIMAL}" ]]; then
@@ -187,6 +187,7 @@ TARGETS="cp_app pd_app"
 
 TEST_SOURCES="tests/unit-tests/test.c"
 TEST_SOURCES+=" tests/unit-tests/test-cp-phy.c"
+TEST_SOURCES+=" tests/unit-tests/test-pd-phy.c"
 TEST_SOURCES+=" tests/unit-tests/test-commands.c"
 TEST_SOURCES+=" tests/unit-tests/test-events.c"
 TEST_SOURCES+=" tests/unit-tests/test-cp-fsm.c"

include/osdp.h

@@ -1455,6 +1455,68 @@ void osdp_get_status_mask(const osdp_t *ctx, uint8_t *bitmask);
 OSDP_EXPORT
 void osdp_get_sc_status_mask(const osdp_t *ctx, uint8_t *bitmask);
 
+/**
+ * @brief Link/protocol health counters accumulated since the last
+ * @ref osdp_get_metrics() call.
+ *
+ * All counters saturate at their maximum value (no wraparound) and
+ * are reset to zero atomically when @ref osdp_get_metrics() returns
+ * a snapshot, giving callers interval-delta semantics without
+ * requiring subtraction.
+ */
+struct osdp_metrics {
+	/**
+	 * Packets transmitted successfully on the wire. Counted once
+	 * per @ref osdp_phy_send_packet() that reached the channel
+	 * driver with the full payload.
+	 */
+	uint32_t packets_sent;
+	/**
+	 * Packets received with a well-formed frame. Frames that failed
+	 * the CRC/checksum integrity check are still counted here; only
+	 * frames rejected earlier (bad SOM, bad length, bad direction
+	 * bit, etc.) are excluded.
+	 */
+	uint32_t packets_received;
+	/**
+	 * Inbound frames rejected at the integrity-check stage. Merged
+	 * counter across CRC-16 and single-byte checksum failures — the
+	 * check used is implicit in the negotiated capability.
+	 */
+	uint32_t packet_check_errors;
+	/**
+	 * REPLY_NAK packets observed on this context. On a PD-mode
+	 * context these are NAKs transmitted; on a CP-mode context
+	 * these are NAKs received. Direction is implicit from the role.
+	 */
+	uint32_t nak_count;
+	/** Successful secure-channel activations (post-SCRYPT). */
+	uint32_t sc_handshake_count;
+	/** Secure-channel tear-downs of a previously active session. */
+	uint32_t sc_failure_count;
+	/** Commands processed at the application callback boundary. */
+	uint32_t command_count;
+	/** Events dispatched to the application callback. */
+	uint32_t event_count;
+};
+
+/**
+ * @brief Read and reset link/protocol health counters for one PD slot.
+ *
+ * Counters are tracked per-PD. In PD mode there is only one slot
+ * (pd_idx == 0). In CP mode pass the index of the downstream PD to
+ * snapshot; callers typically iterate 0..NUM_PD-1.
+ *
+ * @param ctx OSDP context
+ * @param pd_idx PD index to snapshot (0..NUM_PD-1)
+ * @param out Destination struct filled with the current counter values.
+ *            The counters for this PD are then cleared to zero.
+ *
+ * @retval 0 on success, -1 on invalid arguments.
+ */
+OSDP_EXPORT
+int osdp_get_metrics(osdp_t *ctx, int pd_idx, struct osdp_metrics *out);
+
 /**
  * @brief Open a pre-agreed file
  *

include/osdp.hpp

@@ -62,6 +62,11 @@ class OSDP_EXPORT Common {
 		return osdp_get_file_tx_status(_ctx, pd, size, offset);
 	}
 
+	int get_metrics(int pd, struct osdp_metrics *metrics)
+	{
+		return osdp_get_metrics(_ctx, pd, metrics);
+	}
+
 protected:
 	osdp_t *_ctx;
 };

python/osdp/control_panel.py

@@ -194,6 +194,11 @@ def get_file_tx_status(self, address):
         with self.lock:
             return self.ctx.get_file_tx_status(pd)
 
+    def get_metrics(self, address):
+        pd = self.pd_addr.index(address)
+        with self.lock:
+            return self.ctx.get_metrics(pd)
+
     def start(self):
         if self.thread:
             raise RuntimeError("Thread already running!")

python/osdp/peripheral_device.py

@@ -123,6 +123,10 @@ def get_file_tx_status(self):
         with self.lock:
             return self.ctx.get_file_tx_status(0)
 
+    def get_metrics(self):
+        with self.lock:
+            return self.ctx.get_metrics(0)
+
     def stop(self):
         if not self.thread:
             raise RuntimeError("Thread not running!")

python/osdp_sys/base.c

@@ -138,6 +138,46 @@ static PyObject *pyosdp_get_file_tx_status(pyosdp_base_t *self, PyObject *args)
 	return dict;
 }
 
+#define pyosdp_get_metrics_doc                                                    \
+	"Get and reset link/protocol metrics for a PD slot\n"                     \
+	"\n"                                                                      \
+	"@return dictionary with metric counters or None on invalid PD index.\n"
+static PyObject *pyosdp_get_metrics(pyosdp_base_t *self, PyObject *args)
+{
+	int pd_idx;
+	osdp_t *ctx;
+	struct osdp_metrics metrics;
+	PyObject *dict;
+	pyosdp_cp_t *cp = (pyosdp_cp_t *)self;
+	pyosdp_pd_t *pd = (pyosdp_pd_t *)self;
+
+	ctx = self->is_cp ? cp->ctx : pd->ctx;
+
+	if (!PyArg_ParseTuple(args, "I", &pd_idx))
+		Py_RETURN_NONE;
+
+	if (osdp_get_metrics(ctx, pd_idx, &metrics))
+		Py_RETURN_NONE;
+
+	dict = PyDict_New();
+	if (dict == NULL)
+		Py_RETURN_NONE;
+
+	if (pyosdp_dict_add_int(dict, "packets_sent", metrics.packets_sent) ||
+	    pyosdp_dict_add_int(dict, "packets_received", metrics.packets_received) ||
+	    pyosdp_dict_add_int(dict, "packet_check_errors", metrics.packet_check_errors) ||
+	    pyosdp_dict_add_int(dict, "nak_count", metrics.nak_count) ||
+	    pyosdp_dict_add_int(dict, "sc_handshake_count", metrics.sc_handshake_count) ||
+	    pyosdp_dict_add_int(dict, "sc_failure_count", metrics.sc_failure_count) ||
+	    pyosdp_dict_add_int(dict, "command_count", metrics.command_count) ||
+	    pyosdp_dict_add_int(dict, "event_count", metrics.event_count)) {
+		Py_DECREF(dict);
+		Py_RETURN_NONE;
+	}
+
+	return dict;
+}
+
 #define pyosdp_file_register_ops_doc                                           \
 	"Register file OPs handler\n"                                          \
 	"\n"                                                                   \
@@ -261,6 +301,8 @@ static PyMethodDef pyosdp_base_methods[] = {
 	  pyosdp_file_register_ops_doc },
 	{ "get_file_tx_status", (PyCFunction)pyosdp_get_file_tx_status, METH_VARARGS,
 	  pyosdp_file_tx_status_doc },
+	{ "get_metrics", (PyCFunction)pyosdp_get_metrics, METH_VARARGS,
+	  pyosdp_get_metrics_doc },
 	{ NULL } /* Sentinel */
 };
 

python/setup.py

@@ -132,6 +132,7 @@ def try_vendor_sources(src_dir, src_files, vendor_dir):
     "src/osdp_file.c",
     "src/osdp_pd.c",
     "src/osdp_cp.c",
+    "src/osdp_metrics.c",
     "src/crypto/tinyaes_src.c",
     "src/crypto/tinyaes.c",
 ]
@@ -141,6 +142,7 @@ def try_vendor_sources(src_dir, src_files, vendor_dir):
     "include/osdp_export.h",
     "src/osdp_common.h",
     "src/osdp_file.h",
+    "src/osdp_metrics.h",
     "src/crypto/tinyaes_src.h",
 ]
 

src/CMakeLists.txt

@@ -56,6 +56,7 @@ list(APPEND LIB_OSDP_SOURCES
 	${CMAKE_CURRENT_SOURCE_DIR}/osdp_cp.c
 	${CMAKE_CURRENT_SOURCE_DIR}/osdp_sc.c
 	${CMAKE_CURRENT_SOURCE_DIR}/osdp_file.c
+	${CMAKE_CURRENT_SOURCE_DIR}/osdp_metrics.c
 )
 
 if (OPT_OSDP_PACKET_TRACE OR OPT_OSDP_DATA_TRACE)

src/osdp_common.h

@@ -10,6 +10,7 @@
 #include <assert.h>
 #include <stddef.h>
 #include <stdbool.h>
+#include <stdint.h>
 #include <string.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -463,6 +464,7 @@ struct osdp_pd {
 
 	struct osdp_secure_channel sc;   /* Secure Channel session context */
 	struct osdp_file *file;          /* File transfer context */
+	struct osdp_metrics metrics;     /* link/protocol health counters */
 
 	/* PD command callback to app with opaque arg pointer as passed by app */
 	void *command_callback_arg;

src/osdp_cp.c

@@ -9,6 +9,7 @@
 #include "osdp_common.h"
 #include "osdp_file.h"
 #include "osdp_diag.h"
+#include "osdp_metrics.h"
 
 #define CMD_POLL_LEN                   1
 #define CMD_LSTAT_LEN                  1
@@ -62,6 +63,7 @@ static void cp_dispatch_event(struct osdp_pd *pd,
 	if (ctx->event_callback) {
 		ctx->event_callback(ctx->event_callback_arg, pd->idx,
 				    (struct osdp_event *)event);
+		osdp_metrics_report(pd, OSDP_METRIC_EVENT);
 	}
 }
 
@@ -380,6 +382,7 @@ static int cp_decode_response(struct osdp_pd *pd, uint8_t *buf, int len)
 		if (len != REPLY_NAK_DATA_LEN) {
 			break;
 		}
+		osdp_metrics_report(pd, OSDP_METRIC_NAK);
 		if (buf[pos] == OSDP_PD_NAK_MSG_CHK &&
 		    ISSET_FLAG(pd, PD_FLAG_CP_USE_CRC)) {
 			LOG_INF("PD NAK'd CRC-16, falling back to checksum");
@@ -595,6 +598,7 @@ static int cp_decode_response(struct osdp_pd *pd, uint8_t *buf, int len)
 		osdp_compute_session_keys(pd);
 		if (osdp_verify_pd_cryptogram(pd) != 0) {
 			LOG_ERR("Failed to verify PD cryptogram");
+			osdp_metrics_report(pd, OSDP_METRIC_SC_FAILURE);
 			return OSDP_CP_ERR_APP;
 		}
 		ret = OSDP_CP_ERR_NONE;
@@ -667,6 +671,7 @@ static int cp_build_and_send_packet(struct osdp_pd *pd)
 		return OSDP_CP_ERR_GENERIC;
 	}
 
+	osdp_metrics_report(pd, OSDP_METRIC_COMMAND);
 	return OSDP_CP_ERR_NONE;
 }
 
@@ -954,6 +959,7 @@ static void notify_pd_status(struct osdp_pd *pd, bool is_online)
 	evt.notif.type = OSDP_EVENT_NOTIFICATION_PD_STATUS;
 	evt.notif.arg0 = is_online;
 	ctx->event_callback(ctx->event_callback_arg, pd->idx, &evt);
+	osdp_metrics_report(pd, OSDP_METRIC_EVENT);
 }
 
 static void notify_sc_status(struct osdp_pd *pd)
@@ -970,6 +976,7 @@ static void notify_sc_status(struct osdp_pd *pd)
 	evt.notif.arg0 = sc_is_active(pd);
 	evt.notif.arg1 = sc_use_scbkd(pd);
 	ctx->event_callback(ctx->event_callback_arg, pd->idx, &evt);
+	osdp_metrics_report(pd, OSDP_METRIC_EVENT);
 }
 
 static void cp_keyset_complete(struct osdp_pd *pd)
@@ -1097,6 +1104,7 @@ static enum osdp_cp_state_e get_next_ok_state(struct osdp_pd *pd)
 		}
 		return OSDP_CP_STATE_ONLINE;
 	case OSDP_CP_STATE_SC_CHLNG:
+		osdp_metrics_report(pd, OSDP_METRIC_SC_HANDSHAKE);
 		return OSDP_CP_STATE_SC_SCRYPT;
 	case OSDP_CP_STATE_SC_SCRYPT:
 		sc_activate(pd);
@@ -1271,6 +1279,7 @@ static void notify_command_status(struct osdp_pd *pd, int status)
 	evt.notif.arg1 = status;
 
 	ctx->event_callback(ctx->event_callback_arg, pd->idx, &evt);
+	osdp_metrics_report(pd, OSDP_METRIC_EVENT);
 }
 
 static int state_update(struct osdp_pd *pd)