> 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/documentation/features/device-categories.md).

# Device Categories

Device Categories let you classify your devices with a **name**, a **curated icon**, and a **colour**. The category is reflected everywhere a device appears — the live map marker, the device list badge, filter dropdowns, and alert and workflow conditions — giving your fleet a consistent, at-a-glance visual identity.

***

## System vs Custom Categories

AdaTrack ships with six **built-in system categories** that are visible to all users and cannot be deleted:

| Name                 | Icon        | Default colour   |
| -------------------- | ----------- | ---------------- |
| Unknown              | Pin         | Grey `#6B7280`   |
| GPS Tracker          | Map pin     | Blue `#3B82F6`   |
| Environmental Sensor | Thermometer | Green `#10B981`  |
| Actuator             | Bolt        | Amber `#F59E0B`  |
| Gateway              | Router      | Purple `#8B5CF6` |
| Truck / Vehicle      | Truck       | Red `#EF4444`    |

You can create **custom categories** on top of these. Custom categories count toward your tier quota (see [Quota Management](/docs/documentation/administration/quotas.md)); system categories do not.

***

## Creating a Category

1. Navigate to **Settings > Device Categories** (or open **Devices** and click **Manage Categories**).
2. Click **New Category**.
3. Enter a name (up to 100 characters).
4. Select an icon from the curated catalogue.
5. Pick a colour from the predefined palette.
6. Save.

The new category is immediately available in the device creation and edit forms.

***

## Assigning a Category to a Device

1. Open the device in **Devices > Edit** (or during device creation).
2. In the **Category** field, select from the list of your system and custom categories.
3. Save the device.

The live map marker and device list badge update instantly to reflect the category's icon and colour.

***

## Editing and Deleting Categories

* **Edit:** Click the pencil icon next to a custom category to change its name, icon, or colour. Changes propagate to all devices that use that category without any device reassignment.
* **Delete:** Click the trash icon. The category must have no devices assigned before deletion is allowed. Reassign any devices first, or the API will return `409 Conflict`.
* **System categories** cannot be edited or deleted.

***

## Quota

| Tier                   | Custom category limit |
| ---------------------- | --------------------- |
| Community / Free       | 5                     |
| Standard               | 50                    |
| Enterprise / Unlimited | Unlimited             |

The current usage and limit are shown in the **Device Categories** page header. When the limit is reached, the **New Category** button is disabled and the API returns `403 Forbidden` for new category creation attempts.

***

## Filtering by Category

Wherever devices are listed or visualised, a **Category** filter is available:

* **Live map legend** — toggle category layers on/off to isolate specific device types on the map.
* **Devices list** — filter the table by one or more categories.
* **Alert rules** — scope a rule to devices matching a specific category.
* **Geofences** — target enter/exit notifications at a category group.
* **Workflow triggers** — filter the `Telemetry Received` trigger by category.
* **Reports** — group or filter the device selection in the Report Designer by category.

***

## Permissions

| Permission slug          | Default role | Description              |
| ------------------------ | ------------ | ------------------------ |
| `device_category:list`   | User         | View the categories list |
| `device_category:create` | User         | Create custom categories |
| `device_category:update` | User         | Edit custom categories   |
| `device_category:delete` | User         | Delete custom categories |

Users manage their own categories; admins can manage categories across all users.