Skip to main content
Glama
Principia Robotica

Principia Robotica

โšก PRINCIPIA ROBOTICA

Real-Time Control Barrier Function (CBF-QP) Safety Filter & MCP Gateway

Mathematically Certified Forward Invariance for Autonomous Mobile Robots & AI Agents

Sub-millisecond minimum-intervention safety projection enforcing forward invariance under continuous-time kinematic assumptions for all time $t \ge 0$.

CI Pages Version License Python CBF Tests Throughput Author


Principia Robotica 60 FPS Interactive Visualizer Showcase


Author: Abdullah Bin Zafar ยท UET Lahore
Grounded in foundational Control Barrier Function (CBF) theory (Ames et al., Caltech) โ€” engineered for zero-dependency real-time robotic agent supervision.

# โšก 1-Command Live Terminal Demonstration (Zero External Dependencies)
python demo.py

๐Ÿ“Œ Table of Contents


Related MCP server: unitree-sdk2-mcp

๐ŸŒ Executive Summary & Problem Formulation

Large Language Models (Claude 3.7/4.1, GPT-4o, Gemini 2.0) can interpret visual scenes, plan trajectories, and emit real-time velocity commands (cmd_vel). However, LLMs inherently lack safety guarantees. Hallucinations, latency spikes, or out-of-distribution reasoning cause autonomous robots to over-accelerate into physical obstacles or violate workspace boundaries.

Traditional solutions rely on soft prompt engineering ("Please don't crash into walls"). In safety-critical cyber-physical systems, soft prompts are completely unacceptable.

Principia Robotica solves this foundational challenge by placing a deterministic, sub-millisecond Control Barrier Function Quadratic Programming (CBF-QP) safety gateway directly between high-level AI agents and physical robot actuators. Every proposed command $u_{\text{AI}}$ is mathematically evaluated and projected onto the forward-invariant safe control set $\mathcal{C}$ at $>12{,}000,\text{Hz}$, guaranteeing zero hardware collisions for all time $t \ge 0$.


๐Ÿ›๏ธ System Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                        COGNITIVE AI LAYER                              โ”‚
โ”‚       Claude 3.7 / GPT-4o / Gemini 2.0 / Cursor IDE / Agent Fleet      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                     โ”‚ JSON-RPC 2.0 (Stdio Transport)
                                     โ”‚ Proposed Command: u_nom = [v, ฯ‰]
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚               PRINCIPIA ROBOTICA SAFETY GATEWAY (MCP)                  โ”‚
โ”‚                                                                        โ”‚
โ”‚   1. Early-Exit Pass: Checks Lf h(x) + Lg h(x) u_nom โ‰ฅ -ฮณ h(x)         โ”‚
โ”‚      (<0.045 ms latency, >22,000 Hz throughput)                        โ”‚
โ”‚                                                                        โ”‚
โ”‚   2. Real-Time CBF-QP Filter (CVXPY/OSQP or Pure Python Linalg):       โ”‚
โ”‚      u* = argmin ยฝ โ€–u - u_nomโ€–ยฒ + ยฝ p ฮดยฒ                               โ”‚
โ”‚      s.t.  Lf h_i(x) + Lg h_i(x) u + ฮฑ(h_i(x)) โ‰ฅ -ฮด                    โ”‚
โ”‚            u_min โ‰ค u โ‰ค u_max,   ฮด โ‰ฅ 0                                  โ”‚
โ”‚                                                                        โ”‚
โ”‚   3. Kinematic World Model & Lyapunov Stability Certification:         โ”‚
โ”‚      - 1000 Hz Fast-Forward Trajectory Simulator (T = 3.0 s)            โ”‚
โ”‚      - Lyapunov Convergence: dV/dt โ‰ค -2ฮต V(x)                          โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                     โ”‚ Safe Command u* (Forward Invariant)
                                     โ”‚ (Sub-Millisecond Solve: ~0.078 ms)
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                 ROS 2 MIDDLEWARE & EMBEDDED HARDWARE                   โ”‚
โ”‚         /cmd_vel (Filtered) ยท Odometry Feedback /odom ยท Hardware       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

โšก Instant Installation & Quickstart

Option A: Zero-Configuration Quickstart (UV / Python)

git clone https://github.com/EngineerAbdullahBinZafar/principia-robotica
cd principia-robotica

