Configuration Reference

All fields in /etc/deskradar/config.json.

The configuration file is read at startup by the main deskradar app and validated by a Pydantic model. If the file is missing or contains invalid values, the app will exit with an error. Changes take effect after restarting the service (sudo systemctl restart deskradar). The web configurator at http://deskradar.local:5000/config handles saving and restarting automatically.

Example File

{
  "LAT": 50,
  "LON": 0,
  "GET_URL": "http://127.0.0.1:8080/data/aircraft.json",
  "MATRIX_HTTP_URL": "http://10.42.0.50",
  "LCD_SEND_URL": "http://0.0.0.0:8010/display",
  "MATRIX_SIZE_PX": 64,
  "DISPLAY_RADIUS_NM": 25,
  "DRAW_RETICULE": true,
  "MAX_HISTORY": 20,
  "POLL_CADENCE": 1,
  "FADE_FACTOR": 0.95,
  "MIN_ALT": 1000,
  "UNSEEN_MARK_SECS": 10,
  "MAX_UNSEEN_SECS": 20,
  "LONLAT_DECIMALS": 3,
  "MATRIX_HTTP_TIMEOUT": 2,
  "LCD_TIMEOUT": 1,
  "SHOW_CLOSEST": true,
  "CLOSEST_COLOUR": {"r": 255, "g": 255, "b": 255},
  "LOG_LEVEL": "info"
}

Location

Key	Type	Default	Description
`LAT`	float	50	Latitude of the display center in decimal degrees. Aircraft are plotted relative to this point.
`LON`	float	0	Longitude of the display center in decimal degrees.

Network URLs

Key	Type	Default	Description
`GET_URL`	string	`http://127.0.0.1:8080/data/aircraft.json`	dump1090 API endpoint to poll for aircraft data. Usually local to the Pi.
`MATRIX_HTTP_URL`	string	set by boot_check	Base URL of the MatrixPortal S3. Written automatically at boot by resolving `deskradar-portal.local`. Format: `http://<ip>` (no trailing slash, no port — port 80 is used).
`LCD_SEND_URL`	string	`http://0.0.0.0:8010/display`	URL of the LCD service endpoint. Points to the local deskradar-lcd FastAPI service.

GET_URL, LCD_SEND_URL, and MATRIX_HTTP_URL are hidden from the web configurator UI — they are managed by the system or rarely need manual changes.

Display

Key	Type	Default	Description
`MATRIX_SIZE_PX`	int	64	Pixel dimensions of the LED matrix (width and height). The matrix is assumed to be square.
`DISPLAY_RADIUS_NM`	float	25	Radius of the displayed area in nautical miles, centered on `LAT`/`LON`. Aircraft beyond this radius are not shown.
`DRAW_RETICULE`	bool	true	Draw a crosshair/reticule at the display center to indicate the reference location.
`SHOW_CLOSEST`	bool	true	Highlight the nearest aircraft in `CLOSEST_COLOUR` and display its callsign on the LCD.
`CLOSEST_COLOUR`	object	`{"r":255,"g":255,"b":255}`	RGB color used to highlight the closest aircraft. Must include `r`, `g`, and `b` keys with values 0–255.

Tracking

Key	Type	Default	Description
`MAX_HISTORY`	int	20	Maximum number of historical position points retained per aircraft track. Older points are dropped from the tail of the list.
`POLL_CADENCE`	float	1	Seconds between polling cycles. Lower values increase responsiveness but also CPU and network load.
`FADE_FACTOR`	float	0.95	Multiplier applied to trail point colors each cycle (0.0–1.0). 0.95 means each point's brightness drops by 5% per second at 1-second cadence. Lower values fade trails faster.
`MIN_ALT`	int	1000	Minimum altitude in feet for an aircraft to appear on screen. Filters out ground traffic and very-low-altitude aircraft.
`UNSEEN_MARK_SECS`	int	10	Seconds without a new position update before an aircraft's trail is colored red (stale indicator).
`MAX_UNSEEN_SECS`	int	20	Seconds without any update before an aircraft is removed from the display entirely.
`LONLAT_DECIMALS`	int	3	Decimal precision used when rounding lat/lon values during data processing. 3 gives ~110 m resolution.

Timeouts

Key	Type	Default	Description
`MATRIX_HTTP_TIMEOUT`	int	2	Seconds before HTTP requests to the MatrixPortal time out. Should be less than `POLL_CADENCE` to avoid blocking the loop.
`LCD_TIMEOUT`	int	1	Seconds before HTTP requests to the LCD service time out.

Logging

Key	Type	Default	Allowed Values
`LOG_LEVEL`	string	`"info"`	`debug`, `info`, `warning`, `error`, `critical` (case-insensitive)

Derived Fields (read-only)

These are computed from other config values and cannot be set manually. They are calculated at startup by the Pydantic model:

Field	Description
`THOLDS`	Tuple of 4 values: (lat_min, lat_max, lon_min, lon_max) computed from `LAT`, `LON`, and `DISPLAY_RADIUS_NM` using geopy's geodesic distance.
`LAT_MIN` / `LAT_MAX`	Southern and northern latitude bounds of the display area.
`LON_MIN` / `LON_MAX`	Western and eastern longitude bounds of the display area.
`LAT_RANGE`	NumPy linspace array of 64 latitude values evenly spanning `LAT_MIN` to `LAT_MAX`. Used for pixel mapping.
`LON_RANGE`	NumPy linspace array of 64 longitude values evenly spanning `LON_MIN` to `LON_MAX`.

Web Configurator

All fields except GET_URL, LCD_SEND_URL, and MATRIX_HTTP_URL are editable via the web UI at http://deskradar.local:5000/config.

The UI handles type coercion automatically — integer fields stay integers, floats stay floats. The CLOSEST_COLOUR field is presented as a color picker and converted between hex and RGB dict format transparently.