This is an update version of theSkyScansystem that is built using IQT'sEdgeTech components.
SkyScan has been built around the APIs for Axis security cameras, but it could be extended to work with any camera with an API.
- Recent version of Docker and Docker Compose - RTL-SDR dongle with an Antenna that works at 1090MHz - Linux computer, a Raspberry Pi 4 or 5 will work - Axis PTZ Camera (tested with an AXIS P5655-E PTZ )
Make sure you have Docker installed, instructions are on the Docker site:
Raspberry Pi OS (64 bit)https://docs.docker.com/engine/install/debian/ Raspberry Pi OS (32 bit)https://docs.docker.com/engine/install/raspberry-pi-os/ Ubuntuhttps://docs.docker.com/engine/install/ubuntu/
You should also have the RTL SDR tools installed. You check to make sure the SDR is working as intended with thertl_testcommand. The tools can be installed withsudo apt install rtl-sdr.
Clone a local copy of this repo onto the server it will be deployed on:
git clone https://github.com/IQTLabs/edgetech-skyscan.gitThe PTZ camera should be reachable over the network from the Linux computer you are running SkyScan on. Make sure the camera is as level as possible and pointed towards True North.
Start by copyingskyscan.envto.env
cp skyscan.env.envEach of the modules in SkyScan can be configured via Environment variables. The Docker Compose file sets these values from files. There are comments alongside each of the values to provide a description of what is required. Here is a walk through of the core values that need to be configured:
- TheDEPLOYMENTis used to help describe where SkyScan is being deployed. There should be no spaces, use an
-or_instead. This value is used to construct the MQTT Topics. - In order to determineTRIPOD_LATITUDEandTRIPOD_LONGITUDEuse Google Maps, and right click on the tripod's location to copy the lat/long.
- TheTRIPOD_ALTITUDEneeds to be provided based on the WGS84 Ellipsoid, which is different than the barometric pressure based altitude you get from your phone. Start by getting your altitude based on barometric pressure using an App on your phone (make sure you convert from Feet to Meters). Then use this conversion web app to get that elevation in the WGS84 Ellipsoid:https://www.unavco.org/software/geodetic-utilities/geoid-height-calculator/geoid-height-calculator.html
- Initially leaveYAW,PITCH,andROLLat 0.0. Once the deployment is up and running you can adjust these values to compensate for the camera being un-level or not correctly pointing to True North.
- TheZOOMvalue ranges from 0 which is the widest setting, to 9999, which is zoomed in all the way. Start with a low number initially until the deployment has been dialed in.
- The Axis camera you will be using needs to be reachable from the server you are deploying SkyScan on. CompleteCAMERA_IP,CAMERA_USER,andCAMERA_PASSWORDwith the values for your camera. If you need help finding the IP address for the camera, the Linux
avahi-discovercommand can help find Axis cameras on you network using Bonjour. - You should generally not need to change any of the MQTT Topic names.
- ConfigurePAN_RATE_MAX&TILT_RATE_MAXbased on the values for the camera being used. The value is in degrees / second and should be listed in the dataset.
- After everything is up and running, try adjusting thePAN_GAIN&TILT_GAINvalues. If the camera is swaying rapidly back and forth as it tracks a plane, the gain value is probably too high. If the camera has having trouble keeping up with the plane, it is probably too low.
- SetTZto the appropriate timezone for where the camera is located
- Adjust theDUMP1090_DEVICEvalue if you wish to use an RTL-SDR that is not the first one
- UseOBJECT_DISTANCE_THRESHOLD,MIN_ALTITUDE,MAX_ALTITUDE,&MIN_TILTvalues to limit which aircraft can be selected for the camera to track. This is helpful when you want to do things like not track higher flying aircraft because of clouds or only select aircraft that are high enough over the horizon to be seen of obstacles.
After you have finished configuring the environment files, start everything up using Docker Compose:
docker compose pull
docker compose upAfter everything is up and running, goto the web interface for the camera to view what is being tracked.
The PiAware Web UI lets you view the aircraft it is currently tracking. It is available on port 8080 of the computer SkyScan is running on. For example:http://localhost:8080
Once you have SkyScan up an running, the next step is to dial it in.
It is important to have the camera as level as possible in order for it to track accurately. This can be done either by physically leveling the camera or adjusting configuration parameters for yaw, pitch, and roll corrections. TheManfrotto 410 Tripod Headmakes physical leveling easy because each of the axis has a geared adjustment knob.
Orientation corrections can also be applied via configuration. It is best to explore the correct setting dynamically by trying different values via MQTT. TheConfighas an example jupyter notebook that shows how to do that. Once you find acceptable values, enter them into your.envvalue so that they are used each time it is run.
Pointing the camera at static landmarks can help level the camera. To do that, start SkyScan using the following command:
docker compose -f docker-compose-manual.yamlThen refer to the section of theConfigJupyter notebook on manual control.
A control loop is used to track the aircraft. It takes into account where the camera currently is, where the aircraft is and how fast it is moving and then figures out how fast the camera needs to be moving in the Pan and Tilt axises. You can adjust how the control loop reacts to deltas between the camera and aircraft by adjust thePAN_GAINandTILT_GAINinaxis-ptz-controller.env.If the camera is oscillating around the plane, it is a sign that the gain needs to be reduced. If the camera is unable to keep up with the plane, then the gain can be increased. The gain values can be less than 1.0. You can experiment with different values using theConfigJupyter notebook.
It is likely that there will a number of obstacles around the camera that are blocking your view. If they are pretty uniform around the camera, you can specify aMIN_TILTvalue inskyscan-c2.envand it will ignore all aircraft below that tilt value. However, if the obstacles are less uniform you can use theOcclusion Mapperto ignore only portions of the cameras view area.
You can start up the Occlusion Mapper container with the following command:
docker compose -f docker-compose-occlusion.yamlFollowing the instructions in theOcclusion Mapperrepo for mapping out the obstacles. After you have finished mapping the occlusions, restart SkyScan using the normal docker-compose.yaml file.
IQT's EdgeTech framework is a modular approach for building systems. Each component of a system is a stand alone Docker container, which communicate between each other using MQTT messages.
The following EdgeTech modules are used in SkyScan:
- MQTT Dev:A Mosquito based MQTT Broker. It allows MQTT messages to be exchanged between the different SkyScan Modules. It has a very simple configuration to make initial deployments as easy as possible, but as a result there are no security features enabled,.This is not intended for production deployments!
- PiAware:A Docker Image of FlightAware'sPiAware distributionwhich is based around Dump1090. PiAware uses an attached SDR to receive ADS-B transmission and decode them. The decoded information is provided as JSON and viewable through a Web UI.
- Dump1090 JSON:This is a translation module which, on regular interval, will ingest the JSON output from PiAware, convert all of the values into metric and then publish it over MQTT.
- Object Ledger:Consolidates the information from multiple location providers into a unified list. This combined ledger is sent out on MQTT at a regular interval.
- SkyScan C2:Selects which aircraft from Object Ledger's list the camera should track. There are a number of parameters that can be set to help make sure the aircraft is visible to the camera.
- Axis PTZ Controller:Controls an Axis PTZ camera to track the selected aircraft. While it is important to try and have the camera be leveled and positioned facing to true North, the Controller can apply corrections to help compensate. There are also parameters that can be configured to help tune the Controllers tracking of the aircraft. The Controller will also instruct the camera to capture an image of the aircraft at a set interval.
Optional Modules
- Occlusion Mapper:This can be used to map out areas where the camera's view is blocked so that aircraft in those areas will not be tracked. This is helpfully if the camera is positioned near buildings or trees and does not have a clear view.
A Docker Compose file is provided in order to make it easy to startup the SkyScan modules. The optionalOcclusion Mappermodule is commented out in order to try and make it as easy as possible to get started. Once you have SkyScan successfully deployed, you can uncomment these modules as needed.
Parameters are passed to the modules via Environment variables which are read in from Environment files by Docker Compose. The core Environment variables are stored in the.envfile. These are variables that are either used by multiple modules or are values that you will need to configure. A template for that file is in[skyscan.env](./skyscan.env).Each module will also have its own.envfile, for exampleobject-ledger.env.Variables that are specifically for that module are in these files. They come with sane defaults and you may not need to make changes. Each file is commented to better explain how to configure the values.
The different EdgeTech modules used for SkyScan communicate with each other viaMQTTmessages. This allows for SkyScan to be deployed over multiple computers, as long as they have a network connection. The communication is organized into different Topics that the modules publish and subscribe to. The name for these Topics is passed to the Docker containers using environment variables. The various topics used are listed below:
| Env Variable | MQTT Feed | Publish | Subscribe | Data Payload |
|---|---|---|---|---|
| CONFIG_TOPIC | /skyscan/DEPLOYMENT/Config/skyscan-c2/JSON | axis-ptz-controller | axis-ptz-controller | Configuration |
| auto-orienter | auto-orienter | |||
| occlusion-mapper | occlusion-mapper | |||
| skyscan-c2 | ||||
| ORIENTATION_TOPIC | /skyscan/DEPLOYMENT/Orientation/edgetech-auto-orienter/JSON | auto-orienter | axis-ptz-controller | Orientation |
| IMAGE_FILENAME_TOPIC | /skyscan/DEPLOYMENT/Image_Filename/edgetech-axis-ptz-controller/JSON | axis-ptz-controller | ImageFileName | |
| IMAGE_CAPTURE_TOPIC | /skyscan/DEPLOYMENT/Image_Capture/edgetech-axis-ptz-controller/JSON | axis-ptz-controller | yolo-detect | ImageMetadata |
| MANUAL_CONTROL_TOPIC | /skyscan/DEPLOYMENT/Manual_Control/edgetech-axis-ptz-controller/JSON | occlusion-mapper | axis-ptz-controller | Manual Control |
| LOGGER_TOPIC | /skyscan/DEPLOYMENT/Logger/edgetech-axis-ptz-controller/JSON | axis-ptz-controller | Logger | |
| ADS_B_JSON_TOPIC | /skyscan/DEPLOYMENT/ADS-B/edgetech-dump1090-json/JSON | dump1090-json | object-ledger | ADS-B |
| LEDGER_TOPIC | /skyscan/DEPLOYMENT/Ledger/edgetech-object-ledger/JSON | object-ledger | skyscan-c2 | ObjectLedger |
| OBJECT_TOPIC | /skyscan/DEPLOYMENT/Object/skyscan-c2/JSON | skyscan-c2 | axis-ptz-controller | Selected Object |
| MANUAL_OVERRIDE_TOPIC | /skyscan/DEPLOYMENT/Manual_Override/skyscan-c2/JSON | skyscan-c2 | ObjectIDOverride | |
| OBJECT_DETECTION_TOPIC | /skyscan/DEPLOYMENT/Detections/edgetech-yolo-detect/JSON | yolo-detect | auto-orienter | Detection |
Distributed under theApache 2.0.SeeLICENSE.txtfor more information.
- Email:[email protected]
See our other projects:https://github.com/IQTLabs/