Metadata-Version: 2.4
Name: sensorium
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Dist: numpy>=1.22
Requires-Dist: maturin>=1.5.0 ; extra == 'dev'
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Phoenix Sensorium Hardware & Ingestion Engine: High-Frequency, Multi-Modal Sensor Ingestion, Normalization, and Time-Alignment Framework
Author-email: Phoenix Defense AI Team <dev@phoenix-adt.mil>
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/phx-adt/phx-sensorium-sdk#readme
Project-URL: Homepage, https://github.com/phx-adt/phx-sensorium-sdk
Project-URL: Issues, https://github.com/phx-adt/phx-sensorium-sdk/issues
Project-URL: Repository, https://github.com/phx-adt/phx-sensorium-sdk

# Phoenix Sensorium SDK (`phx-sensorium`)

<p align="center">
  <img src="gallery/image.png" alt="Phoenix Sensorium - Real-Time Sensor Fusion & Hardware Ingestion Platform" width="100%" />
</p>

[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![PyO3](https://img.shields.io/badge/PyO3-0.21-purple.svg)](https://pyo3.rs/)
[![License: Proprietary](https://img.shields.io/badge/license-Phoenix%20ADT-red.svg)]()

> Deterministic, High-Frequency Multi-Modal Sensor Ingestion, Normalization, and Time-Alignment Framework for Autonomous Ground, Aerial, and Naval Defense Systems.

---

## 1. Overview

**Phoenix Sensorium** bridges physical hardware sensors (4K Optical/IR Vision, FMCW Radars, LiDARs, and 9-DoF IMUs) with modern Python AI/ML inference pipelines (PyTorch, TensorRT, NumPy) with **zero CPU memory copying** and **sub-millisecond deterministic time alignment**.

### Key Highlights
* **Zero-Copy Ingestion:** Exposes raw video and point cloud buffers directly to NumPy arrays via `__array_interface__`, eliminating memory copies and maximizing bandwidth.
* **Deterministic Time-Alignment:** Uses continuous Linear Interpolation (LERP) and anchor-driven grouping to eliminate phase errors between high-rate IMUs (400Hz) and lower-rate cameras (30Hz).
* **Multi-Threaded Rust Core:** All hardware polling, CRC32 checks, and ring buffer management execute outside the Python Global Interpreter Lock (GIL).
* **Automated Hardware Introspection:** Scans native Linux buses (V4L2, USB-Serial, SocketCAN) and discovers peripheral microcontrollers over serial interfaces.

---

## 2. Quickstart & Installation

### Option A: For Python Users (From PyPI - Zero Rust Required)
End users do **not** need Rust, Cargo, or any C/C++ compiler installed. Pre-compiled binary wheels (`.whl`) are distributed directly via PyPI:

```bash
pip install sensorium
```

### Option B: Building from Source (For Developers)
To compile the core engine and native bindings from source:

```bash
# 1. Clone the repository
git clone https://github.com/Phoenix-ADT/phx-sensorium.git
cd phx-sensorium-sdk

# 2. Automated setup script
chmod +x install.sh
./install.sh
```

---

## 3. Python Quickstart & Examples

### 3.1 Hardware & Controller Introspection
Inspect the host platform architecture, native character buses, and connected microcontrollers:

```python
import sensorium

hub = sensorium.SensorHub()

# 1. Inspect host platform architecture & native buses
host = hub.inspect_host()
print(f"Board: {host.board_model} | Arch: {host.arch} | DMA Engine: {host.dma_type}")
print(f"I2C Buses: {host.i2c_buses}")
print(f"GPIO Chips: {host.gpio_chips}")

# 2. Automatically sweep hardware buses (V4L2, USB-Serial, SocketCAN)
devices = hub.scan_hardware(timeout_ms=150)
for dev in devices:
    print(f"Discovered Device: {dev.endpoint} [{dev.bus_type}] -> {dev.model_guess}")

# 3. Discover connected microcontrollers (ESP32, STM32, Arduino)
controllers = hub.discover_controllers(timeout_ms=250)
for mcu in controllers:
    print(f"MCU: {mcu.mcu_model} [ID: {mcu.chip_id}] @ {mcu.clock_freq_mhz} MHz")
    print(f"Attached Sub-Sensors: {mcu.sub_sensors}")
```

### 3.2 Time-Synchronized Fusion & Zero-Copy NumPy
Create a multi-modal perception group anchored to an optical camera:

```python
import numpy as np
import sensorium

hub = sensorium.SensorHub()

# Define a synchronized group anchored on the 30 FPS camera
group = hub.create_sync_group(
    name="cockpit_perception",
    anchor_sensor="eo_camera",
    sensors=["imu_chassis", "radar_front"],
    max_slop_ms=25.0,
    interpolate_scalars=True,
)

# Start background ingestion workers outside the Python GIL
hub.start()

try:
    for frame in group:
        if frame.is_degraded:
            continue

        # Zero-copy view into camera frame (Shape: H, W, C)
        image = np.asarray(frame.tensor("eo_camera"), copy=False)

        # 9-DoF IMU telemetry mathematically interpolated to exact shutter time
        imu_state = frame.scalar("imu_chassis")

        # 3D Radar target tracks
        tracks = frame.tracks("radar_front")

        print(f"Snapshot @ T={frame.timestamp_ns} ns | Image: {image.shape} | IMU: {imu_state[:3]}")
        break
finally:
    hub.stop()
```

### 3.3 Asynchronous Pipeline (`asyncio`)
Stream aligned snapshots asynchronously into event-driven or networked workflows:

```python
import asyncio
import numpy as np
import sensorium

async def stream_pipeline():
    hub = sensorium.SensorHub()
    group = hub.create_sync_group(
        name="async_feed",
        anchor_sensor="eo_camera",
        sensors=["imu_chassis"],
        max_slop_ms=30.0,
    )

    hub.start()
    try:
        async for frame in group.stream_async(poll_interval_ms=2):
            img = np.asarray(frame.tensor("eo_camera"), copy=False)
            print(f"Async Frame T={frame.timestamp_ns} | Image Shape: {img.shape}")
            break
    finally:
        hub.stop()

if __name__ == "__main__":
    asyncio.run(stream_pipeline())
```

---

## 4. Edge Microcontroller Integration (`SensoriumBridge.h`)

To connect an edge microcontroller (STM32, ESP32, Arduino, Pixhawk) to Sensorium, use the zero-allocation single-header C++ firmware bridge in [`firmware/SensoriumBridge.h`](firmware/SensoriumBridge.h):

```cpp
#include <Arduino.h>
#include "SensoriumBridge.h"

SensoriumNode node("turret_mcu");
SensorSlot imu_slot;

void setup() {
    node.begin_serial(921600);
    imu_slot = node.register_scalar("turret_imu", 6, 200); // 6 channels at 200 Hz
}

void loop() {
    node.spin(); // Process active discovery pings and time calibration

    static uint32_t last_time = 0;
    if (micros() - last_time >= 5000) { // 200 Hz
        last_time = micros();
        float imu_data[6] = {ax, ay, az, gx, gy, gz};
        node.publish_scalar(imu_slot, micros(), imu_data, 6);
    }
}
```

---

## 5. Complete Documentation & Guides

For deep architectural explanations, full API references, and advanced integration tutorials, explore the comprehensive guides in the [`DOCS/`](DOCS/) folder:

| Guide | Description |
| :--- | :--- |
| **[Documentation Index](DOCS/index.md)** | Master sitemap, architectural diagram, and component breakdown. |
| **[01. Getting Started](DOCS/01_getting_started.md)** | Step-by-step installation, fundamental concepts, and first working pipeline. |
| **[02. SensorHub & Ingestion Engine](DOCS/02_sensor_hub_and_orchestration.md)** | Channel registration, ring buffer overflow policies, and lifecycle management. |
| **[03. Multi-Modal Time Synchronization](DOCS/03_multimodal_synchronization.md)** | Anchor-driven grouping, LERP interpolation mathematics, and streaming modes. |
| **[04. Zero-Copy Tensors & NumPy Integration](DOCS/04_zero_copy_tensors_and_numpy.md)** | `DenseTensor` internals, `__array_interface__`, PyTorch CUDA streaming, and TensorRT. |
| **[05. Hardware Introspection & MCU Multiplexing](DOCS/05_hardware_and_controller_introspection.md)** | Linux character bus scanning, microcontroller discovery, and `SensoriumBridge.h`. |
| **[06. Sanity Filters & Production Best Practices](DOCS/06_troubleshooting_and_best_practices.md)** | Real-time IEEE-754 sanity checks, register freeze detection, and RTOS configuration. |

---

<p align="center">
  <img src="gallery/phx-adt.png" alt="Phoenix ADT - Advanced Tech" width="55%" />
</p>

