# Onboarding guide Welcome! This guide walks you through connecting to the Wingbits real-time flight data stream, step by step. You do **not** need to be a developer to get the first flights showing up on your screen — if you can copy and paste a few commands, you're good. The whole thing takes about **10 minutes**. > Throughout this guide, replace `` with your company name wherever you see it (for example, `acme`). We'll send you a file named `prod--trial.creds` — that file is your key to the stream. *** ## What you'll be connecting to Wingbits delivers live aircraft positions (and more) over a system called [**NATS**](https://nats.io/). Think of NATS like a radio: we broadcast flight updates on different "channels" (called **subjects**), and you tune in to the ones you care about. It's fast, lightweight, and there are ready-made libraries for almost every programming language — but you can also just listen in from your terminal, which is what we'll do first. **Two things you need:** 1. **The NATS command-line tool** (`nats`) — free, we'll install it below. 2. **Your credentials file** (`prod--trial.creds`) — we send this to you by email. Keep it private; it's like a password. > **Don't have credentials yet?** If you're interested in trialing our NATS integration but don't yet have a credentials file, email us at [**sales@wingbits.com**](mailto:sales@wingbits.com) and we'll get you set up. *** ## Step 1 — Install the NATS tool Pick your operating system. **macOS** (using [Homebrew](https://brew.sh/)): ```shell brew install nats-io/nats-tools/nats ``` **Windows** (using [Scoop](https://scoop.sh/)): ```shell scoop install nats ``` **Linux** (or anything else): ```shell curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh ``` Check it worked by running: ```shell nats --version ``` If you see a version number (e.g. `0.1.x`), you're ready. If it says "command not found", the install didn't complete — see [Troubleshooting](#troubleshooting). *** ## Step 2 — Save your credentials file We send you your credentials as a file called `prod--trial.creds`. Save it somewhere you can find it — your Downloads folder is fine. **Open a terminal in that same folder** so the next commands can find the file. > **What do credentials actually look like?** This is the #1 source of confusion, so check now that you really have them. A valid creds file is plain text, about 13 lines, and contains **two** long codes between labeled markers: > > * A **JWT** that starts with `eyJ...` and is several hundred characters long (around 700+), sitting between `-----BEGIN NATS USER JWT-----` and `------END NATS USER JWT------`. > * A **seed** that starts with `SU...` and is **58 characters** long, sitting between `-----BEGIN USER NKEY SEED-----` and `------END USER NKEY SEED------`. > > If what you received has **no `eyJ...` block and no `SU...` block**, you don't actually have credentials yet — email [**sales@wingbits.com**](mailto:sales@wingbits.com) before going further. > **Received your credentials as *****text***** instead of a file?** Sometimes the credentials arrive pasted into a document or email body rather than as an attachment. They'll look like a block starting with `-----BEGIN NATS USER JWT-----` and ending with `------END USER NKEY SEED------`. If so, you need to save that block as a file yourself: > > 1. Copy the **entire** block (from the first `-----BEGIN` to the last `-----`). > 2. Open a plain-text editor (TextEdit in *plain text* mode, Notepad, VS Code). > 3. Paste it in and save the file as `prod--trial.creds`. > * **macOS shortcut:** copy the block, then run `pbpaste > ~/Downloads/prod--trial.creds` in your terminal. > Not sure how to "open a terminal in a folder"? > > * **macOS:** right-click the folder → *New Terminal at Folder*. > * **Windows:** open the folder, type `cmd` in the address bar, press Enter. **Confirm the file is really there before continuing.** In your terminal, run: ```shell ls prod--trial.creds ``` If it prints the filename back, you're good. If it says `No such file or directory`, the file isn't in this folder — find where you saved it, or re-save it here. (Tip: on macOS you can avoid folder confusion entirely by using the file's **full path** in the next step — type `--creds "` and then drag the file from Finder into the terminal to paste its full path.) *** ## Step 3 — Connect In the **same terminal window** from Step 2, paste the command below and press Enter. You only need to run it **once** — it saves a "context" (a saved connection) called `prod--trial` so you don't have to retype the server and credentials every time. **Copy this as a single line** (don't break it across multiple lines): ```shell nats context add prod--trial --server "nats://nats-cluster.wingbits.com:4222" --creds "prod--trial.creds" --select ``` > **Why one line?** If you split a command across multiple lines using `\`, the backslash must be the *very last* character on the line — a single stray space after it will break the whole command (you'll see `command not found` errors). Pasting it as one line avoids this entirely. The `--select` at the end makes this your active connection. If the command runs with no error and returns you to a normal prompt, it worked. *** ## Step 4 — Test your connection Let's make sure everything is wired up correctly: ```shell nats context info ``` You should see your server (`nats-cluster.wingbits.com`) and your credentials file listed. Now try actually pulling in some flights: ```shell nats sub "flights.5s.>" ``` Within a few seconds you should start seeing flight updates streaming down your screen. **That's it — you're connected to live aircraft data.** Press `Ctrl + C` to stop. If nothing shows up, jump to [Troubleshooting](#troubleshooting). *** ## Step 5 — Choose the right stream for you We broadcast the **same flight data** at three different speeds. Pick the one that matches how "live" you need it to be. Faster = more data to handle. | Channel (subject) | How often each aircraft updates | Best for | | ----------------- | ----------------------------------- | ------------------------------------------------- | | `flights.full.>` | Every update, up to \~2× per second | Live maps, anything needing the freshest position | | `flights.5s.>` | Once every 5 seconds | Most use cases — a great default | | `flights.dd.>` | Once every 10 seconds | Dashboards, analytics, lower bandwidth | The `>` at the end is a **wildcard** meaning "every aircraft you're allowed to see." So `flights.5s.>` = all your aircraft, updated every 5 seconds. To listen to a channel, just `sub` (subscribe) to it: ```shell nats sub "flights.5s.>" # all aircraft, every 5 seconds nats sub "flights.full.>" # all aircraft, as fast as it comes ``` ### Following one specific aircraft Every aircraft has a unique ID called an **ICAO hex** (a 6-character code like `7820d9`). To follow just one aircraft, put its hex at the end: ```shell nats sub "flights.full.7820d9" ``` ### Following a list of aircraft (a fleet) If you only need certain aircraft, we grant you access to that exact list and you subscribe to each one. You can listen to several at once: ```shell nats sub "flights.full.7820d9" "flights.full.a1b2c3" "flights.full.c0ffee" ``` > Just tell us which aircraft (or geographic area) you care about, and we'll set your access up to match. *** ## Optional add-ons These are extra data feeds available on request. Once enabled for your account, you subscribe to them the same way: | Add-on | Subject | What it is | | --------------- | -------------- | -------------------------------------------------------------- | | **ACAS / TCAS** | `flights.acas` | Collision-avoidance "resolution advisory" events | | **ADS-C** | `flights.adsc` | Oceanic / satellite-based positions (aircraft over open ocean) | ```shell nats sub "flights.acas" nats sub "flights.adsc" ``` *** ## Understanding the data Each message is a small **JSON** record describing one aircraft at one moment. To keep messages tiny and fast, the field names are short codes. Here's what they mean: | Code | Field | Description | | ----- | -------------------------------- | ------------------------------------------ | | `h` | ICAO Hex | The aircraft's unique ID | | `f` | Flight | Flight number / callsign | | `la` | Latitude | Aircraft latitude | | `lo` | Longitude | Aircraft longitude | | `ab` | Barometric Altitude | Altitude from barometric pressure | | `ag` | Geometric Altitude | Altitude from GPS | | `gs` | Ground Speed | Speed over the ground | | `tr` | Track | Direction of travel (track angle) | | `th` | True Heading | Heading relative to true north | | `mh` | Magnetic Heading | Heading relative to magnetic north | | `og` | On Ground | Whether the aircraft is on the ground | | `sq` | Squawk | Transponder squawk code | | `c` | Category | Aircraft category | | `t` | Type | Message type | | `v` | Version | ADS-B version | | `a` | Alert | Alert status | | `em` | Emergency | Emergency status | | `spi` | SPI | Special Position Indicator | | `br` | Baro Rate | Rate of climb/descent (barometric) | | `gr` | Geometric Rate | Rate of climb/descent (GPS) | | `i` | IAS | Indicated air speed | | `m` | Mach | Mach number | | `ct` | Calculated Track | Track calculated from position | | `oat` | Outside Air Temperature | Air temperature outside the aircraft | | `tat` | Total Air Temperature | Total air temperature | | `wd` | Wind Direction | Direction the wind is coming from | | `ws` | Wind Speed | Wind speed | | `ro` | Roll | Roll angle | | `trr` | Track Rate | Rate of change in track | | `rs` | RSSI | Received signal strength | | `sn` | Seen | When the message was last seen | | `sp` | Seen Position | When the position was last seen | | `rc` | Radius of Containment | Position accuracy measure | | `rdi` | Receiver Direction | Direction from receiver to aircraft | | `rds` | Receiver Distance | Distance from receiver to aircraft | | `nh` | Nav Heading | Selected heading | | `nq` | Nav QNH | Altimeter setting | | `naf` | Nav Altitude FMS | Altitude from the Flight Management System | | `nam` | Nav Altitude MCP | Altitude set on the Mode Control Panel | | `n` | Navigation Integrity Category | NIC value | | `nb` | NIC Baro | NIC value from barometric source | | `np` | Navigation Accuracy for Position | NAC-p value | | `nv` | Navigation Accuracy for Velocity | NAC-v value | | `s` | SIL | Source Integrity Level | | `st` | SIL Type | Type of SIL | | `sda` | SDA | System Design Assurance level | | `gv` | Geometric Vertical Accuracy | Accuracy of geometric altitude | | `gpb` | GPS OK Before | GPS was recently OK | > Not every field appears in every message — aircraft only report what their equipment supports. *** ## Using the data in your own software The terminal is great for testing, but you'll probably want to pull this into your own application. NATS has official libraries for [most languages](https://docs.nats.io/using-nats/developer) (Python, JavaScript, Go, Java, C#, Rust, and more). They all use the **same** server address, credentials file, and subjects you used above. **Python example** (`pip install nats-py`): ```python import asyncio, json import nats async def main(): nc = await nats.connect( "nats://nats-cluster.wingbits.com:4222", user_credentials="prod--trial.creds", ) async def on_message(msg): data = json.loads(msg.data) print(f"{data.get('h')} lat={data.get('la')} lon={data.get('lo')}") await nc.subscribe("flights.5s.>", cb=on_message) await asyncio.Event().wait() # keep listening asyncio.run(main()) ``` **Node.js example** (`npm install nats`): ```javascript import { connect, credsAuthenticator } from "nats"; import { readFileSync } from "fs"; const nc = await connect({ servers: "nats://nats-cluster.wingbits.com:4222", authenticator: credsAuthenticator(readFileSync("prod--trial.creds")), }); const sub = nc.subscribe("flights.5s.>"); for await (const msg of sub) { const data = JSON.parse(msg.string()); console.log(data.h, data.la, data.lo); } ``` *** ## Troubleshooting **`nats: command not found`** The tool didn't install. Re-run the install step for your OS, then close and reopen your terminal. **`no such file or directory` mentioning your `.creds` file** Your terminal isn't in the same folder as the credentials file. Either move the `.creds` file into the folder your terminal is in, or use the full path to it, e.g. `--creds "/Users/you/Downloads/prod--trial.creds"`. **`nats: error: nats: Authorization Violation`** The credentials aren't being accepted, or you're subscribing to a channel you don't have access to yet. Double-check you're using the exact `.creds` file we sent, and that you're subscribing to a subject you've been granted. If it persists, contact us — we may need to adjust your access. **It connects, but no flights appear** * Try `flights.full.>` instead of `flights.5s.>` (more frequent updates). * Confirm with us which subjects your account is allowed to see — trial accounts are sometimes scoped to a specific region or aircraft list. **`connection refused` / timeout** Your network may be blocking outbound port **4222**. Check with your IT team, or try from a different network to confirm. *** ## Need help? Reply to your onboarding email or reach out to your Wingbits contact. Tell us: * What command you ran * The exact message you got back and we'll get you sorted quickly. Happy tracking! ✈️ — The Wingbits Team --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wingbits.com/wingbits/guides-2/nats-integration/nats-flight-stream.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.