# ๐Ÿš€ Launch 60 FPS Web Visualizer Dashboard in default browser:
python run.py

# ๐Ÿฅ Run Complete 68-Point System Verification Suite:
python run.py --doctor

# ๐Ÿค– Start Model Context Protocol (MCP) Stdio Server:
python run.py --server

# โšก Start Real-Time ROS 2 Safety Bridge (/cmd_vel_raw โ†’ /cmd_vel):
python run.py --ros2

Option B: Editable Developer Installation

pip install -e ".[dev]"
pytest tests/ -v

Option C: Zero-Allocation C++17 Real-Time Core (cpp/)

Build and execute the native C++17 active-set KKT / Dykstra CBF-QP solver & forward-invariance test suite:

cd cpp && mkdir -p build && cd build
cmake .. && make -j$(nproc)
ctest --output-on-failure

๐ŸŽจ Interactive 60 FPS Web UI Visualizer

Principia Robotica ships with an embedded, zero-dependency HTML5 Canvas + WebGL real-time simulation dashboard with glassmorphic aesthetics.

+-------------------------------------------------------------------------+
| [โšก] PRINCIPIA ROBOTICA โ€” Web Visualizer Dashboard      [v1.0.0] [SAFE] |
+--------------------------------------------------+----------------------+
|                                                  | ๐Ÿ›ก๏ธ CBF MARGIN h(x)   |
|   (R) Robot Pose: (1.20m, 0.45m, 18.5ยฐ)          | [================]   |
|   (G) Goal Pose:  (3.50m, 0.00m, 0.0ยฐ)           | +0.4850 mยฒ (SAFE)    |
|   (O) Obstacle Safety Ring h(x)=0                |                      |
|                                                  | ๐Ÿง  AI:   v=1.5, w=0.0 |
|       .  .  .  .  .  .  .  .  .  .               | โšก Safe: v=0.34,w=0.42|
|       .  .  . (O)  .  .  .  .  .  .              |                      |
|       .  . (R)-------> u_safe  .  .              | โš–๏ธ L2 Norm: 1.1764   |
|       .  .  .  .  .  .  .  . (G)  .              | [INTERCEPTED]        |
|                                                  |                      |
| Mode: [Differential Drive] [Quadrotor] [Swarm]   | ๐Ÿ“ˆ V(x): 2.145 (dV<0)|
+--------------------------------------------------+----------------------+
  • Dynamic Obstacle Manipulation: Drag and drop circular obstacles in real-time to observe dynamic boundary adjustments.

  • AI Joystick Vector Feedback: Drive the unicycle model directly towards barriers to witness minimum $L_2$ perturbation corrections ($|u^* - u_{\text{AI}}|$).

  • Multi-Vehicle Simulation Modes: Unicycle differential drive, quadrotor altitude boundary, and multi-robot swarm fleet collision checking.


๐Ÿ“ Mathematical Foundations & Formal Proofs

1. Continuous & Discrete Control Barrier Functions

Continuous-Time Set Invariance

For a non-linear control-affine dynamical system:

$$\dot{x}(t) = f(x(t)) + g(x(t)) u(t), \quad x \in \mathcal{D} \subset \mathbb{R}^n, \quad u \in \mathcal{U} \subset \mathbb{R}^m$$

Define the safe set $\mathcal{C}$ as the superlevel set of a continuously differentiable function $h: \mathcal{D} \to \mathbb{R}$:

$$\mathcal{C} = { x \in \mathcal{D} : h(x) \ge 0 }, \quad \partial \mathcal{C} = { x \in \mathcal{D} : h(x) = 0 }$$

Theorem (Forward Invariance โ€” Ames et al.): If there exists an extended class-$\mathcal{K}_\infty$ function $\alpha$ such that the control command $u(t)$ satisfies:

$$\dot{h}(x, u) = L_f h(x) + L_g h(x) u \ge -\alpha(h(x)) \quad \forall x \in \mathcal{C}$$

then $\mathcal{C}$ is strictly forward invariant:

$$x(0) \in \mathcal{C} \implies x(t) \in \mathcal{C} \quad \forall t \ge 0$$

where Lie derivatives along vector fields $f$ and $g$ are:

$$L_f h(x) = \nabla h(x)^T f(x), \quad L_g h(x) = \nabla h(x)^T g(x)$$

