Airport Digital Twin Deployment

A digital twin deployment for airport operations management, leveraging FIWARE Orion Context Broker, Apache NiFi/Draco for data processing, and real-time web visualization.

If you use or base your work on this project, please cite the following article:

@article{CONDE2022101723,
title = {Applying digital twins for the management of information in turnaround event operations in commercial airports},
journal = {Advanced Engineering Informatics},
volume = {54},
pages = {101723},
year = {2022},
issn = {1474-0346},
doi = {https://doi.org/10.1016/j.aei.2022.101723},
url = {https://www.sciencedirect.com/science/article/pii/S1474034622001811},
author = {Javier Conde and Andres Munoz-Arcentales and Mario Romero and Javier Rojo and Joaquín Salvachúa and Gabriel Huecas and Álvaro Alonso},
keywords = {Aviation, Flight turnaround events, Digital twin, Internet of Things, Data modelling, Big data},
}

Overview

This project implements a digital twin infrastructure for airport operations, providing real-time data integration, processing, and visualization capabilities. It integrates multiple data sources including flight information, turnaround events, and aircraft data using standardized NGSI-v2 context information management.

Key Capabilities

Real-time flight and aircraft tracking
Turnaround event processing
NGSI-v2 compliant data management
Integration with external systems (Chroma, Assaia, Firehose)
Web-based real-time dashboard
Automated data processing pipelines

Features

Real-time Context Management: FIWARE Orion Context Broker for managing airport entities
Data Processing Pipelines: Apache NiFi/Draco with custom processors for NGSI data
Persistent Storage: MongoDB for historical data
Web Interface: Real-time web client with Socket.IO for live updates
Multi-source Integration: Connectors for Chroma, Assaia, and Firehose systems
Containerized Deployment: Full Docker Compose orchestration
Health Monitoring: Built-in health checks for all services

Architecture

┌─────────────────┐
│  External APIs  │
│ (Chroma/Assaia/ │
│   Firehose)     │
└────────┬────────┘
         │
         v
┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
│   Draco/NiFi    │────>│ Orion Context│────>│   MongoDB    │
│  (Processing)   │     │    Broker    │     │  (Storage)   │
└─────────────────┘     └──────┬───────┘     └──────────────┘
                               │
                               v
                        ┌──────────────┐
                        │ Web Client   │
                        │ (Dashboard)  │
                        └──────────────┘

Component Interaction

Data Ingestion: Draco processors fetch data from external APIs
Context Management: NGSI entities stored in Orion Context Broker
Persistence: Subscriptions trigger data storage in MongoDB
Visualization: Web client subscribes to Orion for real-time updates

FAIR Principles Compliance

This project adheres to FAIR (Findable, Accessible, Interoperable, Reusable) principles:

Findable

Unique Identifier: GitHub repository URL
Rich Metadata: Comprehensive documentation in README and code comments
Searchable: Tagged with relevant keywords (FIWARE, NGSI, airport, digital twin)
Indexed: Available in public GitHub repository

Accessible

Open Access: Publicly available repository
Standard Protocol: HTTPS/HTTP, Docker, standard APIs
Authentication: Configurable API authentication for external services
Long-term: Docker images ensure reproducibility

Interoperable

Standard Format: NGSI-v2 context information format
Qualified References: Uses FIWARE standard data models
Open APIs: RESTful APIs following FIWARE specifications
Vocabularies: OMA NGSI standard vocabulary

Reusable

Clear License: Apache 2.0 License
Provenance: Version controlled with Git
Documentation: Comprehensive setup and usage instructions
Standards: FIWARE and OMA NGSI community standards

Prerequisites

Before deploying this project, ensure you have the following installed:

Docker (version 20.10 or higher)
```
docker --version
```
Docker Compose (version 1.29 or higher)
```
docker-compose --version
```
Bash (for deployment scripts)
Access Credentials for external systems:
- Chroma API credentials
- Assaia API credentials
- Firehose connection details

System Requirements

RAM: Minimum 8GB (16GB recommended)
Disk Space: Minimum 10GB free
Network: Internet connection for pulling Docker images and accessing external APIs
OS: Linux, macOS, or Windows with WSL2

Installation

1. Clone the Repository

git clone <repository-url>
cd arport_twin_deployment

2. Configure Environment

Copy the environment template and configure your settings:

cp .env.template .env

Edit the .env file with your specific configuration (see Configuration section).

3. Make Scripts Executable

chmod +x deployment.sh
chmod +x scripts/*.sh
chmod +x draco/*.sh

Configuration

Environment Variables

Edit the .env file to configure all components:

Orion Context Broker

ORION_PORT=1026              # Orion API port
ORION_VERSION=2.5.0          # FIWARE Orion version

Draco/NiFi Data Processor

DRACO_VERSION=1.3.1          # Draco version
DRACO_WEB_PORT=9090          # NiFi web UI port
DRACO_PORT=5050              # Data ingestion port

MongoDB

MONGO_PORT=27018             # MongoDB port
MONGO_VERSION=3.6            # MongoDB version
MONGO_ROOT_USERNAME=root     # Admin username
MONGO_ROOT_PASSWORD=example  # Admin password (change in production!)

Web Client

WEB_CLIENT_PORT=3000         # Web dashboard port

External API Integrations

Chroma Integration:

CHROMA_REMOTE_URL_FLIGHT=https://your-chroma-flight-api.com
CHROMA_REMOTE_URL_AIRPORT=https://your-chroma-airport-api.com
CHROMA_REMOTE_URL_AIRLINE=https://your-chroma-airline-api.com
CHROMA_REMOTE_USERNAME=your_username
CHROMA_REMOTE_PASSWORD=your_password
CHROMA_TOKEN=your_api_token

Assaia Integration:

ASSAIA_REMOTE_URL_FLIGHT_TURN_AROUND=https://your-assaia-api.com
ASSAIA_REMOTE_USERNAME=your_username
ASSAIA_REMOTE_PASSWORD=your_password
ASSAIA_TOKEN=your_api_token

Firehose Integration:

FIREHOSE_HOSTNAME=your-firehose-host.net
FIREHOSE_PORT=55
FIREHOSE_CREDENTIALS={"username":"your_user","password":"your_pass"}

Security Recommendations

⚠️ Important:

Change default MongoDB credentials in production
Use strong passwords and API tokens
Never commit .env file to version control
Use secrets management for production deployments

Usage

Starting the System

Initial Deployment (creates containers and subscriptions):

./deployment.sh create

This command will:

Build and start all Docker containers
Wait for Orion Context Broker to be healthy
Create necessary NGSI subscriptions
Wait for Draco to be ready
Deploy NiFi data processing templates

Managing the Deployment

Stop containers (preserves data):

./deployment.sh stop

Restart containers (with existing data):

./deployment.sh restart

Destroy deployment (removes all containers and data):

./deployment.sh destroy
# You will be prompted to confirm data deletion

Accessing Services

Once deployed, access the following services:

Service	URL	Description
Orion Context Broker	`http://localhost:1026`	NGSI-v2 API endpoint
Draco/NiFi UI	`http://localhost:9090/nifi`	Data processing pipeline UI
Web Dashboard	`http://localhost:3000`	Real-time visualization
MongoDB	`localhost:27018`	Database (requires auth)

Verifying Deployment

Check Orion version and status:

curl http://localhost:1026/version

Check health of all services:

docker-compose ps

View logs for specific service:

docker-compose logs -f orion
docker-compose logs -f draco
docker-compose logs -f web

API Documentation

Orion Context Broker (NGSI-v2)

Get All Entities

curl -X GET 'http://localhost:1026/v2/entities' \
  -H 'Accept: application/json'

Get Specific Entity

curl -X GET 'http://localhost:1026/v2/entities/{entity_id}' \
  -H 'Accept: application/json'

Create Entity

curl -X POST 'http://localhost:1026/v2/entities' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "Flight001",
    "type": "Flight",
    "flightNumber": {"type": "Text", "value": "AA100"},
    "status": {"type": "Text", "value": "OnTime"}
  }'

Update Entity Attributes

curl -X PATCH 'http://localhost:1026/v2/entities/{entity_id}/attrs' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": {"type": "Text", "value": "Delayed"}
  }'

Query Entities

curl -X GET 'http://localhost:1026/v2/entities?type=Flight&q=status==Delayed' \
  -H 'Accept: application/json'

For complete NGSI-v2 API documentation, visit: FIWARE NGSI-v2 Specification

Web Client API

The web client exposes Socket.IO endpoints for real-time updates:

Connect: http://localhost:3000
Events: flight-update, aircraft-update, turnaround-event

Data Models

Flight Entity

{
  "id": "Flight:AA100:2026-02-21",
  "type": "Flight",
  "flightNumber": {"type": "Text", "value": "AA100"},
  "airline": {"type": "Text", "value": "American Airlines"},
  "aircraft": {"type": "Relationship", "value": "Aircraft:N12345"},
  "origin": {"type": "Text", "value": "JFK"},
  "destination": {"type": "Text", "value": "LAX"},
  "scheduledDeparture": {"type": "DateTime", "value": "2026-02-21T10:00:00Z"},
  "actualDeparture": {"type": "DateTime", "value": "2026-02-21T10:05:00Z"},
  "status": {"type": "Text", "value": "Departed"}
}

Aircraft Entity

{
  "id": "Aircraft:N12345",
  "type": "Aircraft",
  "registration": {"type": "Text", "value": "N12345"},
  "model": {"type": "Text", "value": "Boeing 737-800"},
  "airline": {"type": "Text", "value": "American Airlines"}
}

TurnAroundEvent Entity

{
  "id": "TurnAroundEvent:001",
  "type": "TurnAroundEvent",
  "flight": {"type": "Relationship", "value": "Flight:AA100:2026-02-21"},
  "eventType": {"type": "Text", "value": "Boarding"},
  "timestamp": {"type": "DateTime", "value": "2026-02-21T09:30:00Z"},
  "status": {"type": "Text", "value": "InProgress"}
}

Components

Directory Structure

arport_twin_deployment/
├── deployment.sh              # Main deployment script
├── deployment.py              # Python deployment utilities
├── docker-compose.yml         # Container orchestration
├── .env.template              # Environment configuration template
├── README.md                  # This file
├── draco/                     # NiFi/Draco data processor
│   ├── Dockerfile
│   ├── runDraco.py           # Draco automation script
│   ├── processors/           # Custom NGSI processors
│   └── templates/            # NiFi flow templates
├── scripts/                   # Deployment automation
│   ├── create_subscriptions.py
│   └── wait_for_healthy.py
└── web/                       # Web client dashboard
    ├── app.js                # Express server
    ├── index.html            # Frontend
    ├── controllers/          # API controllers
    └── lib/                  # NGSI client library

Draco/NiFi Templates

Located in draco/templates/:

Assaia-NGSI-Orion.xml: Assaia turnaround event integration
Chroma-NGSI-Orion.xml: Chroma flight data integration
Firehose-NGSI-Orion.xml: Firehose data stream integration
ORION-TO-MONGO-2.xml: Orion to MongoDB persistence
Delete-Flights-And-Relationships.xml: Cleanup utilities

Custom NiFi Processors

nifi-ngsi-nar-1.3.4.nar: NGSI-v2 protocol support
nifi-tcp-client-nar-1.0-SNAPSHOT.nar: TCP client for custom integrations

Troubleshooting

Common Issues

Containers fail to start

# Check container logs
docker-compose logs

# Ensure ports are not in use
lsof -i :1026  # Orion
lsof -i :9090  # Draco
lsof -i :3000  # Web client
lsof -i :27018 # MongoDB

Orion not accessible

# Check Orion health
docker-compose exec orion curl -s http://localhost:1026/version

# Restart Orion
docker-compose restart orion

Subscriptions not created

# Manually run subscription script
source scripts/create_subscriptions.sh
create_subscriptions

MongoDB connection issues

# Test MongoDB connection
docker-compose exec mongo mongo -u root -p example --eval "db.version()"

# Check MongoDB logs
docker-compose logs mongo

Draco/NiFi not loading templates

# Check Draco logs
docker-compose logs draco script-draco

# Manually upload templates via NiFi UI
# Access: http://localhost:9090/nifi

Getting Help

If you encounter issues:

Check service logs: docker-compose logs [service_name]
Verify .env configuration
Ensure all prerequisites are met
Check firewall/network settings
Review FIWARE Orion documentation
Open an issue in the repository

Contributing

We welcome contributions! To contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style and conventions
Add tests for new features
Update documentation for changes
Ensure Docker builds succeed
Test deployment scripts thoroughly

Code of Conduct

Be respectful and inclusive
Provide constructive feedback
Focus on collaboration and learning

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Third-Party Components

FIWARE Orion: AGPL v3
Apache NiFi/Draco: Apache 2.0
MongoDB: SSPL

Citation

If you use this project in your research or production, please cite:

@software{airport_digital_twin,
  title={Airport Digital Twin Deployment},
  author={Your Organization},
  year={2026},
  url={https://github.com/your-org/arport_twin_deployment},
  version={1.0.0}
}

Related Publications

FIWARE NGSI-v2 Specification: https://fiware.github.io/specifications/ngsiv2/stable/
Digital Twin Architecture for Airports: [Add your publications]

Support

Documentation Resources

Contact

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@your-organization.com

Version Information

Current Version: 1.0.0
Last Updated: February 21, 2026
Compatibility: Docker 20.10+, Docker Compose 1.29+

Metadata

Keywords: FIWARE, NGSI, Airport, Digital Twin, IoT, Context Broker, Real-time, Docker
Category: Digital Twin Infrastructure
Domain: Aviation, Airport Operations
Standards: NGSI-v2, OMA NGSI, FIWARE
Status: Active Development

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
draco		draco
scripts		scripts
web		web
.env.template		.env.template
.gitignore		.gitignore
README.md		README.md
deployment.py		deployment.py
deployment.sh		deployment.sh
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation