185 lines
3.9 KiB
Markdown
185 lines
3.9 KiB
Markdown
# Communication Protocol (GPS-Denied)
|
|
|
|
Message formats for GPS-denied drone operation with camera.
|
|
|
|
## Drone Commands
|
|
|
|
```json
|
|
{
|
|
"thrust": 0.5,
|
|
"pitch": 0.1,
|
|
"roll": -0.2,
|
|
"yaw": 0.0
|
|
}
|
|
```
|
|
|
|
| Field | Range | Description |
|
|
|-------|-------|-------------|
|
|
| `thrust` | ±1.0 | Vertical thrust (positive = up) |
|
|
| `pitch` | ±0.5 | Forward/backward tilt |
|
|
| `roll` | ±0.5 | Left/right tilt |
|
|
| `yaw` | ±0.5 | Rotation |
|
|
|
|
---
|
|
|
|
## Drone Telemetry
|
|
|
|
Published on `/drone/telemetry`. **No GPS position available.**
|
|
|
|
```json
|
|
{
|
|
"imu": {
|
|
"orientation": {"roll": 0.0, "pitch": 0.0, "yaw": 0.0},
|
|
"angular_velocity": {"x": 0.0, "y": 0.0, "z": 0.0},
|
|
"linear_acceleration": {"x": 0.0, "y": 0.0, "z": 9.81}
|
|
},
|
|
"altimeter": {
|
|
"altitude": 5.0,
|
|
"vertical_velocity": -0.1
|
|
},
|
|
"velocity": {"x": 0.0, "y": 0.0, "z": -0.1},
|
|
"landing_pad": {
|
|
"relative_x": 0.5,
|
|
"relative_y": -0.2,
|
|
"distance": 4.5,
|
|
"confidence": 0.85
|
|
},
|
|
"camera": {
|
|
"width": 320,
|
|
"height": 240,
|
|
"fov": 60.0,
|
|
"image": "<base64 encoded JPEG>"
|
|
},
|
|
"landed": false,
|
|
"timestamp": 1.234
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Sensor Details
|
|
|
|
### IMU
|
|
Always available.
|
|
|
|
| Field | Unit | Description |
|
|
|-------|------|-------------|
|
|
| `orientation.roll/pitch/yaw` | radians | Euler angles |
|
|
| `angular_velocity.x/y/z` | rad/s | Rotation rates |
|
|
| `linear_acceleration.x/y/z` | m/s² | Acceleration |
|
|
|
|
### Altimeter
|
|
Always available.
|
|
|
|
| Field | Unit | Description |
|
|
|-------|------|-------------|
|
|
| `altitude` | meters | Height above ground |
|
|
| `vertical_velocity` | m/s | Vertical speed |
|
|
|
|
### Velocity
|
|
Estimated from optical flow.
|
|
|
|
| Field | Unit | Description |
|
|
|-------|------|-------------|
|
|
| `x` | m/s | Forward velocity |
|
|
| `y` | m/s | Lateral velocity |
|
|
| `z` | m/s | Vertical velocity |
|
|
|
|
### Landing Pad Detection
|
|
**May be null if pad not visible!**
|
|
|
|
| Field | Unit | Description |
|
|
|-------|------|-------------|
|
|
| `relative_x` | meters | Forward/back offset (body frame) |
|
|
| `relative_y` | meters | Left/right offset (body frame) |
|
|
| `distance` | meters | Vertical distance to pad |
|
|
| `confidence` | 0-1 | Detection confidence |
|
|
|
|
### Camera
|
|
Always available.
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `width` | Image width in pixels |
|
|
| `height` | Image height in pixels |
|
|
| `fov` | Horizontal field of view in degrees |
|
|
| `image` | Base64 encoded JPEG (or null) |
|
|
|
|
---
|
|
|
|
## Using the Camera Image
|
|
|
|
The camera provides a base64-encoded JPEG image of what the drone sees looking down.
|
|
|
|
### Decoding the Image (Python)
|
|
|
|
```python
|
|
import base64
|
|
from PIL import Image
|
|
import io
|
|
|
|
def decode_camera_image(telemetry):
|
|
camera = telemetry.get('camera', {})
|
|
image_b64 = camera.get('image')
|
|
|
|
if image_b64 is None:
|
|
return None
|
|
|
|
# Decode base64 to bytes
|
|
image_bytes = base64.b64decode(image_b64)
|
|
|
|
# Load as PIL Image
|
|
image = Image.open(io.BytesIO(image_bytes))
|
|
|
|
return image
|
|
```
|
|
|
|
### Using with OpenCV
|
|
|
|
```python
|
|
import base64
|
|
import cv2
|
|
import numpy as np
|
|
|
|
def decode_camera_image_cv2(telemetry):
|
|
camera = telemetry.get('camera', {})
|
|
image_b64 = camera.get('image')
|
|
|
|
if image_b64 is None:
|
|
return None
|
|
|
|
# Decode base64 to bytes
|
|
image_bytes = base64.b64decode(image_b64)
|
|
|
|
# Convert to numpy array
|
|
nparr = np.frombuffer(image_bytes, np.uint8)
|
|
|
|
# Decode JPEG
|
|
image = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
|
|
|
|
return image
|
|
```
|
|
|
|
### Image Properties
|
|
|
|
- **Resolution**: 320 x 240 pixels
|
|
- **Format**: JPEG (quality 70)
|
|
- **FOV**: 60 degrees
|
|
- **Direction**: Downward-facing
|
|
- **Update Rate**: ~5 Hz (every 5th telemetry frame)
|
|
|
|
---
|
|
|
|
## Rover Telemetry
|
|
|
|
For internal use by RoverController.
|
|
|
|
```json
|
|
{
|
|
"position": {"x": 1.5, "y": 0.8, "z": 0.15},
|
|
"velocity": {"x": 0.3, "y": 0.4, "z": 0.0},
|
|
"pattern": "circular",
|
|
"timestamp": 1.234
|
|
}
|
|
```
|