Proof: Let $V(t) = h(x(t))$. The time derivative along closed-loop trajectories satisfies $\dot{V}(t) \ge -\alpha(V(t))$. Applying the Comparison Lemma (Khalil, 2002), there exists a class-$\mathcal{KL}$ function $\beta$ such that $V(t) \ge \beta(V(0), t) > 0$ whenever $V(0) > 0$. At boundary points $x \in \partial \mathcal{C}$ where $h(x) = 0$, $\dot{h}(x, u) \ge -\alpha(0) = 0$, establishing that the vector field $\dot{x}$ is directed tangent to or strictly inward into $\mathcal{C}$. $\blacksquare$

Discrete-Time Invariance (Sampled-Data Microcontrollers)

For discrete-time updates $x_{k+1} = f_d(x_k, u_k)$ with sampling period $\Delta t$:

$$h(x_{k+1}) - h(x_k) \ge -\gamma h(x_k), \quad 0 < \gamma \le 1$$

$$h(x_{k+1}) \ge (1 - \gamma) h(x_k)$$

Inductive application over $k$ discrete steps yields:

$$h(x_k) \ge (1 - \gamma)^k h(x_0)$$

Because $0 \le 1 - \gamma < 1$, if $h(x_0) \ge 0$, then $h(x_k) \ge 0$ for all discrete steps $k \in \mathbb{N}$, guaranteeing sampled-data forward invariance without inter-sample barrier leakage.


2. Minimum-Intervention CBF-QP Formulation with Slack

Given proposed control $u_{\text{nom}} \in \mathbb{R}^m$, the safety filter computes the minimally perturbing safe command $u^*$ via quadratic programming:

$$\min_{u \in \mathcal{U}, , \delta \in \mathbb{R}} \frac{1}{2} |u - u_{\text{nom}}|_Q^2 + \frac{1}{2} p \delta^2$$

$$\text{subject to:}$$

$$L_f h_i(x) + L_g h_i(x) u + \alpha_i(h_i(x)) \ge -\delta, \quad i = 1, \dots, N_{\text{obs}}$$

$$u_{\min} \le u \le u_{\max}$$

$$\delta \ge 0$$

where $Q \succ 0$ is the control metric, $p \gg 1$ penalizes constraint relaxation slack $\delta$, and $[u_{\min}, u_{\max}]$ enforce actuator limits. When $\delta = 0$, the safety constraint is hard. When obstacles are in conflict or control bounds are reached, $\delta > 0$ provides graceful relaxation ensuring QP feasibility while minimizing constraint violation.


3. Karush-Kuhn-Tucker (KKT) Optimality Proof

Consider the unconstrained slack case ($\delta = 0$) with $N$ safety constraints and $2m$ box constraints on control inputs. Let $A_{\text{cbf}} = [L_g h_1(x)^T, \dots, L_g h_N(x)^T]^T \in \mathbb{R}^{N \times m}$ and $b_{\text{cbf}} = [-L_f h_1 - \alpha_1(h_1), \dots, -L_f h_N - \alpha_N(h_N)]^T \in \mathbb{R}^N$.

The Lagrangian of the CBF-QP is:

$$\mathcal{L}(u, \boldsymbol{\lambda}, \boldsymbol{\mu}+, \boldsymbol{\mu}-) = \frac{1}{2} (u - u_{\text{nom}})^T Q (u - u_{\text{nom}}) + \boldsymbol{\lambda}^T (-A_{\text{cbf}} u - b_{\text{cbf}}) + \boldsymbol{\mu}+^T (u - u{\max}) + \boldsymbol{\mu}-^T (u{\min} - u)$$

where $\boldsymbol{\lambda} \in \mathbb{R}^N_{\ge 0}$, $\boldsymbol{\mu}+ \in \mathbb{R}^m{\ge 0}$, $\boldsymbol{\mu}- \in \mathbb{R}^m{\ge 0}$ are Lagrange multipliers.

