# Profile Definition & Schema

This document defines the **Profile System** schema which drives the `esp_viewer` framework.

## 1. Profile Schema (JSON)

The **Profile** is the core configuration file that defines how the generic framework interacts with a specific device.

### 1.1 Structure Overview
```json
{
  "meta": { ... },       // Metadata (Name, Version)
  "connection": { ... }, // Connection defaults (baud, eol)
  "parameters": [ ... ], // UI Controls & Command Definitions
  "streams": [ ... ],    // Data Parsing Rules (Values, Events)
  "plots": [ ... ]       // Visualization Layout
}
```

---

## 2. Component Definitions

### 2.1 Meta (`meta`)
Basic information about the profile.
- `name`: (String) Display name.
- `version`: (String) Version of the profile.

### 2.2 Connection (`connection`)
Default settings for the serial port.
- `baud`: (Integer) Initial baud rate.
- `eol`: (String) End-of-line character (e.g., `\n`, `\r\n`).

### 2.3 Parameters (`parameters`)
Defines the widgets in the "Config" panel and the commands sent to the device.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Unique identifier. |
| `label` | string | Display name in UI. |
| `widget` | string | `slider`, `combo`, `spinbox`, `button`, `radio`. |
| `set_template` | string | Command template sent on change. Use `{value}` placeholder. |
| `rx_regex` | string | Regex to parse the current value from device response. |

### 2.4 Streams (`streams`)
Defines how to parse incoming UART data lines.

#### Start-of-Line Delimiter
Used for high-speed sensor data.
- `header`: Line must start with this string.
- `delimiter`: Character to split by (e.g., `,`).
- `fields`: List of field names in order.

#### Regex Parser
Used for asynchronous events, markers, or logs.
- `regex`: Python-style regular expression.
- `type`: `marker`, `log`, or `data`.
- `static_attributes`: Constants (e.g., `color`, `label`) to apply to parsed events.

### 2.5 Plots (`plots`)
Defines the visualization layout.
- `title`: Window title.
- `stream_id`: ID of the stream providing the data.
- `y_items`: List of fields from the stream to plot on the Y-axis.

---

## 3. JSON Schema Reference

AI Agents and developers should use the following schema for validation.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "meta": { 
      "type": "object", 
      "required": ["name"],
      "properties": {
        "name": { "type": "string" },
        "version": { "type": "string" }
      }
    },
    "connection": { 
      "type": "object",
      "properties": {
        "baud": { "type": "integer" },
        "eol": { "type": "string" }
      }
    },
    "parameters": { "type": "array" },
    "streams": { "type": "array" },
    "plots": { "type": "array" }
  },
  "required": ["meta"]
}
```
