Quick Start

Thanks for your purchase of an ADSBee 1090! This quick-start guide should get you headed in the right direction. Please select what you’d like to do from the options below to jump to more detailed instructions.

This quick start guide is a work in progress! Please let me know if you find any typos or want additional information by posting in the #documentation channel on Discord!

I’d like to…

🔧 Change Device Software or Hardware

⬆️ Update the Firmware on my ADSBee
🥡 Modify the Enclosure of my ADSBee

💾 Change Device Settings

📲 Feed air traffic data to an App
🌐 Feed raw packets to an Aggregator or Local Endpoint
💡 Integrate ADSBee with an Embedded Project
🛜 Join an External WiFi Network

🔩 Get into the Nuts and Bolts

📄 Read the ADSBee Datasheet
🐝 Follow the ADSBee Project on GitHub

⬆️ Update Firmware on an ADSBee

  1. Connect your ADSBee to a laptop via a USB-C cable. Make sure to use a cable that has data wires, not just power!
  2. Press the button labelled “BT” and keep it held down. Press and release the button labelled “RST”. Release the button labelled “BT”. The ADSBee 1090 should show up as a USB mass storage device.
  1. Go to the ADSBee Firmware Releases page and download the most recent firmware release. All you need is the file ending in “.uf2” (e.g. “combined.uf2”).
  2. Drag and drop the .uf2 file into the ADSBee USB mass storage device and wait for it to finish loading. The USB mass storage device should automatically eject when the firmware update is complete.
  3. Leave the ADSBee plugged in to your computer while it updates the firmware stored on the ESP32. This should take about a minute; the indicator lights may do some funky things while the firmware is being upgraded. When the orange NETWORK LED begins flashing regularly (at about 5Hz), indicating stable communication between the RP2040 and the ESP32, the firmware update has completed and your device can be unplugged or used as usual.
  4. Optional: Check your firmware version by connecting to the CLI and sending AT+DEVICE_INFO?.

A network bootloader is coming soon! Once installed, it will enable device firmware to be updated without the need for a physical USB connection. Stay tuned!

🥡 Modify an ADSBee Enclosure

The ADSBee 1090 ships in a 3D printed PETG enclosure secured with four plastic latches. The enclosure can be easily disassembled using a standard USB-C cable to pop the latches out of their holds, allowing the back plate of the enclosure to be swapped out for different designs (e.g. the window feeder mounting bracket).

The ADSBee 1090 can be completely removed from its enclosure by using a 2.0mm hex bit to remove the 4x M2.5 mounting screws that are used to secure the PCBA onto the bosses in the 3D printed case. Use care to not strip the plastic when reinstalling the screws!

The MHF4 connector on the ESP32 is extremely fragile! Use caution when removing it, as it’s rather easy to rip off of the ESP32. Preferably, use a push / pull tool like this to remove the connector safely.

For a detailed overview of the enclosure design, as well as a demonstration of disassembling and assembling the enclosure, please watch the YouTube video below.

3D print files for all of the enclosure components are open source and available for free from the OnShape link below. The enclosure design can be changed and saved by creating a free OnShape account. Note that the “Back Cover” part has multiple configurations, one for a window mount configuration (labelled “Bracket”), and one for the handheld case variant (labelled “Default”).

ADSBee 1090 Enclosure CAD

📲 Feed air traffic data to an App

Electronic Flight Bag (EFB) devices are Android / iOS tablets loaded with maps / VFR charts / approach plates / etc for use by pilots. Devices like Stratux, Foreflight Sentry, and ADSBee 1090 can be used to feed EFB devices with aircraft traffic information over WiFi.

Here are a few apps that can be used with ADSBee 1090. If you have one that you like, please send me a note on Discord so that we can add it to the table!

Platform /
Use Case		iPhoneAndroidDesktop
Electronic Flight BagForeFlight (paid)Avare (free)
Airplane SpottingAeroADSBADSB Receiver (free)

ADSBee 1090 is still in Beta, and is not advised for use as a primary EFB traffic information device at this time. Feedback and testing is always welcome, but safety is #1! If you do fly with an ADSBee 1090, please make sure to use a tested and functional alternative device as your primary source for traffic information.

  1. The ADSBee 1090 should be ready to go out-of-the-box for feeding most Electronic Flight Bag (EFB) devices! Power on your ADSBee 1090, and look for a WiFi network titled “ADSBee1090-0240907000001” or something similar (the number varies, as each ADSBee generates a WiFi network with its own unique SSID).
  2. Join the WiFi network with your EFB device. The default password is yummyflowers. You will receive a notice that internet is not available, but your device should remain connected. Note that your device will be assigned an IP address on the subnet 192.168.4.X. The ADSBee is the gateway for this network, with an IP address of 192.168.4.1.
  3. Configure your electronic flight bag app to accept GDL90 traffic information on port 4000 over UDP (this is the default for most apps). You should see aircraft data streaming into the app! Some example screenshots for Avare (a free Android EFB app) are shown below.

