Skip to content

Update readmes #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ahdgkn merged 8 commits into from
Jun 19, 2026
Merged

Update readmes #85

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f380b30
Update to main readme with images folder
ahdgkn Jun 3, 2026
fa337a3
Updates to bluebird-hmi readme
ahdgkn Jun 4, 2026
60caa6a
Update main readme
ahdgkn Jun 18, 2026
241f223
Updates to bluebird-api readme
ahdgkn Jun 18, 2026
efa7692
Updates to gym readme
ahdgkn Jun 18, 2026
3002f48
Update dt and gym readme
ahdgkn Jun 18, 2026
7c6350e
Correct list numbering
ahdgkn Jun 19, 2026
a2025fa
Merge branch 'main' into update_readme
ahdgkn Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 38 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,58 @@
# BluebirdATC
A Digital Twin for use in ATC simulations, and a training environment for AI agents.
# BluebirdATC <img src="images/BBATC_logo.png" alt="BluebirdATC logo" align="right" height="160" />

This repository contains the following packages:
* [![PyPI version](https://img.shields.io/pypi/v/bluebird-dt?logo=pypi&logoColor=white&label=bluebird-dt)](https://pypi.org/project/bluebird-dt/) - the digital twin. See [here](bluebird-dt/README.md) for more information.
* [![PyPI version](https://img.shields.io/pypi/v/bluebird-api.svg?logo=pypi&logoColor=white&label=bluebird-api)](https://pypi.org/project/bluebird-api/) - A REST API for the digital twin. See [here](bluebird-api/README.md) for more information.
* [![PyPI version](https://img.shields.io/pypi/v/bluebird-gymnasium.svg?logo=pypi&logoColor=white&label=bluebird-gymnasium)](https://pypi.org/project/bluebird-gymnasium/) - a gym environment for AI agents. See [here](bluebird-gymnasium/README.md) for more details.
* `bluebird-hmi` - an optional web-based visualisation package. See [here](bluebird-hmi/README.md) for details.

## (AI)r traffic controller challenge
Information relating to the (AI)r traffic controller challenge can be found [here](https://docs.projectbluebird.ai/examples/competition/Competition-Intro/) to get started with the competition specific setup.
BluebirdATC is an open-source digital twin of en route airspace, developed by [Project Bluebird](https://www.projectbluebird.ai), a collaboration between the Alan Turing Institute, the University of Exeter and NATS. It provides a safe, reproducible sandbox to simulate realistic air traffic scenarios, develop autonomous ATC agents, and benchmark their performance.

## Running the digital twin
![RouteFollowPredictor](images/auto_pilot.gif)

For quick start, please make sure uv is installed [(installation guide)](https://docs.astral.sh/uv/getting-started/installation/) and run the following command in a terminal:
## Packages

This repository contains the following packages, each with their own README for more information:

| Package | Purpose |
| --- | --- |
| [![PyPI version](https://img.shields.io/pypi/v/bluebird-dt?logo=pypi&logoColor=white&label=bluebird-dt)](https://pypi.org/project/bluebird-dt/) | The digital twin — simulate airspace, aircraft, and actions. [Docs](bluebird-dt/README.md) |
| [![PyPI version](https://img.shields.io/pypi/v/bluebird-api.svg?logo=pypi&logoColor=white&label=bluebird-api)](https://pypi.org/project/bluebird-api/) | A REST API server for the digital twin. [Docs](bluebird-api/README.md) |
| [![PyPI version](https://img.shields.io/pypi/v/bluebird-gymnasium.svg?logo=pypi&logoColor=white&label=bluebird-gymnasium)](https://pypi.org/project/bluebird-gymnasium/) | Gymnasium environments — train RL agents, single & multi-agent. [Docs](bluebird-gymnasium/README.md) |
| `bluebird-hmi` | An optional web-based visualisation package. [Docs](bluebird-hmi/README.md) |

## AI(r) Traffic Controller Challenge

Project Bluebird are hosting an AI agent development competition, the *AI(r) Traffic Controller Challenge*.

To get started with the competition specific setup see the docs [here](https://docs.projectbluebird.ai/examples/competition/Competition-Intro/).

## Quick start

To get started with viewing a scenario in the HMI - make sure uv is installed [(installation guide)](https://docs.astral.sh/uv/getting-started/installation/) and then run the following command in a terminal:

```bash
uvx bluebird-api@latest
```

then navigate to [http://localhost:8000/hmi/](http://localhost:8000/hmi/).
Then navigate to [http://localhost:8000/hmi/](http://localhost:8000/hmi/).

You'll see a radar HMI with no scenario loaded. To load a simple I-Sector scenario:

1. Select **Load new scenario** in the top left
2. Choose **Artificial** → **I-Sector Two Aircraft** → **Load**
3. Press the **play** icon in the top left

This site will open a radar HMI, initially with no scenario loaded.
To load a scenario, the top left of the window select `Load new scenario`.
A window will appear in the middle of the screen, select `Artificial`, then `I-Sector Two Aircraft` and finally, `Load`.
Aircraft will appear in the sector and begin moving. Each label shows the callsign, current flight level, groundspeed, and cleared and exit flight levels - the same information a real ATCO sees on their radar display.

With the scenario loaded, the aircraft and sector should now be visible in the radar. Clicking the play icon in the top left of the screen will make the simulation evolve making the aircraft move.
## Developing agents

## Quick start examples for developing agents
To get started with agent development, we have provides some examples for interfacing with the digital twin:

Examples for interfacing with the digital twin to make agents are available:
* [here](bluebird-dt/README.md#getting-started) to directly interact with the digital twin
* [here](bluebird-gymnasium/README.md#getting-started) for using the gymnasium
* [here](bluebird-api/README.md#getting-started) for using the REST API from any language
* [here](bluebird-dt/README.md#getting-started) to directly interact with the digital twin

## Documentation

The documentation of the latest release is available at [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai).
Full documentation for the latest release is at [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai).

## Contributing

Please see the guidelines [here](CONTRIBUTING.md) if you would like to contribute to BluebirdATC.
Please see the [contribution guidelines](CONTRIBUTING.md) if you would like to contribute to BluebirdATC.

<div align="center"><img src="images/BB_logo.png" alt="ProjectBluebird"></div>
89 changes: 35 additions & 54 deletions bluebird-api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# The REST API for BluebirdATC
# The REST API for BluebirdATC [![PyPI version](https://img.shields.io/pypi/v/bluebird-api?logo=pypi&logoColor=white)](https://pypi.org/project/bluebird-api/) <img src="../images/BBATC_logo.png" alt="BluebirdATC logo" align="right" height="160" />

It is possible to run the BluebirdATC digital twin in a server process, such that the simulation will evolve at regular time intervals, and Agents and/or frontend visualization software can interact with it via HTTP requests.

`bluebird-api` runs the BluebirdATC digital twin in a server process, such that the simulation will evolve at regular time intervals, and Agents and/or frontend visualization software can interact with it via HTTP requests.
In particular, users can:
* Query available scenario categories and scenarios.
* Load a selected scenario.
Expand All @@ -11,35 +12,29 @@ In particular, users can:

## Getting started

### Running the server

The simplest way to run the api is using uv [(installation guide)](https://docs.astral.sh/uv/getting-started/installation/) and running
The quickest way to start the server is with [uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
uvx bluebird-api@latest
```

You should then be able to go to [http://localhost:8000](http://localhost:8000) in a web browser, and see the message "Hello, BluebirdATC!".
1. Open [http://localhost:8000](http://localhost:8000) — you should see `"Hello, BluebirdATC!"`.
1. Navigate to [http://localhost:8000/hmi](http://localhost:8000/hmi) to open the radar visualisation.
Comment thread
ahdgkn marked this conversation as resolved.
Outdated
1. Select **Load new scenario** in the top left, choose a scenario type (eg. `Springfield`) and scenario (eg `test1`), and press **Load**.

This package includes a prebuilt HMI available by navigating to [http://localhost:8000/hmi](http://localhost:8000/hmi).
Initially, no scenario would be loaded, therefore showing the Bluebird logo on the radar.
To load a scenario, the top left of the window select `Load new scenario`.
A window will appear in the middle of the screen, select `Springfield`, then `test1` and finally, `Load`.
> **Note: Running on a remote machine/cloud?**
Currently, the built version of the app is configured to look for the API running on `localhost`. For deploying on remote machines, or a cloud service, it will be necessary to modify `src/api/config.ts` accordingly, and rebuild via `npm run build`.

### Using the API
## Using the API

Agents can interface with the simulator running behind a REST API, enabling its usage from any programming language.

The next script is an example of an agent in python, which requires the bluebird-dt and requests packages to be installed.
Any language that can make HTTP requests can drive the simulation. The example below is a Python agent that directs each aircraft to its exit fix and cleared flight level as it enters the sector. Install the required packages first:

```bash
pip install bluebird-dt requests
```

It tells all aircraft, on incomm, to fly to their exit fix and climb directly to their exit flight level without ensuring safety or guaranteeing that aircraft will leave the sector.

```python
from bluebird_dt.core import Environment, Action
from bluebird_dt.core import Environment
import time, requests

callsigns_done = []
Expand All @@ -54,46 +49,38 @@ while True:

if aircraft.callsign in callsigns_done or aircraft.current_sector != "SPRINGFIELD":
continue

exit_coordination = environment.exit_coordination("SPRINGFIELD", aircraft.callsign)

if exit_coordination is not None:
actions_to_issue.extend(
[
{
"callsign": aircraft.callsign,
"kind": "change_flight_level_to",
"value": exit_coordination.fl,
"sector": "SPRINGFIELD",
"agent": "agent"
},
{
"callsign": aircraft.callsign,
"kind": "route_direct_to",
"value": exit_coordination.fix,
"sector": "SPRINGFIELD",
"agent": "agent"
}
]
)
actions_to_issue.extend([
{
"callsign": aircraft.callsign,
"kind": "change_flight_level_to",
"value": exit_coordination.fl,
"sector": "SPRINGFIELD",
"agent": "agent"
},
{
"callsign": aircraft.callsign,
"kind": "route_direct_to",
"value": exit_coordination.fix,
"sector": "SPRINGFIELD",
"agent": "agent"
}
])

callsigns_done.append(aircraft.callsign)

if len(actions_to_issue) > 0:
response = requests.post(
"http://localhost:8000/actions",
json=actions_to_issue
)

# Wait for the next tick
requests.post("http://localhost:8000/actions", json=actions_to_issue)

time.sleep(4)
```

## Documentation

The documentation of the latest release is available at [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai).
A more complete multi-language example (including Julia) is in [NonPythonAgents.ipynb](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-api/examples/NonPythonAgents.ipynb).

## OpenAPI
## Documentation

Documentation of the endpoints of the API is available by running

Expand All @@ -105,10 +92,4 @@ and navigating to [http://localhost:8000/docs](http://localhost:8000/docs).

A json format of this API is also available in [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json) which can be used to generate clients automatically using OpenAPI generators for the language you are using.

## Frontend visualisation

The app also serves the frontend visualization (more details on that can be found [here](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-hmi/README.md)), at the URL [http://localhost:8000/hmi](http://localhost:8000/hmi).

## Julia example

A more complete example of how to use the API is available in [NonPythonAgents.ipynb](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-api/examples/NonPythonAgents.ipynb)
<div align="center"><img src="../images/BB_logo.png" alt="ProjectBluebird"></div>
20 changes: 11 additions & 9 deletions bluebird-dt/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# The `bluebird_dt` digital twin.
# The Digital Twin [![PyPI version](https://img.shields.io/pypi/v/bluebird-dt?logo=pypi&logoColor=white)](https://pypi.org/project/bluebird-dt/) <img src="../images/BBATC_logo.png" alt="BluebirdATC logo" align="right" height="160" />

The python package `bluebird_dt` encodes a digital twin of an airspace, including classes that represent:
`bluebird_dt` encodes a digital twin of an airspace, including classes that represent:
* The geometry of the airspace - Sectors, Volumes, Airways, Fixes, ...
* Aircraft, with properties such as location, heading, flight level, ...
* Predictors, to model how the aircraft parameters evolve with the simulation.
Expand All @@ -13,12 +13,12 @@ The python package `bluebird_dt` encodes a digital twin of an airspace, includin

`bluebird-dt` is available on pypi, therefore it can be installed using

```
```bash
pip install bluebird-dt
```

or, if using [UV](https://docs.astral.sh/uv/), you can add it to your environment using
```
```bash
uv add bluebird-dt
```

Expand Down Expand Up @@ -48,12 +48,14 @@ sim.manager.receive_actions(
)
```

This example is very simple, various examples of using the `bluebird_dt` package can be found in the form of Jupyter notebooks in the [examples](https://github.com/project-bluebird/BluebirdATC/tree/main/bluebird-dt/examples) directory.
This example is very simple - various examples of using the `bluebird-dt` package can be found in the form of Jupyter notebooks in the [examples](https://github.com/project-bluebird/BluebirdATC/tree/main/bluebird-dt/examples) directory.

## Documentation
### Running the digital twin as a server.

The online documentation for the `bluebird_dt` package can be found at in [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai)
A FastApi app is available as `bluebird-api`, allowing the simulation to be run as a server, with the user (or an agent) interacting via a REST API. For information on this, see [GitHub](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-api/README.md) or [Pypi](https://pypi.org/project/bluebird-api/).

### Running the digital twin as a server.
## Documentation

The full documentation for the `bluebird-dt` package can be found at in [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai)

A FastApi app is available as bluebird-api, allowing the simulation to be run as a server, with the user (or an agent) interacting via a REST API. For information on this, see [GitHub](https://github.com/project-bluebird/BluebirdATC/blob/main/bluebird-api/README.md) or [Pypi](https://pypi.org/project/bluebird-api/).
<div align="center"><img src="../images/BB_logo.png" alt="ProjectBluebird"></div>
21 changes: 12 additions & 9 deletions bluebird-gymnasium/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,28 @@
# Bluebird Gymnasium
# Bluebird Gymnasium [![PyPI version](https://img.shields.io/pypi/v/bluebird-gymnasium?logo=pypi&logoColor=white)](https://pypi.org/project/bluebird-gymnasium/) <img src="../images/BBATC_logo.png" alt="BluebirdATC logo" align="right" height="160" />

A suite of gymnasium environments for air traffic control (ATC).
`bluebird-gymnasium` is suite of gymnasium environments for air traffic control (ATC).
The environments are based on [bluebird-dt](https://github.com/project-bluebird/BluebirdATC/tree/main/bluebird-dt) (an ATC simulator).

The environments support research in agent-based learning (e.g. reinforcement learning) for ATC.
It supports either single agent or multi-agents scenarios.

## Installation

`bluebird-gymnasium` is available on pypi, therefore it can be installed using
Install from PyPI:

```
```bash
pip install bluebird-gymnasium
```

or, if using [UV](https://docs.astral.sh/uv/), you can add it to your environment using
```
Or, if you're using [uv](https://docs.astral.sh/uv/), you can add it to your environment:

```bash
uv add bluebird-gymnasium
```

## Getting started

### Basic usage

bluebird-gymnasium currently supports the following environments/airspace:
`bluebird-gymnasium` currently supports the following environments/airspace:
X sector, Y sector, I sector, Xplus sector and Springfield sector.

To instantiate a X sector environment with the default config, run:
Expand Down Expand Up @@ -51,6 +50,10 @@ while not done:
obs, reward, done, truncated, info = env.step(action)
```

Various examples of using the `bluebird-gymnasium` package can be found in the form of Jupyter notebooks in the [examples](https://github.com/project-bluebird/BluebirdATC/tree/main/bluebird-gymnasium/examples) directory or in the [documentation](https://docs.projectbluebird.ai/examples/competition/Competition-Intro/) for the AI(r) Traffic Controller Challenge.

## Documentation

The documentation of the latest release is available at [https://docs.projectbluebird.ai](https://docs.projectbluebird.ai).

<div align="center"><img src="../images/BB_logo.png" alt="ProjectBluebird"></div>
Loading
Loading