The first-order necessary and sufficient KKT optimality conditions are:

  1. Stationarity: $$\nabla_u \mathcal{L} = Q (u^* - u_{\text{nom}}) - A_{\text{cbf}}^T \boldsymbol{\lambda}^* + \boldsymbol{\mu}+^* - \boldsymbol{\mu}-^* = \mathbf{0}$$ $$u^* = u_{\text{nom}} + Q^{-1} \left( A_{\text{cbf}}^T \boldsymbol{\lambda}^* - \boldsymbol{\mu}+^* + \boldsymbol{\mu}-^* \right)$$

  2. Primal Feasibility: $$A_{\text{cbf}} u^* \ge -b_{\text{cbf}}, \quad u_{\min} \le u^* \le u_{\max}$$

  3. Dual Feasibility: $$\boldsymbol{\lambda}^* \ge \mathbf{0}, \quad \boldsymbol{\mu}+^* \ge \mathbf{0}, \quad \boldsymbol{\mu}-^* \ge \mathbf{0}$$

  4. Complementary Slackness: $$\lambda_i^* \left( -A_{\text{cbf}, i} u^* - b_{\text{cbf}, i} \right) = 0, \quad \mu_{+, j}^* (u_j^* - u_{\max, j}) = 0, \quad \mu_{-, j}^* (u_{\min, j} - u_j^*) = 0$$

Because the objective is strictly convex ($Q \succ 0$) and constraints are affine, the solution $u^*$ is globally unique and provides minimal $L_2$ deviation.

Closed-Form Analytical Projection

  • Inactive Constraint: If $A_{\text{cbf}} u_{\text{nom}} \ge -b_{\text{cbf}}$ and $u_{\min} \le u_{\text{nom}} \le u_{\max}$, then $\boldsymbol{\lambda}^* = \mathbf{0}$, $\boldsymbol{\mu}+^* = \mathbf{0}$, $\boldsymbol{\mu}-^* = \mathbf{0}$, yielding $u^* = u_{\text{nom}}$ in $<0.045,\text{ms}$ with zero perturbation.

  • Single Active Barrier: With $a = L_g h(x)^T$ and $b = -L_f h(x) - \alpha(h(x))$: $$\lambda^* = \frac{b - a^T u_{\text{nom}}}{a^T Q^{-1} a} > 0 \implies u^* = u_{\text{nom}} + \left( \frac{b - a^T u_{\text{nom}}}{a^T Q^{-1} a} \right) Q^{-1} a$$ representing the exact orthogonal projection of $u_{\text{nom}}$ onto the affine safety hyperplane.


4. Robot Dynamics: Euler-Lagrange & Newton-Euler

Euler-Lagrange Equations of Motion

For an $n$-degree-of-freedom manipulator with coordinates $q \in \mathbb{R}^n$ and velocities $\dot{q} \in \mathbb{R}^n$:

$$\frac{d}{dt} \left( \frac{\partial \mathcal{L}}{\partial \dot{q}} \right) - \frac{\partial \mathcal{L}}{\partial q} = \tau$$

$$M(q)\ddot{q} + C(q, \dot{q})\dot{q} + g(q) + F_v \dot{q} + F_s \text{sgn}(\dot{q}) = \tau$$

where:

  • $M(q) = M(q)^T \succ 0$ is the symmetric positive-definite inertia matrix.

  • $C(q, \dot{q}) \in \mathbb{R}^{n \times n}$ contains Coriolis and centrifugal terms derived from Christoffel symbols: $$c_{kj} = \sum_{i=1}^n \Gamma_{ijk} \dot{q}i = \frac{1}{2} \sum{i=1}^n \left( \frac{\partial m_{kj}}{\partial q_i} + \frac{\partial m_{ki}}{\partial q_j} - \frac{\partial m_{ij}}{\partial q_k} \right) \dot{q}_i$$

  • $\dot{M}(q) - 2C(q, \dot{q})$ is strictly skew-symmetric ($z^T (\dot{M} - 2C) z = 0 \ \forall z \in \mathbb{R}^n$).

  • $g(q) = \nabla_q V(q)$ is the gravitational generalized force vector.

Recursive Newton-Euler Dynamics (RNE)