ADSBee 1090 doesn’t yet support ownship position reports, but it’s on the TODO list (need to integrate a GPS module, the hardware interface is already on the PCB). For now, ADSBee 1090 works best with devices that have their own GPS which can provide ownship position data.

Note that the “IO” tab with this setting is reached by swiping left along the bottom of the screen. A bit tricky to find it by default!
Ownship position (red), and traffic (blue).

🌐 Feed an Aggregator

ADSBee 1090 can stream the transponder packets it receives to an endpoint on a local WiFi network or on the public internet. This can be used to feed aggregators like airplanes.live, adsbexchange, or a local instance of tar1090 (a popular ADS-B decoding software package).

  1. Access the Command Line Interface (CLI). There are multiple ways to do this, refer to the Connecting to the CLI section to pick your favorite!
  2. Configure the ADSBee 1090 to join an external WiFi network.
  3. Check the current feed settings with AT+FEED?
  4. Enter the details for your new feed with AT+FEED=<feed_index>,<feed_uri>,<feed_port>,<feed_active>,<protocol>.
    • <feed_index>: ADSBee can support up to 6 feeds simultaneously. This parameter is replaced with a digit from 0-5 in order to indicate which feed is being altered.
    • <feed_uri>: This parameter is replaced with the IP address of the feed endpoint.
    • <feed_port>: This parameter indicates which port on the endpoint will be used for the feed. The most common value is 30004, the typical port for Mode-S Beast data over TCP.
    • <active>: Enable / disable the feed. Set this to 1 to activate the feed.
    • <protocol>: What protocol to use when feeding. Currently, only BEAST and BEAST_RAW are supported.
      • BEAST = All received transponder packets with a valid checksum.
      • BEAST_RAW = All received transponder packets, regardless of whether they had a valid checksum.
  5. Check that your values were set correctly with AT+FEED?. You should see a sparkline graph below the terminal indicating a non-zero number of packets per second being forwarded to your feed (assuming your ADSBee is receiving packets).

Connect to the CLI

The ADSBee 1090’s settings can be changed via its Command Line Interface (CLI). The CLI can be accessed via USB or via a webpage serial terminal. For a full list of CLI commands, run AT+HELP in the CLI. A detailed description of the CLI commands and their functions can also be found in the ADSBee 1090 datasheet.

Method 1: Connect via USB Serial Terminal

  1. Connect the ADSBee 1090 to your computer via a USB C cable. The ADSBee 1090 should enumerate as a virtual COM port on Windows (or /dev/tty/whatever on Mac / Linux).
  2. Connect to the ADSBee 1090’s COM port using your favorite serial terminal. NOTE: Baud rates and parity don’t matter, since this is a virtual COM port, but line endings MUST be set to \r\n, or else your commands may not be interpreted correctly or at all!
  3. Type AT+HELP into the web terminal, and hit enter. This should provide a list of available AT commands as shown below. Use the AT commands to interact with the CLI as you please! Note that all changed settings will be discarded on reboot unless they are saved with AT+SETTINGS=SAVE. If you would like to revert to the default settings, use AT+SETTINGS=RESET.

Recommended Terminal Software:

Method 2: Connect via ADSBee’s Webpage Serial Terminal

Connecting to the web CLI is best done on a desktop computer in the Chrome browser. Some phones can connect to the web CLI, but there is a bug in some mobile browsers that currently causes text to be entered into the terminal in reverse.

  1. Join the WiFi network generated by the ADSBee 1090 (SSID takes the form “ADSBee1090-0240907000001” or similar). The default password is yummyflowers.
  2. In a web browser (tested and working on Chrome), visit the following web address: http://192.168.4.1. Note that there is no leading “www.”, and the protocol is HTTP, not HTTPS! You should arrive at the screen shown below. The web terminal will timeout after 10 minutes of inactivity, and can be revived by refreshing the page.
  1. Type AT+HELP into the web terminal, and hit enter. This should provide a list of available AT commands as shown below. Use the AT commands to interact with the CLI as you please! Note that all changed settings will be discarded on reboot unless they are saved with AT+SETTINGS=SAVE. If you would like to revert to the default settings, use AT+SETTINGS=RESET.

