> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/help-center/faq.md).

# FAQ

### General

#### What is AdaTrack?

AdaTrack is a high-performance IoT platform for real-time tracking and geospatial analytics. It is designed to handle thousands of concurrent UDP telemetry streams with backend-defined decoding.

#### Can I self-host AdaTrack?

Yes, AdaTrack can be deployed on your own infrastructure (AWS EC2, Docker) for full control over your data. Self-hosted installations run as a free Community Edition out of the box, with optional paid licenses for higher limits. Refer to the [Self-hosted Deployment](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/getting-started/self-hosted.md) guide and the [Licensing guide](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/administration/licensing.md).

#### Which IoT protocols are supported?

AdaTrack ingests **UDP** (HMAC-signed, lowest overhead), **MQTT**, **Teltonika Codec8 TCP** and **Queclink @Track TCP**. See [IoT Ingestion](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/iot-ingestion/README.md). Copy-paste UDP clients for Arduino, ESP32, STM32 and Python are in [Firmware & Client Examples](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/iot-ingestion/firmware/README.md).

### Devices & Telemetry

#### How do I add a new device?

You must first create a **Device Profile** that defines the decoding logic (JavaScript) for your hardware. Once the profile is created, you can register individual devices by their unique IDs and HMAC keys.

#### What is a payload decoder?

A payload decoder is a small JavaScript snippet that AdaTrack executes to convert binary telemetry data into a JSON format. You can update decoders in real-time without restarting the platform.

#### How is telemetry data secured?

AdaTrack uses **HMAC-SHA256** for authenticating UDP packets. Each device has a unique shared secret. We also use timestamps to prevent replay attacks.

### Billing & Quotas

#### How does the usage-based billing work?

AdaTrack tracks "Billable Events," such as telemetry packets processed, reports generated, and workflow executions. You are billed based on your subscription tier and actual usage recorded in the **Usage Ledger**.

#### What happens if I exceed my quota?

If you exceed your account quota (e.g., maximum number of geofences or monthly reports), AdaTrack will send a notification. Depending on your tier, further actions may be limited until the quota is increased or reset.

### Self-Hosted Licensing

#### Do I need a license to run AdaTrack self-hosted?

No. AdaTrack runs as a free **Community Edition** with no license key required. All features are available within the Community tier limits (e.g., 5 devices, 10 alert rules). Paid licenses unlock higher or unlimited limits.

#### Does the license require an internet connection?

No. License verification is fully offline — there are no call-home checks. Your license is verified locally by the server binary.

#### What happens when my license expires?

AdaTrack provides a 7-day grace period after expiry. During this time, your existing limits remain active. After the grace period, the server falls back to Community Edition limits. No data is lost. Apply a renewed license to restore your tier.

#### How do I apply a license?

Set the `ADATRACK_LICENSE_KEY` environment variable to your license token, or point `ADATRACK_LICENSE_FILE` to your `.adatrack.lic` file. See the full [Licensing guide](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/administration/licensing.md) for step-by-step instructions.

### Support

#### How can I report a bug?

Please open an issue on our [GitHub repository](https://github.com/AdaTrack/adatrack/issues) or contact support directly via our Discord community.