{"id":49704911,"url":"https://github.com/sohooo/droneops-sim","last_synced_at":"2026-05-08T09:49:23.740Z","repository":{"id":306426377,"uuid":"1025985616","full_name":"sohooo/droneops-sim","owner":"sohooo","description":"Story-driven drone swarms that react to enemy maneuvers, chart evolving missions, and stream every dramatic turn to GreptimeDB or your console.","archived":false,"fork":false,"pushed_at":"2025-09-25T07:03:37.000Z","size":12406,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-25T09:07:10.453Z","etag":null,"topics":["drones","simulation","telemetry"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sohooo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-25T06:07:10.000Z","updated_at":"2025-09-25T07:03:42.000Z","dependencies_parsed_at":"2025-07-25T17:48:30.856Z","dependency_job_id":"c8335446-90b5-4e2a-bbe1-2e4cab14b323","html_url":"https://github.com/sohooo/droneops-sim","commit_stats":null,"previous_names":["sohooo/droneops-sim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sohooo/droneops-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohooo%2Fdroneops-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohooo%2Fdroneops-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohooo%2Fdroneops-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohooo%2Fdroneops-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sohooo","download_url":"https://codeload.github.com/sohooo/droneops-sim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohooo%2Fdroneops-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32775706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drones","simulation","telemetry"],"created_at":"2026-05-08T09:49:22.928Z","updated_at":"2026-05-08T09:49:23.716Z","avatar_url":"https://github.com/sohooo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DroneOps-Sim\n\n\u003e \"Story-driven drone swarms that react to enemy maneuvers, chart evolving missions, and stream every dramatic turn to GreptimeDB or your console.\"\n\n## Overview\n\n**DroneOps-Sim** is a lightweight Go-based simulator that generates realistic drone telemetry for demonstration, testing, and learning purposes.\n\nIt supports:\n\n- **Multiple drone fleets** (small FPV, medium UAV, large UAV)\n- **Randomized movement patterns** (random walk)\n- **Battery drain and failure simulation**\n- **Configurable sensor errors, communication dropouts, and battery anomalies**\n- **Output to GreptimeDB** using its gRPC ORM interface **or** to STDOUT for quick demos\n- **Mission scenarios** scripted with a lightweight DSL for phases and enemy objectives\n- **Observer dashboard** for stepping through mission events, switching perspectives, and injecting commands\n- **Swarm-event logs** for follower assignments, reassignments, and formation changes\n- **Per-tick simulation state metrics** including communication reliability, sensor noise, weather impact, and chaos-mode status\n- **Interactive TUI** with hotkeys (`q` quit, `w` wrap, `s` scroll, `e` spawn enemy via `type,lat,lon,alt` + `Enter`; dialog auto-fills near the latest drone position for quick spawning, `E` edit/remove enemy via `id,status|delete`, `t` toggle summary footer (enabled by default), `p` toggle a battlefield map with gridlines, north indicator, scale bar, mission-colored drone arrows shaded by battery level with altitude-aware shapes, distinct enemy status markers, optional detection range circles and recent drone trails, `h/?` help overlay)\n  The map uses Unicode symbols by default; set `TUI_SYMBOLS=ascii` to render with plain ASCII.\n\nThis project was designed to support visualization dashboards (e.g., Grafana Geomap panel) and multi-cluster sync scenarios (mission clusters → command cluster).\n\nFor development and contribution guidelines, see [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).\n\n## Purpose\n\n- Provide a realistic demo data source for telemetry pipelines.\n- Learn and practice:\n  - IoT data modeling for time-series databases\n  - GreptimeDB ingestion (gRPC ORM)\n  - Kubernetes \u0026 Helm deployment\n  - Grafana visualization integration\n- Serve as a foundation for building more complex simulations (patrol routes, mission-based events).\n\n## Configuration\n\nDetailed configuration options are documented in [docs/configuration.md](docs/configuration.md).\nSee [docs/swarm-response.md](docs/swarm-response.md) for how drone swarms react to enemy detections.\nScenarios can be authored using the [Scenario DSL](docs/scenario.md) to drive mission phases and triggers.\nCommon narrative patterns such as escort and search-and-rescue are available as built-in [story arcs](docs/story-arcs.md).\nFor tips on shaping these scenarios into compelling presentations, see [docs/demo-best-practices.md](docs/demo-best-practices.md).\n\n## Telemetry Types\n\nThe simulator emits several telemetry streams:\n\n- **Drone Telemetry** – core position and battery data with movement metrics.\n- **Enemy Detection** – reports when drones spot hostile objects.\n- **Swarm Events** – follower assignments, releases, and formation changes.\n- **Simulation State** – per-tick metrics such as communication reliability and sensor noise.\n- **Mission Metadata** – details about active missions and objectives.\n\n### Sample Swarm Event\n\n```json\n{\n  \"cluster_id\": \"mission-01\",\n  \"drone_id\": \"alpha-1\",\n  \"enemy_id\": \"enemy-42\",\n  \"event\": \"follow_assigned\",\n  \"ts\": \"2024-06-24T12:00:00Z\"\n}\n```\n\n### Sample Simulation State\n\n```json\n{\n  \"cluster_id\": \"mission-01\",\n  \"communication_reliability\": 0.97,\n  \"sensor_noise\": 0.02,\n  \"weather_impact\": 0.10,\n  \"ts\": \"2024-06-24T12:00:00Z\"\n}\n```\n\n## Schema Validation (schemas/simulation.cue)\n\nConfiguration is validated at runtime using CUE:\n\ncue vet config/simulation.yaml schemas/simulation.cue\n\n## Entry Point\n\nThe `droneops-sim` binary exposes subcommands:\n\n- `simulate` – run the real-time simulator.\n- `replay` – play back a previously recorded telemetry log.\n\nUse `droneops-sim \u003ccommand\u003e --help` to see all options.\n\n### Simulator Flags\n\n- `--print-only` → Print telemetry JSON to STDOUT (ignores DB)\n- `--config` → Path to YAML config (default: config/simulation.yaml)\n- `--schema` → Path to CUE schema (default: schemas/simulation.cue)\n- `--tick` → Telemetry tick interval (default: 1s)\n- `--log-file` → Optional path to write telemetry and detection logs (JSONL)\n\n### Replay Flags\n\n- `--input` → Path to telemetry log file (required)\n- `--speed` → Playback speed multiplier (default: 1.0)\n- `--print-only` → Print telemetry to STDOUT instead of writing to DB\n\n### Environment Variables\n\nThe simulator can be configured through the following environment variables:\n\n| Variable | Default | Required | Description |\n|----------|---------|----------|-------------|\n| `GREPTIMEDB_ENDPOINT` | _none_ | Yes (for GreptimeDB) | GreptimeDB gRPC endpoint. If unset, telemetry is printed to STDOUT. |\n| `GREPTIMEDB_DATABASE` | `metrics` | No | GreptimeDB database name to write into. |\n| `GREPTIMEDB_TABLE` | `drone_telemetry` | No | Table for drone telemetry records. |\n| `ENEMY_DETECTION_TABLE` | `enemy_detection` | No | Table storing enemy detection events. |\n| `SWARM_EVENT_TABLE` | `swarm_events` | No | Table storing swarm coordination events. |\n| `SIMULATION_STATE_TABLE` | `simulation_state` | No | Table storing per-tick simulation state metrics. |\n| `MISSION_METADATA_TABLE` | `mission_metadata` | No | Table storing mission metadata. |\n| `CLUSTER_ID` | `mission-01` | No | Cluster identity tag added to each telemetry line. |\n| `TICK_INTERVAL` | `1s` | No | Telemetry tick interval (Go duration). Overrides the `--tick` flag. |\n| `ENABLE_DETECTIONS` | `true` | No | Toggle emission of enemy detection stream. |\n| `ENABLE_SWARM_EVENTS` | `true` | No | Toggle emission of swarm event stream. |\n| `ENABLE_MOVEMENT_METRICS` | `true` | No | Toggle emission of movement telemetry. |\n| `ENABLE_SIMULATION_STATE` | `true` | No | Toggle emission of simulation state stream. |\n| `TUI_SYMBOLS` | `unicode` | No | Symbol set for TUI map (\"unicode\" or \"ascii\"). |\n\n## Grafana Dashboard\n\nRender the Grafana dashboards using environment variables and the `make dashboard` command.\n\n```bash\nexport GREPTIMEDB_DATASOURCE_UID=greptime_uid\nexport POSTGRES_DATASOURCE_UID=postgres_uid\nmake dashboard\n```\n\nSee [docs/grafana-dashboard.md](docs/grafana-dashboard.md) for details.\n\n## Quickstart\n\nSee [docs/quickstart.md](docs/quickstart.md) for step-by-step instructions.\n\n## Log Export \u0026 Playback\n\n- Use `--log-file` to export telemetry and enemy detection events as JSONL files.\n  Swarm coordination events are written to a `.swarm` companion file.\n- Replay a recorded mission:\n\n```bash\ndroneops-sim replay --input mission.log --print-only\n```\n\n- Control playback rate using `--speed` (e.g., `--speed 2` for 2x).\n\n## Examples\n\n### STDOUT output\n\nThe simulator first prints the mission metadata and then begins emitting drone\ntelemetry lines. Example mission record:\n\n```json\n{\"id\":\"firewall\",\"name\":\"Operation: Firewall\",\"objective\":\"Defend the area from intrusions.\",\"description\":\"Drones patrol the perimeter to ensure no unauthorized access.\",\"region\":{\"name\":\"central-europe\",\"center_lat\":48.2,\"center_lon\":16.4,\"radius_km\":300}}\n```\n\nExample drone telemetry line:\n\n```json\n{\"cluster_id\":\"mission-01\",\"drone_id\":\"recon-swarm-204951-A\",\"mission_id\":\"m1\",\"lat\":48.19985,\"lon\":16.39983,\"alt\":99.9,\"battery\":99.5,\"status\":\"ok\",\"follow\":false,\"movement_pattern\":\"patrol\",\"speed_mps\":12.3,\"heading_deg\":180,\"previous_position\":{\"lat\":48.19980,\"lon\":16.39980,\"alt\":100},\"synced_from\":\"\",\"synced_id\":\"\",\"synced_at\":\"0001-01-01T00:00:00Z\",\"ts\":\"2025-07-29T20:49:52.332081195Z\"}\n```\n\n## Architecture\n\nThe simulator orchestrates scenario-driven missions, enemy behaviour, and telemetry output using a tick-based loop.\n\n```mermaid\nflowchart TD\n    Scenario[\"Scenario \u0026 Storylines\"] --\u003e Sim[\"Simulator\"]\n    Sim --\u003e Tick((\"Tick Loop\"))\n    Tick --\u003e Enemy[\"Enemy Engine\"]\n    Tick --\u003e Telemetry[\"Telemetry Generator\"]\n    Enemy --\u003e|\"positions \u0026 detections\"| Sim\n    Telemetry --\u003e Writers[\"Telemetry Writers\\n(GreptimeDB, Stdout, File)\"]\n    Telemetry --\u003e Detection[\"Detection Writer\"]\n```\n\n## Grafana Dashboard (Recommended)\n\n- Use the GreptimeDB data source for Grafana.\n- Add a Geomap panel with:\n- lat, lon as coordinates\n- status, battery as extra fields\n- Combine with filters (cluster_id, model) and aggregate views.\n\n## Debugging\n\n- Print mode (--print-only) helps verify telemetry without DB access.\n- Logs:\n- [Simulator] → telemetry generation\n- [GreptimeDBWriter] → DB ingestion results\n- Validate config manually:\n\n```bash\ncue vet config/simulation.yaml schemas/simulation.cue\n```\n\nTest:\n\n```bash\ngo test ./... -v\n```\n\n## Deployment in Kubernetes\n\nFor Helm deployment instructions, see [docs/helm-deployment.md](docs/helm-deployment.md).\n\n## Mission Configuration and Visualization\n\n### Mission Objectives\n\nThe `droneops-sim` project supports mission-based drone operations. Missions are defined in the `missions` section of `config/simulation.yaml` and include:\n\n- **ID**: Unique identifier for the mission.\n- **Name**: Catchy name matching the mission objective (e.g., \"Operation: Firewall\").\n- **Objective**: The main goal of the mission.\n- **Description**: A short story or background for the mission.\n- **Region**: The target area for the mission.\n\nExample mission configuration:\n\n```yaml\nmissions:\n  - id: \"firewall\"\n    name: \"Operation: Firewall\"\n    objective: \"Defend the area from intrusions.\"\n    description: \"Drones patrol the perimeter to ensure no unauthorized access.\"\n    region:\n      name: \"central-europe\"\n      center_lat: 48.2\n      center_lon: 16.4\n      radius_km: 300\n```\n\nExample fleet referencing a mission:\n\n```yaml\nfleets:\n  - name: recon-swarm\n    model: small-fpv\n    mission_id: recon\n    # ... other fleet settings ...\n```\n\nThe `mission_id` field links each fleet to a mission. Once code support is in place, the simulator will use this relationship to spawn fleets for specific missions and tag all emitted telemetry accordingly.\n\n### Integration with Telemetry\n\nEach drone is associated with a mission via the `mission_id` field, enabling:\n\n- **Mission Visualization**: Display mission objectives and regions in Grafana.\n- **Drone Association**: Group and filter drones by mission.\n\n### Grafana Dashboard\n\nThe Grafana dashboard integrates mission data to provide:\n\n- **Mission Objectives**: Display the name, objective, and description.\n- **Region Visualization**: Overlay mission regions on the Geomap panel.\n- **Drone Telemetry**: Filter and group drones by mission.\n- **Simulation State Panels**: Track communication reliability, sensor noise trends, and chaos-mode indicators over time.\n\n### Program Logic\n\nOn startup, the program:\n\n1. Loads mission and fleet data from `config/simulation.yaml`.\n2. Inserts mission telemetry into stdout or GreptimeDB.\n3. Associates fleets and their drones with missions using the `mission_id` field.\n\n## Admin WebUI\n\n### Features Overview\n\nThe Admin WebUI provides a centralized interface for monitoring and managing drone fleets in real-time. It is designed to be lightweight, responsive, and user-friendly.\n\n### Features\n\n- **Fleet Overview**: Displays detailed information about each drone fleet, including model, movement pattern, battery status, and failure rates.\n- **Chaos Mode Toggle**: Allows users to enable or disable chaos mode, simulating random failures and unpredictable behavior.\n- **Drone Launch Control**: Provides an interface to launch drones for specific missions or operations.\n- **Mission Visualization**: Shows mission objectives, regions, and associated drones.\n- **3D Map Option**: Explore an interactive CesiumJS scene with textured terrain, dynamic lighting, and mission annotations at `/3d`.\n- **Interactive Command Console**: Enables direct interaction with the simulator for advanced operations.\n\n### Access\n\nThe Admin WebUI is exposed on port `8080` and can be accessed via a web browser. Ensure the Kubernetes service is correctly configured to route traffic to the Admin WebUI.\n\n### Deployment\n\nThe Admin WebUI is included in the Helm chart for the `droneops-sim` project. Follow the steps in the [Deployment in Kubernetes](#deployment-in-kubernetes) section to deploy the simulator and access the Admin WebUI.\n\n## Enemy Detection\n\nThe simulator includes an enemy detection subsystem used to test how drones react to hostile objects.\n\n- An **Enemy Simulation Engine** spawns a configurable number of enemies across all configured zones and updates them each tick. Enemies react to nearby drones with evasive maneuvers and may group together.\n- Every drone checks for enemies within a configurable detection radius (default: 1\u0026nbsp;km) each tick. Confidence is influenced by distance as well as sensor noise, terrain occlusion and weather conditions.\n- Detection events are written to the table specified by `ENEMY_DETECTION_TABLE` when writing to GreptimeDB, or printed to STDOUT in print-only mode.\n\nEach detection record captures the detecting drone's coordinates, the enemy's location, range and bearing from the drone, and an estimated enemy velocity.\n\nSee [docs/enemy-detection.md](docs/enemy-detection.md) for more details on the available settings and event format.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsohooo%2Fdroneops-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsohooo%2Fdroneops-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsohooo%2Fdroneops-sim/lists"}