There are no guardrails on the CLI commands! You can turn off WiFi from the Web CLI, which will predictably stop you from being able to interact using said Web CLI. To recover, connect to the CLI via USB and run AT+SETTINGS=RESET.

The Web CLI can also be reached by visiting the ADSBee 1090’s IP address once it has joined an external WiFi network (e.g. the network created by the WiFi access point at your house). For instance, if your ADSBee 1090 was assigned an IP address of 10.3.2.5, then you could visit the web CLI by navigating to http://10.3.2.5 (note this is just an example). To get the IP address of the ADSBee 1090, visit the DHCP leases page on your router to see what IP has been assigned to the device.

CLI Tips

  • AT command arguments can be skipped by leaving them blank, and AT commands can be given fewer than their maximum number of arguments! For instance, if you just want to disable feed 5, you could send AT+FEED=5,,,0, instead of the more verbose AT+FEED=5,78.46.234.18,30004,0,BEAST. In the shorter command, the feed IP address, port, and protocol were omitted. Note that the trailing comma was not necessary, since the final argument is automatically passed as a blank field if it is missing. AT+FEED=5,,,0 works just as well!
  • Sending messages via the Web CLI can be time-intensive, and may cause the ESP32 to miss transponder packets if console verbosity is set too high. If you’d like to investigate packet reception and other info with AT+LOG_LEVEL=INFO, it’s recommended to do this via the USB terminal and keep the Web CLI interface closed. When using the web CLI, it is recommended to keep the Web CLI verbosity level at AT+LOG_LEVEL=WARNINGS, AT+LOG_LEVEL=ERRORS, or AT+LOG_LEVEL=SILENT.
  • The console on the Web CLI will automatically time out after 10 minutes of inactivity (it can be re-activated with a page refresh).

🛜Join an External WiFi Network

  1. Connect to the CLI via the method of you choosing.
  2. Run the command AT+WIFI_STA? to check your current WiFi station settings.
  3. Enter the network credentials for your WiFi network with AT+WIFI_STA=<enabled>,<ssid>,<password>. In this case, replace <enabled> with 1, <ssid> with the SSID of your network, and <password> with your WPA passkey. Note that values should be comma separated, with no spaces in between! No quotes are required around any values.
  4. Save the settings with AT+SETTINGS=SAVE. If you’d like, you can verify that they were saved by calling AT+SETTINGS?.
  5. Apply the new WiFi settings by restarting the device with AT+REBOOT.

💡 Integrate the ADSBee with an Embedded Project

The ADSBee 1090 is intended to interface easily with external modules via UART! Both the USB connector (CONSOLE) and UART output can be used to report received aircraft data in a variety of formats, including MAVLINK1, MAVLINK2, GDL90, Mode S Beast, and CSBEE. Of these protocols, CSBEE is the easiest to decode from scratch, and is also the most information rich.

Connect a Device via UART

  1. Connect to the CLI.
  2. Configure the baudrate of the COMMS UART to your desired value using the AT+BAUDRATE command. For instance, to set the baudrate to 115200 baud on the COMMS UART, send the command: AT+BAUDRATE=COMMS_UART,115200. Verify your setting with AT+BAUDRATE?.
  3. Enable a reporting protocol on the COMMS UART. For instance, to enable CSBEE reporting, send AT+PROTOCOL=COMMS_UART,CSBEE. Verify your setting by checking the output of AT+PROTOCOL?.
  4. Connect your external device to the pins on the ADSBee 1090 labelled GND, TX, and RX. Don’t forget to cross over TX and RX as necessary!
  5. Save your settings with AT+SETTINGS=SAVE.

Connect a Device via USB

  1. Connect to the CLI.
  2. Silence all log messages on the CONSOLE output, as this may mangle any protocol it’s attempting to transmit: AT+LOG_LEVEL=SILENT.
  3. Set the desired reporting protocol on the CONSOLE output. For instance, to report CSBEE over the CONSOLE connection, send AT+PROTOCOL=CONSOLE,CSBEE.
  4. Confirm that the protocol is being correctly output via the console. You will be able to see the protocol on both the serial and web CLI.
  5. Save your settings with AT+SETTINGS=SAVE. You can now connect your ADSBee to another project and read data over USB with a library like PySerial!