R2D2-Holocron/holocron-cesium

🎯 NATO Tactical Display - Cesium.js + MQTT

A real-time 3D tactical display system built with Cesium.js and MQTT for visualizing military assets on a global map.

Features

• ✅ Real-time 3D visualization using Cesium.js
• ✅ MQTT integration for live asset updates
• ✅ WebSocket bridge for browser-to-MQTT communication
• ✅ Dockerized deployment - runs with single command
• ✅ Geographic accuracy - native lat/lon/altitude support
• ✅ Asset tracking - drones, ships, ground vehicles
• ✅ Color-coded assets - yellow (air), blue (surface), green (ground)
• ✅ Asset trails - 60-second position history
• ✅ Auto cleanup - removes stale assets
• ✅ Test publisher included - generate sample data

Architecture

┌─────────────────┐
│   MQTT Broker   │
│   (Mosquitto)   │
│   Port: 1883    │
└────────┬────────┘
         │
         │ MQTT Protocol
         │
┌────────▼────────┐
│  WebSocket      │
│  Bridge Server  │
│  (Node.js)      │
│  Port: 9001     │
└────────┬────────┘
         │
         │ WebSocket
         │
┌────────▼────────┐
│  Cesium.js      │
│  Web Client     │
│  Port: 3000     │
└─────────────────┘

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Internet connection (for Cesium.js CDN)

1. Clone/Download

cd holocron-cesium

2. Start the Stack

# Start all services
docker-compose up -d

# Or with test data publisher
docker-compose --profile testing up -d

3. Access the Display

Open your browser to:

• Tactical Display: http://localhost:3000
• Health Check: http://localhost:3000/health

4. Verify MQTT

# Check logs
docker-compose logs -f tactical-display

# Expected output:
# ✓ Connected to MQTT broker at mqtt://mosquitto:1883
# ✓ Subscribed to r2d2/holocron/assets/status/#

Usage

Viewing Assets

1. Open http://localhost:3000
2. Assets will appear automatically as MQTT messages arrive
3. Click on asset names in the list to zoom to them
4. Use mouse to pan/zoom the 3D globe:
   • Left drag: Rotate
   • Right drag: Pan
   • Scroll: Zoom
   • Middle drag: Tilt

Publishing Asset Data

Method 1: Use Test Publisher (Included)

# Start with test data
docker-compose --profile testing up -d

# You'll see 5 test assets moving around Europe

Method 2: Manual MQTT Publish

Topic is set by .env: MQTT_TOPIC_PREFIX/assets/status/<asset-id>. Default prefix is r2d2/holocron, so the full topic is r2d2/holocron/assets/status/drone-001.

# Install mosquitto-clients
apt-get install mosquitto-clients  # Ubuntu/Debian
brew install mosquitto              # macOS

# Publish asset position (use your MQTT_TOPIC_PREFIX from .env; default: r2d2/holocron)
mosquitto_pub -h localhost -t "r2d2/holocron/assets/status/drone-001" -m '{
  "body": {
    "identifier": "drone-001",
    "description": {
      "symbol_set": "SymbolSetEnum_AIR",
      "name": "Reaper UAV"
    },
    "pose": {
      "position": {
        "latitude_longitude_altitude": {
          "latitude": 46.2044,
          "longitude": 6.1432,
          "altitude": [{"value": 5000}]
        }
      }
    },
    "velocity": {
      "speed_and_rate": {
        "heading": 45,
        "speed": 250
      }
    }
  }
}'

Method 3: From Your Existing System

Connect your MQTT publisher to:

• Host: localhost
• Port: 1883
• Topic: <MQTT_TOPIC_PREFIX>/assets/status/<asset-id> (default: r2d2/holocron/assets/status/<asset-id>)
• Format: See message format below

Message Format

{
  "body": {
    "identifier": "unique-asset-id",
    "description": {
      "symbol_set": "SymbolSetEnum_AIR | SymbolSetEnum_SEA_SURFACE | SymbolSetEnum_LAND_UNIT",
      "name": "Display name"
    },
    "pose": {
      "position": {
        "latitude_longitude_altitude": {
          "latitude": 46.2044,
          "longitude": 6.1432,
          "altitude": [{ "value": 5000 }]
        }
      }
    },
    "velocity": {
      "speed_and_rate": {
        "heading": 45,
        "speed": 250
      }
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Configuration

Environment Variables

Copy .env.example to .env and set:

Variable	Description	Default
MQTT_BROKER	MQTT broker URL	mqtt://mosquitto:1883
MQTT_TOPIC_PREFIX	Topic prefix for asset status (e.g. r2d2/holocron → topics r2d2/holocron/assets/status/#)	r2d2/holocron
PORT	HTTP server port	3000
WS_PORT	WebSocket port	9001

docker-compose loads .env and passes these into the tactical-display and mqtt-publisher services. Do not commit .env.

Cesium Ion Token (Optional)

For premium Cesium features (high-res terrain, imagery):

1. Get free token at https://cesium.com/ion/signup
2. Edit public/app.js:

   const CESIUM_TOKEN = "your-token-here";
   

MQTT Broker

Edit mosquitto/config/mosquitto.conf for custom MQTT settings.

Development

Start Testing

# Install dependencies
cd test-publisher && npm install
node test-publisher-catl.js

Project Structure

holocron-cesium/
├── public/
│   ├── index.html          # Main web interface
│   └── app.js              # Cesium.js application
├── test-publisher/
│   ├── publisher.js        # Test MQTT publisher
│   ├── test-publisher-catl.js        # Test MQTT publisher
│   └── package.json
├── mosquitto/
│   └── config/
│       └── mosquitto.conf  # MQTT broker config
├── server.js               # WebSocket bridge server
├── package.json
├── Dockerfile
├── docker-compose.yml
└── README.md

Troubleshooting

Assets Not Appearing

1. Check MQTT connection:

   docker-compose logs tactical-display
   

2. Verify messages are being published:

   mosquitto_sub -h localhost -t "r2d2/holocron/assets/status/#" -v
   

3. Check browser console (F12) for errors

WebSocket Connection Failed

• Ensure port 9002 is not in use
• Check firewall settings
• View browser console for exact error

Docker Issues

# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# View logs
docker-compose logs -f

# Restart services
docker-compose restart

Ports Used

Port	Service	Description
3000	HTTP	Web interface
9002	WebSocket	MQTT bridge (mapped from internal 9001)
1883	MQTT	MQTT broker

---

Ready to deploy tactical displays! 🚀