# Oya Domain — Features > **Oya** (`libs/oya/`) is the drone and autonomous aerial systems domain of the > Oshun monorepo. Named after the Yoruba goddess of winds, storms, and > transformation, Oya ships **six** packages under `libs/oya/`. The flagship > `@oya/core` library — implemented in TypeScript and containing 101 source > modules — both establishes the typed vocabulary (branded IDs, 3D math > primitives, coordinate frames, flight state enumerations, telemetry schemas, > camera and payload types, geofencing, and mission planning primitives) and > implements the working subsystems built on it: flight control, sensor fusion, > computer vision, swarm coordination, autopilot integration (PX4 and > ArduPilot), MAVLink v2 communication, 3D reconstruction, regulatory > compliance, next-generation power systems, and a drone-as-a-service enterprise > platform. Five focused sibling packages — `@oya/flight-control`, > `@oya/telemetry`, `@oya/mission-planning`, `@oya/safety`, and > `@oya/swarm-intelligence` — each provide a production-readiness evaluator > (and, for swarm intelligence, concrete swarm-control primitives). Consuming > teams import from these packages to build ground control stations, fleet > dashboards, mission planners, and domain integrations. The application and > service tier (`apps/oya/`, `services/oya/`), concrete platform-bus wiring, and > the Gaia weather adapter are the remaining planned scope. --- Oya solves the engineering problem of building production drone-fleet software in TypeScript without reinventing the wheel for every project. Drone software has unusual requirements: it must work with multiple autopilot firmwares (PX4, ArduPilot, DJI), with multiple physical coordinate frames (GPS geodetic, local NED, body-fixed), with real-time telemetry streams from potentially dozens of drones, and with regulatory frameworks (FAA Part 107, EU SORA, Remote ID) that have legal force. Without a shared library layer, teams end up re-implementing the same physics, the same MAVLink parser, and the same geofence checker in every project. `@oya/core` provides that shared layer. A ground control station, a fleet dashboard, a cinematography planner, and an inspection reporting tool can all import the same `Mission`, `Telemetry`, and `GeofenceZone` types and be confident they mean the same thing. The five sibling packages add a production-readiness evaluation layer on top: before you commit to a mission, you can run your flight-controller state, telemetry feeds, mission plan, safety case, and swarm configuration through typed evaluators that return structured `blocking` or `warning` issues and an aggregate status. --- ## `@oya/core` — Foundation Types, Coordinates, and Validation Every Oya module depends on the core type system. `@oya/core` declares a single runtime dependency — `zod` — and provides every branded ID type, 3D math primitive, coordinate frame, flight state enumeration, telemetry schema, and mission type that all other modules build on. Zod schemas accompany every type, providing runtime validation at service boundaries. ### Drone Identity Types (`types.ts`) Branded ID types prevent accidental mixing of identifiers at compile time. Passing a `MissionId` where a `DroneId` is expected is a TypeScript error, not a silent runtime bug. - **`DroneId`, `SwarmId`, `MissionId`, `WaypointId`** — Branded string identifiers with corresponding Zod schemas for runtime format validation (UUID v4 format enforced). ### 3D Mathematics (`types.ts`, `math-utils.ts`) All drone kinematics, sensor data, and navigation algorithms work in three dimensions. These types are the mathematical substrate for every computation in Oya. - **`Position3D`, `Velocity3D`, `Acceleration3D`** — `Position3D` is geodetic (latitude/longitude in decimal degrees, altitude in meters above MSL); `Velocity3D` is `{ vx, vy, vz }` in m/s; `Acceleration3D` is `{ ax, ay, az }` in m/s². All three have corresponding Zod schemas. - **`Orientation`, `Quaternion`, `EulerAngles`** — Drone attitude as Euler angles (roll, pitch, yaw) in radians (Tait-Bryan ZYX convention) and as unit quaternions (w, x, y, z). `QuaternionSchema` enforces unit norm. Quaternions are more numerically stable for composition and interpolation and are used internally by attitude estimators. `EulerAngles` is an alias of `Orientation`. - **Math Utilities** — `coordinate-transforms.ts` and `math-utils.ts` supply the numeric toolkit: angle conversion, GPS↔NED↔Body frame transforms, quaternion↔Euler conversion, `haversineDistance` and Vincenty geodesic distance, rotation matrices, interpolation (`slerp`, splines, Béziers), signal filters (`KalmanFilter`, `ExtendedKalmanFilter`, `MadgwickFilter`, …), PID controllers, geometry/collision helpers, and CRC checksums. Vector and quaternion algebra (`vec3`, `vec3Sub`, `vec3Cross`, `quatNormalize`, `quatMultiply`, …) lives in `kinematics.ts`. ### Coordinate Systems (`types.ts`, `constants.ts`) Drone navigation uses multiple coordinate frames. Converting between them correctly is critical for accurate geolocation, sensor fusion, and waypoint following. Oya defines three distinct frame types so that functions requiring one frame cannot accidentally receive another. - **`GPSCoordinates`** — Geodetic coordinates: latitude, longitude, altitude (MSL or AGL), datum reference (WGS84 default). - **`LocalCoordinates`** — Local North-East-Down (NED) frame relative to a reference origin, for small-area operations where flat-Earth approximation is valid. - **`BodyCoordinates`** — Drone-body-relative frame (forward/right/down axes) for sensor data expressed in the drone's own reference frame. - **WGS84 Constants** — `WGS84_A`, `WGS84_B`, `WGS84_E`, `WGS84_E2`, `WGS84_F`, `WGS84_INVERSE_F` — the Earth ellipsoid model parameters used by all coordinate transform algorithms. - **Physical Constants** — `STANDARD_GRAVITY` (9.80665 m/s²), `EARTH_MEAN_RADIUS`, `SPEED_OF_SOUND_SEA_LEVEL`, `AIR_DENSITY_SEA_LEVEL`. ### Flight Mode and State Enumerations (`types.ts`) Typed enumerations cover every operating mode and lifecycle state a drone can be in. Using typed enums rather than raw strings prevents invalid mode strings from reaching flight control logic and makes switch-statement exhaustiveness checking possible. - **`FlightMode`** — `Manual`, `Stabilized`, `Altitude`, `Position`, `Mission`, `ReturnToHome`, `Land`, `Loiter`, `Guided`, `Acro`. - **`DroneState`** — `Idle`, `Preflight`, `Armed`, `TakingOff`, `Flying`, `Hovering`, `Landing`, `Landed`, `Emergency`, `Disarmed`. - **`ConnectionStatus`** — `Disconnected`, `Connecting`, `Connected`, `Reconnecting`, `Lost`, `Error`. - **`AirspaceClass`** — ICAO airspace classifications: `A`, `B`, `C`, `D`, `E`, `G`, plus `Restricted`, `Prohibited`, `Danger`, `TemporaryFlightRestriction`. - **`GimbalMode`** — `Free`, `Follow`, `Lock`, `FPV`. - **`GeofenceBehavior`, `GeofenceType`, `EmergencyType`, `FlightPlanStatus`, `WaypointAction`, `WeatherResistance`** — Complete typed enumerations for geofencing behavior, emergency classifications, mission status lifecycle, and hardware capability ratings. ### Telemetry and Sensor Types (`types.ts`) These are the types that flow in real time from drones to any ground station, dashboard, or logging system. Everything from a single-drone status widget to a 50-drone fleet replay is built on these records. - **`Telemetry`** — Real-time drone state snapshot: `DroneId`, ISO-8601 timestamp, `Position3D`, `Velocity3D`, `Acceleration3D`, `Orientation`, `BatteryState`, `GPSCoordinates`, signal strength (dBm), satellite count, and the active `FlightMode`, `DroneState`, and `ConnectionStatus`. GPS fix quality, HDOP/VDOP, motor RPMs, and ESC temperatures are not fields on this base record — they live in the higher-level telemetry modules (`@oya/telemetry`, `core/src/telemetry-collection.ts`). This is the canonical telemetry record for logging, dashboards, and mission replays. - **`BatteryState`** — Voltage, current, remaining charge percentage, estimated remaining flight time, temperature, cell count, charging flag, and discharge cycle count. - **`DroneCapabilities`** — Capability descriptor: max speed, max altitude, max flight time, and boolean flags for camera, gimbal, RTK GPS, thermal camera, LiDAR, and obstacle avoidance, plus max payload weight and a `WeatherResistance` rating. - **`CameraSettings`, `GimbalState`, `PayloadInfo`, `WeatherConditions`** — Typed structures for camera configuration, gimbal orientation, payload attachment status, and atmospheric conditions. - **Telemetry Collection** (`telemetry-collection.ts`) — Telemetry aggregation from multiple drones, with time-series buffering and anomaly flagging. - **Time-Series Storage** (`timeseries-storage.ts`) — Typed time-series telemetry storage with configurable retention, downsampling, and range queries for post-flight analysis. ### Mission and Waypoint Types (`types.ts`) Mission planning in Oya is fully typed from the individual waypoint action up to the top-level mission plan. This ensures that a mission created by an AI planner, validated by a regulatory-compliance checker, and uploaded to a drone all share exactly the same data structure. - **`Waypoint`** — Single waypoint with `GPSCoordinates`, approach speed, exit heading, hover duration, trigger radius, and a list of `WaypointActionEntry` items to execute on arrival. - **`Mission`** — Top-level mission: `MissionId`, name, drone assignment, ordered waypoints, `MissionConstraints`, `MissionMetadata`, and `FlightPlanStatus`. - **`MissionConstraints`** — Safety boundaries: maximum altitude AGL, maximum horizontal distance from home, minimum battery to continue, maximum wind speed, flight time limit, and geofence zones. - **`FlightPlan`** — Validated, serializable mission plan with checksum for upload verification and protocol version for compatibility. - **`EmergencyProcedure`** — Per-emergency-type response definitions: trigger condition, immediate action (RTL/LAND/HOVER), notification targets, and operator override capability. - **Mission Execution Engine** (`mission-execution.ts`) — The mission state machine: `MissionUploader`, `MissionValidator`, `WaypointSequencer`, `WaypointNavigationStateMachine`, `WaypointAcceptanceChecker`, and the straight-line, curved-transition, stop-and-turn, and fly-through navigation modes, with a `totalMissionDistance` helper. ### Geofence Types (`types.ts`) Geofences are the safety boundary between a drone and controlled or restricted airspace. Oya models them as typed zone objects so that the same geofence definition can be validated on the ground, enforced in-flight, and stored for audit. - **`GeofenceZone`** — Zone definition: `GeofenceType` shape (`Circle` or `Polygon`) with center/radius or GPS vertices, min/max altitude limits, and a `GeofenceBehavior` on violation (`Warn`, `ReturnToHome`, `Land`, `Stop`). - **Real-Time Geofence Enforcement** (`geofencing.ts`) — Geofence shape classes (`PolygonGeofence`, `CircularGeofence`, `CylindricalGeofence`, `CorridorGeofence`), zone managers (`NoFlyZoneManager`, `DynamicGeofence`, `NestedGeofenceManager`), and the `BreachDetector`, `GraduatedWarningSystem`, and `ContainmentActionExecutor` enforcement pipeline. --- ## Autopilot Integration ### PX4 Autopilot (`px4-autopilot.ts`) PX4 is the most widely used open-source flight controller. Oya's integration covers both SITL (Software-In-The-Loop) simulation and real hardware, providing a unified TypeScript API regardless of connection type. - **PX4 Connection and MAVLink v2** — Manages TCP/UDP connection to PX4 with full MAVLink v2 protocol handling, system and component ID negotiation, and heartbeat management. - **Offboard Mode Control** — TypeScript API for PX4's offboard mode: position setpoints, velocity setpoints, attitude setpoints, and thrust setpoints with correct frame specification. - **uORB Topic Access** — Subscribe to and publish PX4's internal uORB (publish/subscribe messaging) topics for advanced autopilot integration. - **EKF2 State Access** — Access PX4's EKF2 (Extended Kalman Filter 2) state estimator outputs: position, velocity, attitude, wind estimate, and innovation test ratios. - **VTOL Transitions** — Control and monitor vertical-takeoff-to-fixed-wing transitions for tilt-rotor and tailsitter VTOL airframes. - **Gimbal Protocol v2** — Full PX4 Gimbal Protocol v2 implementation for professional camera gimbal control. - **PX4-ROS2 Bridge** — Integration with the PX4-ROS2 microXRCE-DDS bridge for systems co-deploying with ROS2 ecosystems. - **Parameter Management** — Read and write PX4 parameters programmatically for automated configuration, parameter tuning, and configuration backup/restore. ### ArduPilot (`ardupilot.ts`) ArduPilot covers a broader range of vehicle types than PX4 and is common in commercial inspection and agriculture use cases. Oya supports all three major ArduPilot vehicle classes. - **MAVLink Dialect Handling** — ArduPilot's MAVLink dialect extensions (FENCE_ACTION, FENCE_BREACH, EKF_STATUS_REPORT, etc.) beyond the standard MAVLink common message set. - **GUIDED Mode Navigation** — Send GPS position targets, velocity targets, and heading targets in GUIDED mode for precise autonomous navigation. - **Rally Points** — Define rally points for intermediate RTL destinations rather than always returning to the home point, critical for long-range operations. - **Lua Scripting Interface** — Interface with ArduPilot's Lua scripting system for onboard mission customization. - **ArduPilot Log Download** — MAVLink log download protocol for retrieving onboard DataFlash logs for post-flight analysis. - **Companion Computer Communication** — Serial and MAVLink-over-TCP communication protocols for companion computers running computer vision and AI alongside the flight controller. --- ## Sensor Integration ### GPS Navigation (`gps-navigation.ts`) Accurate GPS is critical for waypoint following and safe return-to-home. Oya's GPS module goes beyond simple coordinate parsing to support RTK centimeter-level accuracy and active spoofing detection. - **u-blox UBX Protocol Parser** — Full binary protocol parser for u-blox GNSS receivers, extracting NAV-PVT, NAV-SAT, and NAV-STATUS messages. - **RTK Correction Injection** — RTCM3 correction message injection for centimeter-accurate RTK GPS positioning. - **Multi-Constellation GNSS** — GPS, GLONASS, Galileo, and BeiDou multi-constellation fusion for best position accuracy. - **GPS Spoofing Detection** — Heuristic and statistical methods to detect GPS signal spoofing based on satellite geometry, signal strength, and position jump analysis. ### IMU and Orientation (`imu-orientation.ts`) IMUs (accelerometers + gyroscopes + optional magnetometers) provide attitude estimates at far higher rates than GPS, but accumulate drift over time. Oya's IMU module implements two complementary fusion algorithms with different trade-offs for different sensor quality profiles. - **Madgwick AHRS** — Sensor fusion algorithm fusing accelerometer, gyroscope, and optional magnetometer data into a stable orientation quaternion without GPS. - **Mahony AHRS** — Alternative sensor fusion algorithm with configurable proportional and integral gain for different sensor quality profiles. - **Gyroscope Drift Compensation** — Long-term bias estimation and correction for accumulated gyroscope drift. - **Accelerometer Calibration** — 6-point calibration procedure for accelerometer bias and scale factor correction. ### LiDAR Integration (`lidar-integration.ts`) LiDAR gives drones a dense 3D picture of their environment — critical for obstacle avoidance, terrain following, and generating survey-grade point clouds for inspection and construction workflows. - **Point Cloud Collection** — Real-time 3D LiDAR point cloud acquisition from spinning and solid-state LiDAR sensors. - **Ground Plane Extraction** — RANSAC-based ground plane detection for terrain-following and landing zone assessment. - **Building and Vegetation Classification** — Machine learning classification of point cloud objects for infrastructure inspection and forestry applications. - **DSM (Digital Surface Model) Generation** — Generate Digital Surface Models from LiDAR point clouds for terrain analysis. ### Depth Sensors (`depth-sensors.ts`) Stereo cameras and Time-of-Flight sensors give drones close-range depth perception that complements LiDAR, particularly important for obstacle avoidance in cluttered environments where LiDAR may have blind spots. - **Stereo Vision Depth Maps** — Stereo camera disparity computation for obstacle detection ranges to approximately 20 meters. - **ToF Sensor Fusion** — Time-of-Flight sensor data fusion with stereo vision for improved close-range accuracy. - **Monocular Depth Estimation** — Single-camera depth estimation using pretrained neural networks for platforms without dedicated depth sensors. ### Multi-Sensor Fusion (`multi-sensor-fusion.ts`) No single sensor is reliable in all conditions. The fusion layer combines GPS, IMU, barometer, magnetometer, optical flow, and UWB into a single unified state estimate, with automatic fallback when individual sensors degrade. - **Extended Kalman Filter** — Full EKF implementation fusing GPS, IMU, barometer, magnetometer, optical flow, and UWB ranging into a unified state estimate. - **UWB (Ultra-Wideband) Positioning** — Two-Way Ranging protocol for centimeter-accurate indoor positioning in GPS-denied environments. - **Optical Flow** — Pixel flow velocity integration for GPS-denied horizontal position hold. - **Visual-Inertial Odometry (VIO)** — Camera + IMU fusion for 6DOF odometry without GPS, enabling indoor autonomous navigation. --- ## Computer Vision and AI ### SLAM and Visual Navigation (`visual-slam.ts`, `advanced-slam-vio.ts`) SLAM (Simultaneous Localization and Mapping) lets drones build a map of their environment while tracking their own position within it — essential for GPS-denied flight such as indoor inspection or underground operations. - **ORB-SLAM3 Integration** — Real-time monocular, stereo, and RGB-D SLAM for GPS-denied navigation. - **Event Camera Navigation** (`event-camera-navigation.ts`) — Integration with event cameras (neuromorphic sensors that respond to pixel brightness changes rather than frames) for high-speed, low-latency obstacle detection. - **MSCKF (Multi-State Constraint Kalman Filter)** (`advanced-slam-vio.ts`) — Tightly-coupled visual-inertial state estimator for accurate long-range VIO. ### Obstacle Avoidance (`obstacle-avoidance.ts`) Safe autonomous flight requires knowing not just where the drone is but what is around it, and reacting in real time to avoid collisions. Oya implements both single-drone reactive avoidance and multi-drone reciprocal avoidance. - **Potential Field Path Modification** — Real-time path deformation around obstacles using artificial potential fields. - **ORCA (Optimal Reciprocal Collision Avoidance)** — Multi-agent collision avoidance for swarms where each drone assumes others will also apply ORCA. - **3D Occupancy Grid** — Volumetric occupancy representation for 3D obstacle mapping and path planning. - **Human-Aware Navigation** (`human-aware-navigation.ts`) — Navigation behaviors that maintain safe distances from detected humans and predict human motion to avoid collisions. ### Computer Vision Pipeline Oya integrates multiple state-of-the-art detection and tracking models, covering everything from fast real-time detection to high-accuracy aerial-view specialized architectures. - **Object Detection — YOLOv12** (`yolov12-integration.ts`) — State-of-the-art real-time object detection with drone-optimized inference, aerial view fine-tuning, and multi-class confidence thresholds. - **Object Detection — RT-DETR** (`rtdetr-integration.ts`) — Detection Transformer for high-accuracy detection without anchor box tuning. - **UAV-DETR** (`uavdetr-integration.ts`) — Detection transformer specialized for UAV-perspective images where targets are small and densely packed. - **Subject Tracking** (`subject-tracking.ts`) — Multi-object tracking with Kalman filter-based trajectory prediction for follow-me and cinematography applications. - **Pose Detection** (`pose-detection-2d.ts`, `advanced-pose-estimation.ts`) — 2D and 3D human pose estimation for form analysis, sports coaching, and search-and-rescue person detection. - **Sapiens Integration** (`sapiens-integration.ts`) — Meta's Sapiens foundation model for dense human pose estimation and body segmentation from aerial perspectives. - **SAM Integration** (`sam-integration.ts`) — Segment Anything Model integration for zero-shot semantic segmentation of aerial imagery. - **3D Body Reconstruction** (`body-reconstruction-3d.ts`) — 3D human body shape and pose reconstruction from monocular drone footage for biomechanics analysis. ### Pretrained Models and Edge Inference Running full neural network inference on a ground server introduces communication latency that can make obstacle avoidance unsafe. Oya's edge inference stack handles model optimization and deployment directly to drone-mounted accelerators. - **Pretrained Models** (`pretrained-models.ts`) — Managed catalog of drone-optimized pretrained model weights with version tracking, download management, and benchmark scores. - **Model Optimization** (`model-optimization.ts`) — ONNX export, quantization (INT8, FP16), TensorRT and Core ML optimization, and model pruning for edge deployment. - **Edge Deployment** (`edge-deployment.ts`) — Deployment manager for running optimized models on drone-mounted Jetson Orin, Raspberry Pi 5, and Hailo-8 edge inference accelerators. - **Model Inference** (`model-inference.ts`) — Unified inference API over ONNX Runtime, TensorRT, and platform-native inference engines. ### Specialized Vision Systems - **Multi-View Fusion** (`multi-view-fusion.ts`) — Fuse overlapping imagery from multiple drones or multiple passes for improved reconstruction quality. - **Temporal Tracking** (`temporal-tracking.ts`) — Long-horizon object tracking across video frames with re-identification after temporary occlusion. - **Multi-Camera Coordination** (`multi-camera-coordination.ts`) — Synchronize capture across multiple drone-mounted cameras for stereo, 3D reconstruction, and coverage applications. --- ## Flight Control Systems ### Kinematics and Dynamics (`kinematics.ts`) The kinematics module provides the mathematical foundation for simulating how a drone responds to motor commands — used in simulation, autopilot tuning, and trajectory planning. - **6-DOF Rigid Body Dynamics** — Full six-degree-of-freedom equations of motion for rigid body flight simulation. - **Rotor Configuration Models** — Motor mixing matrices for quadrotor (X and + configurations), hexarotor, and octorotor airframes. - **Thrust and Torque Models** — Propeller thrust model using blade momentum theory and blade element theory for accurate thrust estimation. - **Aerodynamic Models** — Drag model, wind disturbance model, and Dryden turbulence model for realistic simulation. ### Attitude Control (`attitude-control.ts`) Attitude control is the inner loop that keeps a drone level and pointed the right way. Oya implements two architectures: the classical cascaded PID used by most commercial autopilots, and the more mathematically elegant geometric control that avoids singularities at extreme attitudes. - **Cascaded PID Controller** — Inner attitude rate loop and outer attitude angle loop. Cascaded control provides fast inner response with stable outer behavior. - **Quaternion Geometric Control** — SO(3) geometric control laws for singularity-free attitude control across all orientations. - **Attitude Estimation Filters** — EKF, Madgwick AHRS, and Mahony AHRS for sensor fusion. - **Auto-Tune** — Automated PID gain tuning via test signal injection and response analysis. - **Motor Failure Compensation** — Detect asymmetric thrust and automatically adjust remaining motor outputs to maintain attitude. ### Velocity and Position Control (`velocity-position-control.ts`) The outer control loops sit above attitude control and translate the desired drone position or velocity into attitude setpoints. Multiple position measurement sources are supported with automatic fallback. - **GPS, RTK-GPS, VIO, and UWB Position Hold** — Multiple position source backends with automatic fallback between GPS-based and GPS-denied modes. - **Cinematic Velocity Mode** — Butter-smooth velocity controller for cinematography with configurable jerk limits. - **Trajectory Planning** (`path-planning.ts`) — Minimum-snap trajectory generation through waypoints, Dubins path planning for fixed-wing-style turns, and B-spline smoothing. - **Follow-Me Mode** — Target tracking with Kalman filter prediction for smooth following even when GPS updates are intermittent. ### Gimbal Control (`gimbal-control.ts`, `camera-gimbal-api.ts`) For cinematography and inspection drones, the gimbal is as important as the flight controller — it keeps the camera stable and pointed at the subject regardless of airframe vibration and wind. - **3-Axis Gimbal Stabilization** — Roll, pitch, and yaw stabilization compensating for airframe vibration and wind gusts. - **Follow / Lock / FPV / Free Modes** — All four standard gimbal operating modes with smooth transitions between them. - **Camera-Gimbal Calibration** — Intrinsic and extrinsic calibration for precise gimbal angle to camera pointing relationship. - **Shot Planning** (`shot-planning.ts`) — Cinematic shot type library (orbit, dronie, reveal, top-down, fly-through) with camera angle and drone position planning. - **Cinematography Trajectory** (`cinematography-trajectory.ts`) — Pre-planned cinematic flight path generation with smooth keyframe interpolation for repeatable shots. --- ## Swarm Coordination ### Swarm API and Formation Flying (`swarm-api.ts`, `formation-flying.ts`) Swarm coordination allows multiple drones to fly as a single coordinated unit. Formations are defined as relative geometry, so the same swarm can execute a V-formation survey sweep and then reconfigure into a grid for area coverage without landing. - **Formation Patterns** — Predefined formation patterns: V-formation, line, grid, sphere, helix, and custom geometries defined as relative offset vectors. - **Dynamic Reconfiguration** — Change formation shape in flight with smooth trajectory planning for each drone from old to new position. - **Leader-Follower Architecture** — Centralized leader with position-following followers; leader failure triggers automatic leader re-election. ### Swarm Intelligence and Consensus (`swarm-coordination.ts`, `consensus-algorithms.ts`, `gnn-swarm-intelligence.ts`) For larger or longer-range swarms, a purely centralized leader-follower architecture is fragile. The intelligence modules add decentralized consensus and machine-learning-based emergent behavior. - **Distributed Task Assignment** (`task-allocation.ts`) — Contract net protocol for decentralized task bidding among swarm members; Hungarian algorithm for optimal task-to-drone assignment. - **Gossip Protocol State Sharing** — Epidemic protocol for distributing swarm state without a central coordinator, tolerant of drone loss. - **GNN Swarm Intelligence** (`gnn-swarm-intelligence.ts`) — Graph Neural Network-based swarm coordination where each drone learns from its neighbors' states and actions for emergent collective behavior. - **Consensus Algorithms** — Average consensus, max/min consensus, and leader election for distributed agreement without central coordination. ### Swarm Collision Avoidance (`swarm-collision-avoidance.ts`) Within a swarm, drones must avoid each other without a central arbitrator. ORCA lets each drone independently compute a collision-free velocity that is optimal given the assumption that all other drones are doing the same. - **ORCA Multi-Agent Avoidance** — Optimal Reciprocal Collision Avoidance with per-drone velocity obstacle computation. - **Priority-Based Right-of-Way** — Role-based priority rules for intersecting paths. - **Emergency Separation Maneuvers** — Immediate separation commands when proximity sensors detect imminent collision risk. ### Inter-Drone Communication (`inter-drone-communication.ts`) Reliable communication between drones is the backbone of any swarm. Oya extends MAVLink's multi-agent addressing with a mesh networking layer for range extension and bandwidth-adaptive scheduling to handle degraded links. - **MAVLink Swarm Messaging** — Multi-agent MAVLink v2 messaging with addressing, routing, and duplicate filtering. - **Mesh Networking** — Ad-hoc mesh network for range extension via drone relays with OLSR routing for automatic multi-hop paths. - **Bandwidth-Adaptive State Sharing** — Prioritized state message scheduling based on available inter-drone link bandwidth. --- ## Payload Systems ### Photogrammetry and Mapping (`gaussian-splatting-integration.ts`, `spatial-data.ts`) Aerial photogrammetry is one of the primary use cases for commercial drones. Oya's mapping pipeline integrates directly with Maya's 3D Gaussian Splatting reconstruction, turning geotagged drone imagery into production-quality 3D models. - **Survey Grid Planning** — Configurable forward/side overlap, GSD (Ground Sampling Distance — the physical size of one image pixel on the ground) calculator, and automatic ground control point injection. - **3D Gaussian Splatting Integration** — Direct pipeline from drone-captured geotagged images into `@maya/mirror`'s 3DGS reconstruction. Metadata (GPS coordinates, IMU attitudes, focal length) is embedded in image EXIF for Structure-from-Motion. - **Spatial Data Management** (`spatial-data.ts`) — GeoJSON storage, coordinate projection utilities, and spatial query APIs for drone-generated geographic datasets. ### Multispectral and Thermal Imaging Beyond RGB photography, specialized drone payloads capture multispectral and thermal data that reveals information invisible to the naked eye — crop health, equipment hot spots, and heat loss in buildings. - **NDVI Calculation** — `calculateNDVI(red, nir)` — Normalized Difference Vegetation Index for assessing plant health from multispectral imagery. - **Thermal Anomaly Detection** — Radiometric temperature calibration, emissivity correction, false color mapping, and hot spot localization for infrastructure inspection. - **Precision Agriculture Outputs** — Band capture (RGB, NIR, Red Edge), plant health mapping, and prescription map generation for variable-rate agriculture. --- ## MAVLink Protocol ### MAVLink v2 Implementation (`mavlink-protocol.ts`) MAVLink is the de-facto standard wire protocol for communicating with autopilot firmware. Oya implements the full v2 specification including the security and routing extensions that are critical for multi-drone operations. - **Full MAVLink v2 Protocol** — Heartbeat, command protocol (COMMAND_LONG, COMMAND_INT), mission protocol (upload/download, item types), parameter protocol (read, write, list), MAVLink FTP (file transfer), logging protocol, camera protocol, and gimbal v2 protocol. - **Message Signing** — MAVLink v2 message signing for authenticated links in security-sensitive deployments. - **MAVLink Router** — Multi-endpoint MAVLink router for distributing messages between ground control stations, companion computers, and telemetry links. ### Autopilot Integration Frameworks (`sitl-integration-framework.ts`) Software-In-The-Loop simulation lets engineers test mission logic against a full autopilot simulation before flying real hardware — critical for catching mission planning bugs that would be expensive or dangerous to discover in flight. - **SITL Framework** — Unified Software-In-The-Loop testing framework supporting PX4 SITL, ArduPilot SITL, Gazebo, AirSim, jMAVSim, and Microsoft AirSim backends through a common test API. - **Hardware-In-The-Loop Testing** (`modern-simulation-platforms.ts`) — HITL (Hardware-In-The-Loop) mode for running real flight controller firmware with simulated sensors. ### Simulation Platforms (`gazebo-integration.ts`, `airsim-integration.ts`, `jmavsim-integration.ts`, `modern-simulation-platforms.ts`) - **Gazebo Integration** — ROS2-compatible Gazebo plugin interface for sensor simulation, physics-accurate flight dynamics, and multi-drone world simulation. - **AirSim Integration** — Microsoft AirSim Python API integration for photorealistic Unreal Engine-based simulation with computer vision and sensor emulation. - **Modern Simulation Platforms** — Integration adapters for Flightmare, Isaac Sim, CARLA (for urban airspace simulation), and Webots. --- ## Regulatory Compliance and Safety ### Airspace and Regulatory Compliance (`regulatory-compliance.ts`, `faa-bvlos-compliance.ts`) Flying drones legally requires navigating a web of authorization systems and regulatory frameworks that differ by country, airspace class, and operation type. Oya automates the compliance checks and authorization requests that operators would otherwise have to manage manually. - **FAA LAANC Integration** — Low Altitude Authorization and Notification Capability for automated Part 107 flight authorization requests. - **FAA BVLOS Compliance** (`faa-bvlos-compliance.ts`) — Beyond Visual Line of Sight operation compliance checks, verifying that DAA system, C2 link, Remote ID, and operational requirements are all satisfied. - **EU SORA Compliance** — European Specific Operations Risk Assessment framework automation for generating safety assurance documentation. - **UTM Integration** — Unmanned Traffic Management system integration for real-time airspace deconfliction in urban environments. - **Remote ID Compliance** — FAA Remote Identification broadcast (ASTM F3411-22a standard) and EU eIDAS-compliant eID for legal operation in regulated airspace. ### Emergency Procedures (`emergency-procedures.ts`, `health-check.ts`) Every drone operation should have a pre-defined response for every possible failure mode. Oya encodes these as typed `EmergencyProcedure` objects with priority ordering so the most critical response is always taken first. - **Per-Emergency-Type Failsafe** — Configurable automatic responses for: - `LOW_BATTERY` — progressive warning → speed reduction → RTL → emergency landing. - `GPS_LOST` — switch to VIO/optical flow → loiter → RTL. - `SIGNAL_LOST` — execute pre-programmed lost-link procedure. - `GEOFENCE_BREACH` — immediate RTL/LAND. - `MOTOR_FAILURE` — assess thrust authority → emergency descent. - **Pre-Flight Safety Checks** (`health-check.ts`) — Comprehensive checklist: sensor calibration status, GPS accuracy (HDOP ≤ 1.5), battery state (≥ 30%), motor response test, compass heading, geofence boundary confirmation, and weather go/no-go. --- ## Next-Generation Power Systems (`nextgen-power-systems.ts`) Commercial drone operations are constrained by battery energy density. Oya models three energy technology paths — solid-state batteries, hydrogen fuel cells, and energy harvesting — together with the charging infrastructure needed to keep a fleet operational. ### Solid-State Batteries - **Solid-State BMS** — `SolidStateBMS` class implementing Kalman filter SOC (State of Charge) estimation (`kalmanSOCEstimate`), solid-state degradation modeling (`solidStateDegradation`), active and passive cell balancing, fast-charging profile generation (`generateFastChargingProfile`), and thermal scaling. - **Battery Passport** — `BatteryPassport` tracking operating history, SOH (State of Health) predictions, recall notices, and second-life evaluation for circular economy compliance. - **Thermal Runaway Prediction** — `predictThermalRunaway` using electrochemical feature analysis and anomaly scoring. ### Hydrogen Fuel Cells - **PEM Fuel Cell Modeling** — `pemfcPolarizationCurve` modeling voltage as a function of current density and temperature, `h2ConsumptionRate` for hydrogen tank sizing, and `fuelCellAltitudeCompensation` for pressure effects at altitude. - **Cold Start Management** — `fuelCellColdStart` sequence for sub-zero operation with battery pre-warming. - **Hybrid FC-Battery Architecture** — `hybridLiPoSolidStateSplit` computing optimal power split between fuel cell and battery for maximum efficiency. ### Energy Harvesting - **Solar Integration** — `calculateSolarIrradiance`, `solarCellPower`, and MPPT (Maximum Power Point Tracking) via perturbation-and-observe algorithm. - **Multi-Source Harvesting** — Thermoelectric generation, regenerative braking energy recovery, and RF energy harvesting models. - **Tethered Power** — `TetheredPowerSystem` with `catenarySag` and `cablePowerLoss` calculations for stationary high-endurance applications. ### Charging Infrastructure - **Charging Station Optimization** — `optimizeChargingQueue` for fleet-level battery swap scheduling; `v2gAnalysis` for vehicle-to-grid energy trading during peak demand. - **Wireless Charging** — `wirelessChargingEfficiency` for inductive charging pad integration in drone-in-a-box landing stations. --- ## Enterprise Platform (`enterprise-platform.ts`) Production drone operations at scale require more than flight control — they need fleet management, billing, SLA monitoring, and industry-specific workflow templates. Oya's enterprise module provides the business-logic layer on top of the core autonomy primitives. - **Drone-as-a-Service (DaaS)** — `DaaSPlatform` class managing subscription fleet access, per-flight billing, SLA monitoring, and customer onboarding workflows. - **Fleet Management System** — `FleetManagementSystem` for multi-site drone fleet tracking, maintenance scheduling, utilization analytics, and operational cost modeling. Utility functions: `calculateCostPerFlight`, `calculateMissionCarbonFootprint`, `calculateRUL` (Remaining Useful Life via Weibull reliability analysis). - **UTM Integration Engine** — `UTMIntegrationEngine` for automated airspace deconfliction across fleet operations. - **Drone-in-a-Box System** — `DroneInABoxSystem` managing automated launch/land pads with environmental monitoring, battery swap, and remote activation. - **AI Mission Agent** — `AIMissionAgentSystem` for LLM-powered mission planning (`extractMissionIntent`, `chainOfThoughtPlan`) and autonomous mission optimization based on weather, battery, and airspace conditions. - **Industry-Specific Solutions** — `IndustrySpecificSolutions` with pre-built workflow templates for five verticals: - **Infrastructure Inspection** — Bridge, powerline corridor, solar farm, and wind turbine inspection with defect detection and condition reporting. - **Agriculture** — Precision NDVI mapping, irrigation zone detection, and pest detection. - **Mining** — Volumetric stockpile measurement, haul route grading, and safety zone enforcement. - **Emergency Response** — Search area coverage planning, resource deployment tracking, and real-time situation updates. - **Public Safety** — Crowd monitoring with privacy compliance, perimeter surveillance, and incident documentation. - **Enterprise Analytics** — `EnterpriseAnalyticsEngine` for fleet KPI dashboards, mission outcome analysis, and operational trend reporting. --- ## Hardware Platform Support (`hardware-platforms-2025.ts`, `generic-hardware.ts`, `dji-sdk.ts`) Drone software that only works with one manufacturer's hardware has limited commercial reach. Oya abstracts over the three main hardware ecosystems — DJI proprietary, open-source Pixhawk-family, and leading edge-AI compute boards. - **DJI SDK Integration** (`dji-sdk.ts`) — DJI Mobile SDK and DJI Enterprise SDK integration for DJI Matrice, Agras, and Mavic series drones. - **Generic Hardware Abstraction** (`generic-hardware.ts`) — Driver-level abstraction for non-DJI autopilot hardware: Pixhawk, Cube, Holybro, and Matek flight controllers. - **2025 Hardware Platforms** (`hardware-platforms-2025.ts`) — Typed capability profiles and driver adapters for current-generation hardware: NVIDIA Jetson Orin (edge AI), Hailo-8L (inference accelerator), Auterion Suite, Skydio, Parrot ANAFI, and Freefly Alta. --- ## Observability and Post-Flight Analysis Understanding what happened during a flight — and why — requires structured logging, replay capability, and statistical analysis. Oya captures enough data to answer engineering questions days after a flight completes. - **Observability** (`observability.ts`) — Drone-specific metrics exported to `@oshun/metrics`: active mission count, fleet battery level distribution, signal quality histogram, geofence proximity distribution, and emergency event rates. - **Flight Logging** (`flight-logging.ts`) — Structured flight log format with per-frame telemetry, event annotations (arm, waypoint reached, mode change), and export to MAVLink DataFlash, KML, and GeoJSON formats. - **Post-Flight Analysis** (`post-flight-analysis.ts`) — `FlightReplayEngine`, `FlightStatisticsCalculator`, `AnomalyDetector`, `BatteryHealthAnalyzer`, and `FlightComparisonTool` computing mission efficiency, energy consumption, battery degradation per cycle, and anomaly detection over the telemetry record. - **Real-Time Streaming** (`realtime-streaming.ts`) — Low-latency telemetry streaming API for ground control station live dashboards via WebSocket and gRPC streaming. - **Video Streaming** (`video-streaming.ts`) — RTSP and WebRTC video stream management for live first-person view and payload camera feeds. --- ## Developer SDK and Data Access The SDK layer is what consuming teams — both internal Oshun domains and external application developers — actually import. It provides a clean high-level command API that hides the MAVLink framing and connection management complexity. - **SDK Core** (`sdk-core.ts`) — the SDK kernel: `SdkCore`, `ConnectionManager`, `SdkAuthenticator`, and `SdkEventBus`, plus middleware, plugin, feature-flag, health, and diagnostic infrastructure for consumer-facing drone access. - **Drone Control API** (`drone-control-api.ts`) — High-level command API: `arm`, `takeoff`, `goTo(waypoint)`, `returnToLaunch`, `land`, `setFlightMode`, `emergencyStop`. - **Telemetry API** (`telemetry-api.ts`) — `TelemetrySubscriptionAPI` and `RealTimeTelemetryStream` with typed subscription, plus dedicated battery, GPS, and sensor telemetry APIs, historical query, filtering, aggregation, and export. - **Data Access Layer** (`data-access-layer.ts`) — Repository pattern over the mission database with typed query APIs for historical mission data, telemetry archives, and fleet health records. - **Database Schema** (`database-schema.ts`) — TypeScript-typed database schema definitions for mission records, telemetry series, fleet inventory, and compliance documentation. --- ## Integration with Other Oshun Domains `@oya/core` ships TypeScript cross-domain adapter modules (`*-integration.ts`) that define the typed boundary toward other Oshun domains. The boundary exists because Oya owns aerial autonomy primitives — it does not own 3D reconstruction, creative studio workflows, AI consciousness, or build quality assessment. Those domains own their industry-specific business features and consume drone data through typed adapters. The concrete runtime wiring is part of the planned platform-bus expansion; the `*-integration.ts` modules establish the contract today. - **`@maya/mirror` Photogrammetry** — Drone-captured image sets feed into Maya's 3D Gaussian Splatting reconstruction pipeline via `@oya/core`'s `FlightPlan` and geotagged capture metadata types. Maya owns the reconstruction algorithm; Oya owns the capture geometry. - **`@isis/*` Generation** (`isis-integration.ts`) — Route generation jobs to Isis (e.g. generating orthophoto mosaics from collected imagery, or creating 3D assets from LiDAR point clouds). Isis owns the generation pipeline; Oya routes jobs to it. - **`@lilith/*` AI Consciousness** (`lilith-integration.ts`) — Natural language mission planning: the Lilith AI consciousness layer accepts user intent in natural language and converts it to typed `Mission` objects via `extractMissionIntent`. Lilith owns the language understanding; Oya owns the resulting mission type. - **`@sophia/*` Knowledge** (`sophia-integration.ts`) — Sophia provides regulatory knowledge (airspace rules, weather interpretation, equipment specifications) to inform mission planning decisions. Sophia owns the knowledge graph; Oya queries it for planning inputs. - **`@aja/*` Integration** (`aja-integration.ts`) — Aja motion-capture bridge: pose-data forwarding, real-time motion streaming, and skeleton-format conversion from drone-captured human-pose estimation. - **`@aphrodite/*` Streaming** (`aphrodite-integration.ts`) — Live drone video streaming integrated with Aphrodite's creator economy platform for aerial live streaming. - **`@yemaya/*` Creative Studio** (`yemaya-integration.ts`) — Mission and capture metadata surfaced in Yemaya's creative project management for cinematography productions. - **`@bellona/*` Build Engine** (`bellona-integration.ts`) — Drone inspection data (LiDAR, thermal, visual) fed into Bellona's build quality and asset pipeline for construction site monitoring. - **`@oshun/storage`** _(planned)_ — Captured media and telemetry archives stored via `@oshun/storage` with drone GPS coordinates and mission metadata attached. `@oya/core` declares no `@oshun/*` dependency today; this wiring is planned. - **`@oshun/event-bus`** _(planned)_ — Mission events (started, waypoint reached, completed, emergency declared) published to the event bus for cross-domain reaction. - **`@oshun/metrics`** _(planned)_ — Fleet telemetry metrics exported for operational dashboards. `observability.ts` already produces Prometheus-compatible metrics in `@oya/core`; exporting them through `@oshun/metrics` is the planned step. ## Gaia Weather and Climate Integration _(planned)_ Phase 175 plans to add Gaia cyclone, wind, precipitation, lightning, and severe-weather products as inputs to Oya mission planning. The boundary between the two domains is clear: Oya owns flight authorization, mission execution, and drone safety policy; Gaia owns forecast generation and verification. Oya would consume Gaia products for no-fly cones, hurricane-hunter drone-swarm tasking, evacuation-swarm planning, outdoor mission gating, and weather-aware fleet safety. No Gaia adapter exists in `libs/oya/` today.