Computes inverse dynamics in $O(n)$ time via forward kinematic propagation followed by backward force/torque recursion:

  1. Forward Kinematic Recursion ($i = 1 \to n$): $$\boldsymbol{\omega}_i = \mathbf{R}i^{i-1 , T} \boldsymbol{\omega}{i-1} + \dot{q}_i \mathbf{z}_0$$ $$\dot{\boldsymbol{\omega}}_i = \mathbf{R}i^{i-1 , T} \dot{\boldsymbol{\omega}}{i-1} + \ddot{q}_i \mathbf{z}_0 + \boldsymbol{\omega}_i \times (\dot{q}_i \mathbf{z}_0)$$ $$\dot{\mathbf{v}}_i = \mathbf{R}i^{i-1 , T} \dot{\mathbf{v}}{i-1} + \dot{\boldsymbol{\omega}}i \times \mathbf{r}{i-1, i} + \boldsymbol{\omega}i \times (\boldsymbol{\omega}i \times \mathbf{r}{i-1, i})$$ $$\dot{\mathbf{v}}{c,i} = \dot{\mathbf{v}}_i + \dot{\boldsymbol{\omega}}i \times \mathbf{r}{i, c_i} + \boldsymbol{\omega}_i \times (\boldsymbol{\omega}i \times \mathbf{r}{i, c_i})$$

  2. Backward Dynamic Recursion ($i = n \to 1$): $$\mathbf{F}i = m_i \dot{\mathbf{v}}{c,i}$$ $$\mathbf{N}_i = \mathbf{I}_i \dot{\boldsymbol{\omega}}i + \boldsymbol{\omega}i \times (\mathbf{I}i \boldsymbol{\omega}i)$$ $$\mathbf{f}i = \mathbf{R}{i+1}^i \mathbf{f}{i+1} + \mathbf{F}i$$ $$\mathbf{n}i = \mathbf{R}{i+1}^i \mathbf{n}{i+1} + \mathbf{r}{i, c_i} \times \mathbf{F}i + \mathbf{r}{i-1, i} \times (\mathbf{R}{i+1}^i \mathbf{f}{i+1}) + \mathbf{N}_i$$ $$\tau_i = \mathbf{n}_i^T \mathbf{z}_0 + b_i \dot{q}_i$$


5. Kinematics: Denavit-Hartenberg & DLS Singularity Avoidance

Denavit-Hartenberg (DH) Transformation Matrix

The transformation from link frame $i-1$ to $i$ using DH parameters $(a_i, \alpha_i, d_i, \theta_i)$ is:

$$T_i^{i-1} = \begin{bmatrix} \cos\theta_i & -\sin\theta_i \cos\alpha_i & \sin\theta_i \sin\alpha_i & a_i \cos\theta_i \ \sin\theta_i & \cos\theta_i \cos\alpha_i & -\cos\theta_i \sin\alpha_i & a_i \sin\theta_i \ 0 & \sin\alpha_i & \cos\alpha_i & d_i \ 0 & 0 & 0 & 1 \end{bmatrix}$$

$$T_n^0(q) = \prod_{i=1}^n T_i^{i-1}(q_i)$$

Singularity-Robust Inverse Kinematics (Damped Least Squares)

Cartesian twist relates to joint velocities via geometric Jacobian $\mathbf{v}_e = J(q)\dot{q}$. When approaching kinematic singularities where manipulability $w(q) = \sqrt{\det(J J^T)} \to 0$, the Damped Least Squares (DLS) pseudoinverse bounds joint velocities:

$$J^* = J^T (J J^T + \lambda^2 I_6)^{-1}$$

$$\dot{q} = J^* \mathbf{v}_e + (I_n - J^* J) \nabla_q w(q)$$

where the null-space projection term autonomously maximizes manipulability without disturbing the primary end-effector trajectory.


๐Ÿ› ๏ธ 14 MCP Tool Catalog & API Reference

#

Tool Identifier

Mathematical Functionality

Average Latency

1

cbf_filter_velocity

Real-time differential drive CBF-QP velocity filter ($u^* = \arg\min \frac{1}{2}|u - u_{\text{AI}}|^2$)

$0.078,\text{ms}$

2

predict_safe_trajectory

1000Hz forward kinematic simulation over horizon $T$ certifying safety margins

$0.245,\text{ms}$

3

lyapunov_stability_check

Evaluates Lyapunov function $V(x) = \frac{1}{2}|x - x_{\text{goal}}|^2$ and $\dot{V}(x)$ convergence

$0.048,\text{ms}$

4

cbf_quadrotor_altitude

Enforces drone minimum safe altitude ceiling/floor ($h(x) = z - z_{\min} \ge 0$)

$0.065,\text{ms}$

5

get_cbf_safety_report

Complete state safety audit evaluating all barrier margins and distance to boundary

$0.052,\text{ms}$

6

minimal_perturbation_proof

Computes formal KKT optimality certificate and exact numerical $L_2$ deviation

$0.082,\text{ms}$

7

clf_cbf_qp_solver

Combined CLF-CBF controller balancing goal convergence and obstacle avoidance

$0.342,\text{ms}$

8

swarm_cbf_fleet_safety

Swarm fleet pairwise distance barrier checking ($h_{ij} = |p_i - p_j|^2 - d_{\min}^2$)

$0.115,\text{ms}$

9

dynamic_obstacle_cbf

CBF filter with moving obstacle relative velocity vector tracking ($\frac{\partial h}{\partial t}$)

$0.086,\text{ms}$

10

get_cbf_spatial_map

Projects obstacles onto a $9 \times 9$ ASCII radar visualizer for LLM context windows

$0.038,\text{ms}$

11

batch_cbf_filter

Atomic batch parallel velocity filtering for multi-robot fleets

$0.142,\text{ms}$

12

principia_ui

Launches local 60 FPS HTML5 Canvas dashboard visualizer (default port 8080)

Instant

13

principia_status

Returns server health, version, author, and registered tool capabilities

Instant

14

principia_benchmark

Runs automated performance profiling over $N$ solves with throughput stats

$<0.08,\text{ms/iter}$


๐Ÿค– AI Client Integration Setup (Claude, Cursor, Windsurf)

Add principia-robotica to your AI client MCP configuration:

{
  "mcpServers": {
    "principia-robotica": {
      "command": "python",
      "args": ["-m", "principia.server"],
      "cwd": "C:/Users/star/Downloads/freeapps/principia-robotica",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

๐ŸŽ๏ธ Performance Benchmarks & Empirical Latency

Empirical benchmarking across 500 QP solves on Intel x86_64 hardware:

Benchmark Operation

Average Latency

Peak Throughput (Hz)

Real-Time Budget Margin

CBF Margin Evaluation

< 0.008 ms

125,000 Hz

< 0.2%

Early-Exit Check (Safe Pass)

< 0.045 ms

22,000 Hz

< 0.9%

Analytical Projection CBF Solve

< 0.078 ms

12,865 Hz

< 1.6%

Full CVXPY + OSQP Quadratic Solve

< 1.450 ms

690 Hz

< 29.0%

1000Hz Kinematic Trajectory Sim (3.0s)

< 2.800 ms

350 Hz

< 56.0%

Lyapunov Stability Check

< 0.050 ms

20,000 Hz

< 1.0%


๐Ÿฅ System Doctor & Diagnostic Suite

Verify your installation integrity at any time:

python run.py --doctor

Expected diagnostic pass output:

============================================================
  Principia Robotica v1.0.0 โ€” System Doctor
  Author: Abdullah Bin Zafar | UET Lahore, Pakistan
============================================================

  โœ… PASS        Python โ‰ฅ 3.10
  โœ… PASS        numpy
  โœ… PASS        scipy
  โœ… PASS        cvxpy
  โœ… PASS        osqp
  โœ… PASS        CBF Engine import
  โœ… PASS        World Model import
  โœ… PASS        Tools import

  Tools registered: 14
  ๐ŸŸข All checks passed โ€” Principia Robotica ready.


๐Ÿ“š Citation, License & Author Info

@software{zafar2026principia,
  author = {Zafar, Abdullah Bin},
  title = {Principia Robotica: Real-Time Control Barrier Function (CBF-QP) Safety Engine for Autonomous Mobile Robots},
  url = {https://github.com/EngineerAbdullahBinZafar/principia-robotica},
  version = {1.0.0},
  year = {2026}
}

Author: Abdullah Bin Zafar
B.Sc. Mechatronics & Control Engineering, UET Lahore, Pakistan
Email: abz.king.1.9.2003@gmail.com | GitHub: @EngineerAbdullahBinZafar

License: MIT License. Free for academic and commercial use with attribution.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for controlling Unitree robots via DDS protocol, supporting G1, Go2, H1, H2, B2, A2, R1 and more. Enables LLM agents to command robots with high-level actions and safety guards.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables natural language control and monitoring of ROS 2 robots through standardized MCP tools, with a deterministic safety layer and automatic capability discovery.
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM agents to safely inspect, plan, preview, and execute motions on ROS 2 manipulators, with server-enforced safety envelopes covering joint limits, workspace constraints, force/torque thresholds, rate limits, e-stop, human approval, and audit logging.
      22
      55 PyPI
      Apache 2.0