Antigravity ROS 2 Robotics Plugin
<div align="center">
<p align="center">
<img src="assets/banner.png" alt="Antigravity ROS 2 Robotics Plugin β Native Antigravity IDE Plugin and Model Context Protocol Server with Real-Time Dashboard by Engineer Abdullah Bin Zafar" width="100%" />
</p>
<img src="assets/logo.svg" alt="Antigravity Robotics Plugin Logo" width="160" height="160" />
# Antigravity ROS 2 Robotics Plugin
### `antigravity-robotics-plugin` β’ v1.2.0
**Native Antigravity Plugin, Model Context Protocol (MCP) Server & Zero-G Aerospace Suite for ROS 2 Autonomous Robotics**
[](https://github.com/EngineerAbdullahBinZafar/antigravity-robotics-plugin/actions/workflows/ci.yml)
[](https://github.com/EngineerAbdullahBinZafar/antigravity-robotics-plugin)
[-00FFA3?style=for-the-badge&logo=pytest&logoColor=black)](tests/)
[](ros2_mcp/sandbox.py)
[](ros2_packages/)
[](LICENSE)
[](pyproject.toml)
<br/>
*Engineered by **[Abdullah Bin Zafar](https://github.com/EngineerAbdullahBinZafar)** β Lead Robotics & Autonomous Systems Architect*
</div>
---
## π Overview
`antigravity-robotics-plugin` is an enterprise-grade, native **Google Antigravity Plugin**, **Model Context Protocol (MCP)** server, and **Aerospace Zero-G Control Suite** engineered to connect autonomous AI agents directly to **ROS 2 (Robot Operating System 2)** environments, digital twin simulations, and physical robotic hardware across terrestrial and microgravity platforms.
It empowers Antigravity agents to inspect topics, tune PID control loops, stream 2D LiDAR pointclouds, monitor multi-robot fleets, and execute safe actuator commands protected by a mutex-guarded **3-Tier Command Sandbox**.
### π Complete Multi-Layer Robotics Architecture:
1. **AI-Agentic Mission Supervisor (Python MCP)**: 16 high-level MCP tools for automated diagnosis, safety checks, and telemetry control.
2. **Interactive Zero-G Web Dashboard Sidecar**: 4-tab aerospace control station docking right inside the Antigravity IDE Aux Pane (`sidecar://antigravity-robotics-plugin/dashboard/index.html`).
3. **C++ Lifecycle Node (`antigravity_core`)**: Mission-critical deterministic FSM (`Unconfigured` β‘οΈ `Inactive` β‘οΈ `Active` β‘οΈ `Finalized`) with a 250ms hardware watchdog.
4. **Native RViz2 Qt Panel Plugin (`antigravity_rviz_panel`)**: Desktop companion panel embedding Zero-G velocity gauges and E-STOP directly into desktop RViz2.
5. **Gazebo Harmonic Zero-G Simulation (`sim/`)**: Orbital microgravity world with 6-DOF thruster dynamics, celestial lighting, and obstacle docking courses.
---
## ποΈ Architectural Topology
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Google Antigravity IDE β
β β
β βββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββ β
β β Agentic Reasoning β β Interactive Web Dashboard β β
β β (Tools / Prompts / MCP) β β (Aux Pane Native Sidecar)β β
β βββββββββββββββ¬ββββββββββββββ ββββββββββββββββ²ββββββββββββββββ β
β β stdio (JSON-RPC 2.0) β SSE / WS (20-30Hz)β
βββββββββββββββββββΌββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββ
βΌ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββ
β antigravity-robotics-plugin (Native MCP Host) β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 3-Tier Command Sandbox Guard β β
β β [read_only] | [safe_write] (Default) | [full] β β
β β Mutex-guarded Audit Logger (threading.Lock) β β
β ββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ β
β β Safe Tool Invocation β
β βΌ β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 16 MCP Tools across 8 Robotics Domains β β
β β Topics β’ Nodes β’ Params β’ Diagnostics β’ PID β’ Trajectory β’ β β
β β Spatial LiDAR β’ Swarm Fleet Management β β
β ββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ β
β β β
β βββββββββββββββββββ΄ββββββββββββββββββ β
β βΌ βΌ β
β ββββββββββββββββββββββββββ ββββββββββββββββββββββββββ β
β β ROS2NativeInterface β β MockInterface β β
β β (rclpy / Hardware) β β (Deterministic Sim) β β
β βββββββββββββ¬βββββββββββββ ββββββββββββββββββββββββββ β
ββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ROS 2 Ecosystem & Physical Actuators β
β β
β βββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββ β
β β antigravity_core β β antigravity_rviz_panel β β
β β (C++ Lifecycle Controller)β β (Native RViz2 Qt Panel) β β
β β 250ms Watchdog & FSM β β Zero-G Gauges & E-STOP β β
β βββββββββββββββ¬ββββββββββββββ βββββββββββββββ²ββββββββββββββ β
β β /antigravity/thrust_cmd β /cmd_vel β
β βΌ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββ΄ββββββββββββββ β
β β Gazebo Harmonic Zero-G / Hardware Actuators β β
β β (6-DOF Thrusters, 360Β° LiDAR, High-G IMU) β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π¨ Zero-G Aerospace Color Palette & Ergonomics
Designed specifically for harsh lighting fluctuations, polarized visors, and high-vibration aerospace operations ($>7:1$ WCAG AAA Contrast Ratio):
| Role / Element | Token Name | Hex Code | Visual & Ergonomic Intent |
| :--- | :--- | :--- | :--- |
| **Main Surface** | Deep Space Charcoal | `#12131C` | Absorbs screen glare, minimizes eye strain under direct celestial glare |
| **Panel Surface**| Command Module Slate| `#1A1D29` | Structural separation of telemetry widgets without harsh white borders |
| **Card Border** | Avionics Frame | `#2A2F42` | High-definition card containment and structural contrast |
| **Nominal Active**| Neon Cyan | `#00F0FF` | Active feedback, nominal topic streaming, clear navigation corridors |
| **Caution / Alert**| Inertial Amber | `#FFB800` | Proximity alerts ($0.6\,\text{m}$β$1.5\,\text{m}$), gain limits, transient FSM states |
| **Critical Alarm**| Solar Flare Red | `#FF3366` | Emergency Stop (E-STOP), physical collision bounds, protanopia-safe |
| **Typography** | Vibration-Proof Silver | `#E2E8F0` | High-legibility silver-white eliminating blur under thruster vibrations |
---
## π‘οΈ 3-Tier Security Sandbox Guardrails
To prevent unintended actuation or dangerous physical hardware movement, all tool executions pass through the **Command Sandbox**:
| Sandbox Level | Permitted Operations | Guardrail Enforcement |
| :--- | :--- | :--- |
| `read_only` | `ping`, `system_diagnostics`, `list_topics`, `read_topic`, `list_nodes`, `get_node_info`, `get_parameter`, `get_pid_state`, `get_robot_snapshot`, `get_spatial_map`, `swarm_fleet_status` | **Zero hardware writes.** All `publish_topic`, `set_parameter`, and `tune_pid` calls are rejected with `SandboxBlockedError`. |
| `safe_write` *(Default)* | All read operations + strictly allowlisted topics (`/cmd_vel`, `/target_velocity`, `/led_state`, `/speaker_cmd`, `/arm_target_angle`) and parameters (`nav2_controller:max_vel_x`, etc.) | Any attempt to publish to unauthorized topics or change unverified parameters is audited and rejected via a thread-safe mutex audit logger (`threading.Lock`). |
| `full` | Unrestricted read/write access across all ROS 2 nodes and topics | Permitted **only** in simulation mode (`MockInterface`) or on verified isolated test benches. |
---
## π§° 16 Standard Robotics Tools & JSON-RPC Schemas
The plugin registers 16 deterministic MCP tools matching the 2024-11-05 Model Context Protocol specification:
| # | Domain | Tool Name | Parameters & Types | Default Level | Description |
|---|---|---|---|---|---|
| 1 | **System** | `ping` | *(none)* | `read_only` | Verifies MCP server connectivity, round-trip latency, and active node count. |
| 2 | **System** | `system_diagnostics` | *(none)* | `read_only` | Full robot health check: battery voltage/level, LiDAR status, IMU health, error list. |
| 3 | **Topics** | `list_topics` | *(none)* | `read_only` | Enumerate all active ROS 2 DDS topics and their message types. |
| 4 | **Topics** | `read_topic` | `topic`: str, `msg_type`: str (opt), `timeout_ms`: int (opt), `latched`: bool (opt) | `read_only` | Read the latest message payload and timestamp age from any topic. |
| 5 | **Topics** | `publish_topic` | `topic`: str, `msg_type`: str, `payload`: dict | `safe_write` | Publish structured JSON payloads to ROS 2 topics (allowlisted in `safe_write`). |
| 6 | **State** | `get_robot_snapshot` | *(none)* | `read_only` | Aggregated parallel snapshot of odometry, battery, IMU, cmd_vel, and health. |
| 7 | **Nodes** | `list_nodes` | *(none)* | `read_only` | List all discovered nodes in the computational graph with namespaces. |
| 8 | **Nodes** | `get_node_info` | `node_name`: str | `read_only` | Inspect subscribers, publishers, service servers, and action servers for a node. |
| 9 | **Parameters**| `get_parameter` | `node_name`: str, `param_name`: str | `read_only` | Query a runtime parameter value and type from a target node. |
| 10 | **Parameters**| `set_parameter` | `node_name`: str, `param_name`: str, `value`: any | `safe_write` | Update a runtime parameter value (strictly allowlisted in `safe_write`). |
| 11 | **Control** | `get_pid_state` | `node_name`: str, `kp_param`: str (opt), `ki_param`: str (opt), `kd_param`: str (opt) | `read_only` | Inspect active PID controller gains ($K_p, K_i, K_d$) and safety boundaries. |
| 12 | **Control** | `tune_pid` | `node_name`: str, `kp`: float (opt), `ki`: float (opt), `kd`: float (opt), param names (opt) | `safe_write` | Dynamically update controller gains with strict non-negative ($K \ge 0$) bounds validation. |
| 13 | **Kinematics**| `predict_trajectory` | `linear_x`: float, `angular_z`: float, `dt_sec`: float (opt, def 3.0), `time_step`: float (opt) | `read_only` | Pre-simulate robot trajectory in $1000\,\text{Hz}$ fast-forward simulation ($<0.1\,\text{ms}$ compute). |
| 14 | **Safety** | `predictive_safety_check` | `command_type`: str, `target`: str, `proposed_value`: any | `read_only` | Validate proposed commands against dynamic stability limits and return mathematical proof. |
| 15 | **Perception**| `get_spatial_map` | `scan_topic`: str (opt, def `"/scan"`), `grid_size`: int (opt, def 13), `max_range_m`: float (opt) | `read_only` | Converts 360Β° LiDAR pointclouds into a 2D ASCII spatial radar grid for LLMs. |
| 16 | **Fleet** | `swarm_fleet_status` | *(none)* | `read_only` | Scans multi-namespace ROS 2 graph (`/drone_1`, `/rover_2`, `/arm_3`) and aggregates fleet health. |
### JSON-RPC 2.0 Request & Response Schema Examples
#### Example 1: `tune_pid` (Control Tuning)
```json
// Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "tune_pid",
"params": {
"node_name": "nav2_controller",
"kp": 2.5,
"ki": 0.1,
"kd": 0.4
}
}
// Response
{
"jsonrpc": "2.0",
"id": 42,
"result": {
"status": "ok",
"applied": [
{"gain": "Kp", "value": 2.5, "status": "ok"},
{"gain": "Ki", "value": 0.1, "status": "ok"},
{"gain": "Kd", "value": 0.4, "status": "ok"}
],
"guidance": "Tuning order: (1) Increase Kp until oscillation begins, (2) Add Kd to damp oscillation, (3) Add Ki last to eliminate steady-state error."
}
}
```
#### Example 2: `get_spatial_map` (2D LiDAR ASCII Radar)
```json
// Request
{
"jsonrpc": "2.0",
"id": 43,
"method": "get_spatial_map",
"params": {
"scan_topic": "/scan",
"grid_size": 13,
"max_range_m": 3.5
}
}
// Response
{
"jsonrpc": "2.0",
"id": 43,
"result": {
"status": "success",
"spatial_grid_ascii": ".............\n.............\n.....***.....\n.............\n.............\n.............\n......R......\n.............\n.............\n.............\n.............\n.............\n.............",
"legend": {"R": "Robot Center (0,0)", "*": "Detected Obstacle", ".": "Clear Space"},
"obstacle_summary": {
"closest_obstacle_distance_m": 0.82,
"closest_obstacle_bearing_deg": 1.2,
"clearance_front_m": 0.82,
"clearance_left_m": 3.50,
"clearance_right_m": 3.50
},
"spatial_recommendation": "Obstacle detected ahead β suggest rotation"
}
}
```
---
## π₯οΈ Interactive Web Dashboard & Antigravity Aux Pane Sidecar
The plugin features a zero-external-dependency, zero-CDN Web Dashboard designed for real-time operation directly inside the Google Antigravity IDE Aux Pane:
### Direct Aux Pane Sidecar Link
```markdown
[ROS 2 Robotics Dashboard](sidecar://antigravity-robotics-plugin/dashboard/index.html)
```
### 4-Tab Interface Structure
1. **Tactile Drive & Radar (Tab 1):**
- Clickable tactile D-pad and arrow key bindings (`β β β β` and `Space` for brake).
- Speed profiles: Low ($0.2\,\text{m/s}$), Medium ($0.5\,\text{m/s}$), High ($1.0\,\text{m/s}$).
- 360Β° HTML5 Canvas LiDAR radar rendered at 30Hz with concentric distance range rings ($1.0\,\text{m}, 2.0\,\text{m}, 3.0\,\text{m}$).
- Orientation-agnostic geometric badges: `πΊ Obstacle Close (<1.0m)` and `π· Path Clear`.
2. **Sensors & Health (Tab 2):**
- Battery voltage, current draw, and state-of-charge (SoC) progress bar.
- 3D IMU artificial horizon displaying real-time Pitch, Roll, and Yaw angles.
- Diagnostic anomaly stream with one-click error clearing.
3. **Engineer Mode (Tab 3):**
- Active ROS 2 computational graph node monitor with namespace grouping.
- Live topic inspection modal with JSON payload formatting.
- Real-time PID gain calibration sliders ($K_p, K_i, K_d$) with hardware bounds checking.
4. **Activity Log (Tab 4):**
- Real-time timestamped event stream displaying tool calls, audit records, and telemetry warnings.
---
## π C++ Lifecycle Controller, RViz2 Qt Panel & Gazebo Zero-G Simulation
### C++ Lifecycle Controller (`antigravity_core`)
Implements `rclcpp_lifecycle::LifecycleNode` to provide deterministic state management:
- **Finite State Machine (FSM):**
$$\text{Unconfigured} \xrightarrow{\text{on\_configure}} \text{Inactive} \xrightarrow{\text{on\_activate}} \text{Active} \xrightarrow{\text{on\_deactivate}} \text{Inactive} \xrightarrow{\text{on\_cleanup}} \text{Unconfigured}$$
- **250ms Hardware Watchdog:** An internal $50\,\text{Hz}$ wall timer checks time elapsed since the last `/cmd_vel` command:
$$\Delta t_{\text{cmd}} = t_{\text{current}} - t_{\text{last\_cmd}} > 250\,\text{ms} \implies \mathbf{F}_{\text{thrust}} \leftarrow \mathbf{0}$$
- **Emergency Stop (E-STOP):** Subscribed to `/antigravity/estop`. When asserted (`data: true`), all thruster forces are instantly clamped to $0.0\,\text{N}$, neutralizing kinetic momentum.
### RViz2 Qt Panel Plugin (`antigravity_rviz_panel`)
A native desktop companion plugin derived from `rviz_common::Panel`:
- Registered in `plugin_description.xml` as `antigravity_rviz_panel/AntigravityTelemetryPanel`.
- Embedded dark-mode UI with linear/angular velocity readouts, D-pad directional drive buttons, and dedicated emergency E-STOP button.
- Direct publisher to `/cmd_vel` and subscriber to `/cmd_vel` feedback.
### Gazebo Harmonic Zero-G Simulation (`sim/`)
- World file: `sim/worlds/zero_g_orbit.sdf` setting gravity vector $\mathbf{g} = [0, 0, 0]^T\,\text{m/s}^2$.
- 6-DOF orbital craft model with omnidirectional thrusters and $360^\circ$ planar LiDAR.
- Launch pipeline: `sim/launch/zero_g_simulation.launch.py` coordinating Gazebo Harmonic, `ros_gz_bridge`, and `antigravity_lifecycle_controller`.
---
## π GitHub-Native LaTeX Mathematical Formulations
All mathematical equations are formatted using GitHub-native LaTeX (`$...$` for inline expressions and `$$...$$` for block equations) to render cleanly across all Markdown viewers:
### 1. Discrete PID Controller with Anti-Windup Clamping & Filtering
The continuous-time ideal PID control law for tracking error $e(t) = r(t) - y(t)$ is:
$$u(t) = K_p e(t) + K_i \int_0^t e(\tau) \, d\tau + K_d \frac{de(t)}{dt}$$
where $K_p \ge 0$, $K_i \ge 0$, and $K_d \ge 0$.
In discrete digital microcontroller implementations with sampling period $T_s$, derivative action is filtered by a first-order low-pass filter (filter time constant $T_f = \frac{1}{N \omega_c}$) to suppress high-frequency sensor noise. Using backward-difference discretization:
$$e[k] = r[k] - y[k]$$
$$P[k] = K_p e[k]$$
$$D[k] = \frac{T_f}{T_f + T_s} D[k-1] + \frac{K_d}{T_f + T_s} \left(e[k] - e[k-1]\right)$$
The unsaturated control command is:
$$v[k] = P[k] + I[k-1] + K_i T_s e[k] + D[k]$$
When actuator physical limits enforce saturation bounds $[u_{\min}, u_{\max}]$, the output applied to physical hardware is:
$$u[k] = \text{sat}(v[k], u_{\min}, u_{\max}) = \begin{cases}
u_{\max}, & v[k] > u_{\max} \\
v[k], & u_{\min} \le v[k] \le u_{\max} \\
u_{\min}, & v[k] < u_{\min}
\end{cases}$$
To prevent integrator windup, conditional clamping is applied:
$$I[k] = \begin{cases}
I[k-1], & \text{if } \left(v[k] > u_{\max} \land e[k] > 0\right) \lor \left(v[k] < u_{\min} \land e[k] < 0\right) \\
I[k-1] + K_i T_s e[k], & \text{otherwise}
\end{cases}$$
Pre-execution gain validation bounds each gain against platform safety thresholds:
$$K \in [K_{\min}, K_{\max}], \quad \forall K \in \{K_p, K_i, K_d\}, \quad K \ge 0$$
---
### 2. Non-Holonomic Unicycle Kinematics & Straight-Line Limit
For a non-holonomic mobile robot in $\text{SE}(2)$ with planar pose vector $\mathbf{x} = [x, y, \theta]^T \in \mathbb{R}^3$ driven by linear velocity $v(t)$ and angular velocity $\omega(t)$:
$$\begin{bmatrix} \dot{x}(t) \\ \dot{y}(t) \\ \dot{\theta}(t) \end{bmatrix} = \begin{bmatrix} \cos\theta(t) & 0 \\ \sin\theta(t) & 0 \\ 0 & 1 \end{bmatrix} \begin{bmatrix} v(t) \\ \omega(t) \end{bmatrix}$$
Assuming piecewise-constant velocity commands $(v, \omega)$ over simulation step $\Delta t$:
**Case 1: Turning Motion ($\|\omega\| \ge 10^{-6}\,\text{rad/s}$):**
The robot follows a circular arc of instantaneous radius of curvature $R = \frac{v}{\omega}$. Exact analytic integration yields:
$$\theta(t + \Delta t) = \theta(t) + \omega \Delta t$$
$$x(t + \Delta t) = x(t) + \frac{v}{\omega} \left( \sin(\theta(t) + \omega \Delta t) - \sin\theta(t) \right)$$
$$y(t + \Delta t) = y(t) - \frac{v}{\omega} \left( \cos(\theta(t) + \omega \Delta t) - \cos\theta(t) \right)$$
**Case 2: Pure Translation ($\|\omega\| < 10^{-6}\,\text{rad/s}$, Straight-Line Limit):**
Taking the analytical limit as $\omega \to 0$ via L'HΓ΄pital's rule:
$$\lim_{\omega \to 0} \frac{v}{\omega} \left(\sin(\theta + \omega \Delta t) - \sin\theta\right) = \lim_{\omega \to 0} \frac{v \Delta t \cos(\theta + \omega \Delta t)}{1} = v \cos\theta \Delta t$$
$$\lim_{\omega \to 0} -\frac{v}{\omega} \left(\cos(\theta + \omega \Delta t) - \cos\theta\right) = \lim_{\omega \to 0} \frac{v \Delta t \sin(\theta + \omega \Delta t)}{1} = v \sin\theta \Delta t$$
which avoids numerical division-by-zero singularities:
$$x(t + \Delta t) = x(t) + v \cos\theta(t) \Delta t$$
$$y(t + \Delta t) = y(t) + v \sin\theta(t) \Delta t$$
$$\theta(t + \Delta t) = \theta(t)$$
---
### 3. 1000Hz Fast-Forward Trajectory Preview & Time-To-Collision (TTC)
Simulated over a forward prediction horizon $T_{\text{horizon}} = N \Delta t$ with high-rate time step $\Delta t = 10^{-3}\,\text{s}$ ($1000\,\text{Hz}$ rate, $<0.1\,\text{ms}$ computational latency):
The Euclidean distance between the predicted robot path waypoint $\mathbf{p}_k = [x_k, y_k]^T$ and an obstacle $\mathbf{p}_{\text{obs}} = [o_x, o_y]^T$ with obstacle radius $r_{\text{obs}}$ and robot footprint radius $r_{\text{robot}}$ is:
$$d_k = \|\mathbf{p}_k - \mathbf{p}_{\text{obs}}\|_2 - (r_{\text{obs}} + r_{\text{robot}})$$
The critical Time-To-Collision ($\text{TTC}$) relative to minimum allowable safety distance $d_{\text{safe}}$ is:
$$\text{TTC} = \frac{d - d_{\text{safe}}}{\|\mathbf{v}\|}$$
More generally across the simulated discrete horizon:
$$\text{TTC} = \inf \left\{ t_k = k \Delta t : d_k \le d_{\text{safe}} \right\}$$
Dynamic safety admissibility requires the stopping distance $d_{\text{stop}}(v)$ to satisfy:
$$d_{\text{stop}}(v) = \frac{v^2}{2 a_{\max}} + v \tau_{\text{latency}} \le \min_{k} d_k$$
where $a_{\max}$ is the maximum available braking deceleration and $\tau_{\text{latency}}$ represents communication and motor response latency.
---
### 4. 2D LiDAR Polar-to-Cartesian SE(3) Transformations to ASCII Radar Grid
A 2D planar LiDAR emits $N$ laser beams across angular span $[\theta_{\min}, \theta_{\max}]$. For beam index $i \in \{0, \dots, N-1\}$ with measured range $r_i$:
$$\theta_i = \theta_{\min} + i \cdot \frac{\theta_{\max} - \theta_{\min}}{N - 1}$$
The point coordinates in sensor local coordinate frame $\mathcal{F}_S$ are:
$$\mathbf{p}_i^S = \begin{bmatrix} r_i \cos\theta_i \\ r_i \sin\theta_i \\ 0 \\ 1 \end{bmatrix}$$
Using homogeneous transformation matrices in $\text{SE}(3)$, the point is projected into the world frame $\mathcal{F}_W$ via the robot base link frame $\mathcal{F}_B$:
$$\mathbf{p}_i^W = \mathbf{T}_B^W \mathbf{T}_S^B \mathbf{p}_i^S$$
where:
$$\mathbf{T}_B^W = \begin{bmatrix}
\cos\theta_w & -\sin\theta_w & 0 & x_w \\
\sin\theta_w & \cos\theta_w & 0 & y_w \\
0 & 0 & 1 & z_w \\
0 & 0 & 0 & 1
\end{bmatrix}, \quad
\mathbf{T}_S^B = \begin{bmatrix}
\mathbf{R}_S^B & \mathbf{t}_S^B \\
\mathbf{0}_{1 \times 3} & 1
\end{bmatrix}$$
For the embedded 2D ASCII radar visualizer on a grid of dimension $G \times G$ ($G=13$) with center coordinate $c = \lfloor G / 2 \rfloor$ and maximum radar range $r_{\max}$:
$$g_x(i) = c - \text{round}\left( \frac{r_i}{r_{\max}} \cdot c \cdot \cos\theta_i \right)$$
$$g_y(i) = c - \text{round}\left( \frac{r_i}{r_{\max}} \cdot c \cdot \sin\theta_i \right)$$
A cell is marked as occupied (`*`) if $0.1\,\text{m} < r_i \le r_{\max}$ and $0 \le g_x, g_y < G$, with the robot marked at center $(c, c)$ (`R`) and clear space designated as (`.`).
---
## β‘ Quick Start & Usage
### 1. Installation
Install directly in your Python environment or Antigravity workspace:
```bash
git clone https://github.com/EngineerAbdullahBinZafar/antigravity-robotics-plugin.git
cd antigravity-robotics-plugin
pip install -e ".[dev,dashboard,rosbridge]"
```
### 2. Building ROS 2 C++ Packages (Humble / Jazzy)
```bash
# In your ROS 2 colcon workspace:
mkdir -p ~/ros2_ws/src
cp -r ros2_packages/* ~/ros2_ws/src/
cd ~/ros2_ws
colcon build --symlink-install
source install/setup.bash
```
### 3. Launch Gazebo Harmonic Zero-G Simulation
```bash
ros2 launch sim/launch/zero_g_simulation.launch.py
```
### 4. Launch Standalone Dashboard
```bash
python -m ros2_mcp.dashboard.server --port 8765
# Or via CLI alias:
ros2-mcp-dashboard --port 8765
```
### 5. Run Automated Test Suite
Execute the comprehensive 152-test verification suite:
```bash
pytest tests/ -v
```
---
## π§ͺ Verification & Benchmarks
The entire test suite executes with **100% success rate (152/152 passing)** across 8 specialized verification harnesses:
* `test_plugin_manifest.py`: Validates `plugin.json`, `mcp_config.json`, assets, and Antigravity schema compliance.
* `test_server.py`: Validates all 16 tool handlers, parameter validation, and JSON-RPC hygiene.
* `test_dashboard_api.py`: Validates REST API endpoints, topic routing, and telemetry streams.
* `test_live_ws_stress_m2.py`: Real-time stress tests verifying 20Hz sustained streaming across concurrent clients.
* `test_adversarial_m1.py` & `test_adversarial_m2.py`: Adversarial safety penetration tests, ungraceful socket teardowns, and directory traversal immunity.
* `test_adversarial_stress_m2.py`: Concurrency and rapid connect/disconnect churn tests.
* `test_empirical_benchmarks.py`: P95 latency benchmarks (<30ms connect latency, <5ms command dispatch).
---
## π Repository Structure
```text
antigravity-robotics-plugin/
βββ plugin.json # Antigravity native plugin manifest
βββ mcp_config.json # MCP stdio client configuration
βββ pyproject.toml # Modern PEP 621 build configuration
βββ setup.py # Setuptools packaging specification
βββ LICENSE # Apache 2.0 Open Source License
βββ README.md # Complete system documentation
βββ assets/
β βββ logo.svg # Vector logo badge
βββ rules/
β βββ AGENTS.md # Priority directives & sidecar link rules
βββ skills/
β βββ ros2-robotics/
β βββ SKILL.md # Antigravity skill specification
βββ sidecars/
β βββ dashboard/
β βββ sidecar.json # Aux pane sidecar configuration
β βββ launch.py # Robust sidecar launcher
βββ ros2_mcp/
β βββ server.py # Core MCP server & JSON-RPC stdio transport
β βββ ros2_interface.py # Dual runtime (ROS2NativeInterface & MockInterface)
β βββ sandbox.py # 3-tier security sandbox & mutex audit log
β βββ tools/ # 16 modular tool implementations
β βββ dashboard/
β βββ server.py # Asynchronous HTTP/SSE/WebSocket streaming server
β βββ static/
β βββ index.html # 4-tab semantic HTML5 dashboard interface
β βββ style.css # Zero-G aerospace dark theme
β βββ app.js # 360Β° LiDAR radar, tactile D-Pad, & telemetry
βββ ros2_packages/
β βββ antigravity_core/ # C++ rclcpp_lifecycle::LifecycleNode package
β βββ antigravity_rviz_panel/ # Native C++/Qt rviz_common::Panel plugin
βββ sim/
β βββ worlds/zero_g_orbit.sdf # Gazebo Harmonic zero-gravity world
β βββ models/ # 6-DOF craft model with thrusters & LiDAR
β βββ launch/ # ROS 2 Gazebo simulation launch pipeline
βββ tests/ # 152 passing automated tests
```
---
## π License & Attribution
This project is open-source software licensed under the **[Apache License 2.0](LICENSE)**.
Developed and maintained by **[Abdullah Bin Zafar](https://github.com/EngineerAbdullahBinZafar)**.
Contributions, bug reports, and pull requests are welcome!
TDQS
Scored across 16 tools
Most tools have clearly distinct purposes by resource and action, such as ping vs system_diagnostics and list_topics vs list_nodes. There is minor adjacency between read_topic and get_robot_snapshot, and between predict_trajectory and predictive_safety_check, but descriptions make the boundaries usable.
All tool names use snake_case, and most follow a verb_noun pattern such as list_topics, get_parameter, and tune_pid. A few names are noun/status-oriented (ping, system_diagnostics, swarm_fleet_status), but the overall naming is predictable.
Sixteen tools is slightly above the typical ideal range, but the ROS2 robotics scope is broad and each tool maps to a meaningful capability such as diagnostics, topic access, parameters, PID tuning, prediction, and fleet status. The set is reasonable rather than bloated.
The surface covers core ROS2 graph operations, robot health, topic read/write, node inspection, parameters, PID tuning, safety checks, and spatial mapping. Notable gaps remain around ROS2 services/actions and node lifecycle management, but core diagnostic and control workflows are well represented.