Skip to content

Latest commit

 

History

History
206 lines (149 loc) · 7.32 KB

README.md

File metadata and controls

206 lines (149 loc) · 7.32 KB

Stratux ADS-B Message Simulator

A Go application that simulates ADS-B (Automatic Dependent Surveillance-Broadcast) messages from a Stratux receiver. It reads historical traffic data from MongoDB, replays it at a configurable rate, and publishes messages to a Kafka topic with timestamps adjusted to the current time.

Features

  • Reads documents from MongoDB stratux_raw collection (or configurable database/collection)
  • Streams messages in ascending timestamp order
  • Publishes to Kafka at a user-defined rate (messages per second)
  • Loops from the beginning when all documents have been sent
  • Automatically starts and stops Kafka in a local Docker container
  • Caps Kafka topic size at 1GB when producing faster than consuming
  • Graceful shutdown on SIGINT/SIGTERM or after the specified duration

Prerequisites

  • Go 1.23+ – required only when building from source
  • MongoDB – running locally or remotely with the stratux_raw collection populated
  • Docker – with Docker Compose plugin (for Kafka)

Sample data

Sample ADS-B and aircraft registration data is available in collection_data/. The files are gzip-compressed; decompress them before importing:

cd collection_data
gunzip -k stratux_raw.json.gz registered_aircraft.json.gz
cd ..

Then import into MongoDB using mongoimport:

# Import stratux_raw (ADS-B messages for the streamer)
mongoimport --uri="mongodb://localhost:27017" --db=Stratux --collection=stratux_raw \
  --file=collection_data/stratux_raw.json

# Import registered_aircraft (lookup data for the Java processors)
mongoimport --uri="mongodb://localhost:27017" --db=Stratux --collection=registered_aircraft \
  --file=collection_data/registered_aircraft.json

Adjust --uri and --db if your setup differs. Add --drop to replace existing collections.

Configuration

Configuration is loaded from environment variables, which may be defined in a .env file in the project directory.

Variable Required Default Description
MONGO_URI Yes — MongoDB connection string (e.g. mongodb://localhost:27017)
MONGO_DATABASE No Stratux MongoDB database name
MONGO_COLLECTION No stratux_raw MongoDB collection name
KAFKA_BROKER No localhost:9092 Kafka broker address
KAFKA_TOPIC No stratux Kafka topic name

Obtaining the executable

You can run the streamer in either of two ways:

  • Pre-built executable: Use an executable from distributions/ for your platform (e.g. stratux-simulator-linux-amd64, stratux-simulator-darwin-arm64). Copy it to this directory as stratux-simulator or run it from here so .env and docker-compose.yml are in the working directory.
  • Build from source: Run go build -o stratux-simulator . (requires Go 1.23+).

Building

go build -o stratux-simulator .

Running

./stratux-simulator [flags]

Command-line flags

Flag Default Description
--rate 1.0 Messages per second to emit
--duration 0 Number of seconds to run (0 = run until terminated)

Examples

# Run indefinitely at 10 messages per second (Ctrl+C to stop)
./stratux-simulator --rate 10

# Run for 60 seconds at 10 messages per second
./stratux-simulator --rate 10 --duration 60

# Run for 5 minutes at 50 messages per second
./stratux-simulator --rate 50 --duration 300

What happens when you run

  1. The application loads .env (if present) and parses flags
  2. It starts Kafka via docker compose up -d
  3. It waits for Kafka to be reachable, then creates the topic (if it does not exist)
  4. It connects to MongoDB and begins streaming documents
  5. Each document’s timestamp is replaced with the current time before publishing to Kafka
  6. When the run duration expires or you press Ctrl+C, it stops Kafka with docker compose down and exits

Installing Docker on Linux

The application requires Docker and the Docker Compose plugin. Choose the instructions for your distribution.

Fedora

Option 1: Docker’s official repository (recommended)

# Remove conflicting packages (if any)
sudo dnf remove -y docker docker-client docker-client-latest docker-common \
  docker-latest docker-latest-logrotate docker-logrotate docker-selinux \
  docker-engine-selinux docker-engine 2>/dev/null || true

# Install prerequisites and add Docker repository
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# Install Docker Engine and Compose plugin
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker
sudo systemctl enable --now docker

# Add your user to the docker group (to run without sudo)
sudo usermod -aG docker $USER
newgrp docker

Option 2: Fedora’s default packages

sudo dnf install -y docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

Debian and Ubuntu (Debian-based)

Option 1: Docker’s official repository (recommended)

# Remove conflicting packages (if any)
sudo apt remove -y docker docker-engine docker.io containerd runc 2>/dev/null || true

# Install prerequisites
sudo apt update
sudo apt install -y ca-certificates curl gnupg

# Add Docker’s GPG key and repository
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# $ID is "debian" or "ubuntu" depending on your distro
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo $ID) $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Compose plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (to run without sudo)
sudo usermod -aG docker $USER
newgrp docker

Option 2: Debian/Ubuntu default packages

sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

Note: With the default packages, you may need to use docker-compose (with a hyphen) instead of docker compose. The application expects docker compose; if your system only provides docker-compose, you can create an alias: alias docker-compose='docker compose' or install the Compose plugin from Docker’s repository.

Verify installation

docker --version
docker compose version

Project structure

.
├── main.go            # Application entry point
├── go.mod             # Go module definition
├── go.sum             # Go module checksums
├── docker-compose.yml # Kafka service definition
├── .env               # Environment configuration (create with variables from Configuration table above)
├── collection_data/   # Sample ADS-B and aircraft registration data (.json.gz files)
├── distributions/     # Pre-built executables for various platforms
└── README.md          # This file

License

See the project repository for license information.