Eklenti
RehberiPlugin
Guide

Nasıl ÇalışırHow It Works

Bir ekran eklentisi, cihazın içerik döngüsünde gösterilen bir ekran ve kullanıcı tarafından ayarlanabilen bir ayar şeması'dır. manifest.json eklentiyi tanımlar; schema.json uygulamanın çizdiği ayar formunu tanımlar. A screen plugin is a screen shown in the device's content rotation plus a user-editable settings schema. manifest.json describes the plugin; schema.json describes the settings form the app renders.

Klasör YapısıFolder Structure

Eklentiler cihazda /plugins/<id>/ altında bulunur. Klasör adı manifest.id ile aynı olmalıdır.Plugins live under /plugins/<id>/ on the device. The folder name must be the same as manifest.id.

• manifest.json — zorunlu. Eklenti kimliği ve davranışı.required. Plugin identity and behavior.
• schema.json — ayar formu (opsiyonel). Eski ad config_schema.json da kabul edilir.settings form (optional). Legacy name config_schema.json is also accepted.
• settings.json — cihazın ürettiği güncel ayar değerleri.current setting values, generated by the device.
• preview.png — opsiyonel önizleme.optional preview.

manifest.json

schema_version 1 olmalıdır. Çözünürlük tam olarak 240x240.schema_version must be 1. Resolution is exactly 240x240.

{
  "schema_version": 1,
  "id": "borsa",
  "name": "Borsa Takip",
  "version": "1.0.0",
  "description": "Tek veya coklu hisse senedi takibi",
  "author": "Arda",
  "display_mode": "content_only",
  "renderer": "builtin:borsa",
  "target_resolution": "240x240"
}

AlanField	ZorunluRequired	AçıklamaDescription
schema_version	✓	Her zaman 1.Always 1.
id	✓	Benzersiz; küçük harf, rakam, _, -. Klasör adıyla aynı.Unique; lowercase, digits, _, -. Same as folder name.
name	✓	Görünen ad.Display name.
version	—	Sürüm (vars. 0.0.1).Version (def. 0.0.1).
description	—	Kısa açıklama.Short description.
author	—	Yazar (vars. Anonim).Author (def. Anonim).
display_mode	—	content_only · menu_only · both
renderer	—	Yerleşik render: builtin:<ad>.Built-in renderer: builtin:<name>.
resolution	—	240x240
remote_control	—	Dokunma döngüsü (aşağıda).Tap cycle (below).

Cihaz butonuyla ekranda adımlar arasında geçiş için remote_control.tap_cycle tanımlayabilirsin:Define remote_control.tap_cycle to step through views with the device button:

"remote_control": {
  "tap_cycle": [ { "label": "Liste" }, { "label": "Grafik" } ]
}

display_mode

DeğerValue	AnlamıMeaning
content_only	Sadece içerik döngüsünde görünür (varsayılan).Appears only in the content rotation (default).
menu_only	Sadece ana menüde bir öğe olarak.Only as an item in the main menu.
both	Hem içerik döngüsü hem menü.Both content rotation and menu.

schema.json

Ayar formunu tanımlar. fields dizisindeki her alan uygulamada bir UI bileşenine dönüşür; cihaz değerleri settings.json'a yazar.Defines the settings form. Each item in fields becomes a UI widget in the app; the device writes values to settings.json.

{
  "schema_version": 1,
  "plugin_id": "borsa",
  "fields": [
    { "key": "stock_count", "label": "Hisse sayisi", "type": "int", "default": "0" }
  ]
}

AlanField	AçıklamaDescription
key	Ayar anahtarı; cihaz settings[key] ile okur.Setting key; device reads settings[key].
label	Kullanıcıya gösterilen etiket.Label shown to the user.
type	Alan tipi (aşağıda).Field type (below).
default	Varsayılan değer (string).Default value (string).
options, min, max, step	Tipe göre ek alanlar.Type-specific extras.

Alan TipleriField Types

Desteklenen tipler ve cihazda okunuşları:Supported types and how the device reads them:

type	UI	ESP32 okumaESP32 read
string	Metin kutusuText field	settings["key"]
color	Renk seçici (hex)Color picker (hex)	settings["key"] → "#rrggbb"
int	− / + stepper (min/max/step)− / + stepper (min/max/step)	settings["key"].toInt()
slider	Sürgü (min/max/step)Slider (min/max/step)	settings["key"].toFloat()
bool	AnahtarSwitch	settings["key"] == "true"
select	Açılır liste (options)Dropdown (options)	settings["key"]

Hepsi bir arada örnek:All types together:

{
  "fields": [
    { "key": "view_mode",   "type": "select", "label": "Gorunum", "default": "monthly",
      "options": ["monthly", "weekly", "3-day"] },
    { "key": "bg_color",    "type": "color",  "label": "Arka Plan", "default": "#0a0f1e" },
    { "key": "brightness",  "type": "int",    "label": "Parlaklik", "default": "200",
      "min": 0, "max": 255, "step": 5 },
    { "key": "speed",       "type": "slider", "label": "Hiz", "default": "1.0",
      "min": 0.1, "max": 5.0, "step": 0.1 },
    { "key": "start_monday","type": "bool",   "label": "Pazartesi Baslasin", "default": "true" },
    { "key": "footer_text", "type": "string", "label": "Alt Yazi", "default": "" }
  ]
}

settings.json

Kullanıcı uygulamadan ayar kaydedince cihaz bu dosyayı üretir. Render kodu değerleri buradan okur. Sen bu dosyayı elle hazırlamazsın — şema yeter.The device generates this file when the user saves settings from the app. The render code reads values from here. You don't author this file by hand — the schema is enough.

{ "stock_count": "3", "bg_color": "#0a0f1e", "start_monday": "true" }

REST API

Cihaz yerel ağda HTTP API sunar. Başlıca eklenti uçları:The device exposes a local HTTP API. Main plugin endpoints:

Endpoint	AçıklamaDescription
GET /list_screen_plugins	Yüklü eklentiler + durum.Installed plugins + state.
GET /activate_screen_plugin	Aç/kapat (toggle).Toggle on/off.
POST /api/ensure_screen_plugin_active	Yanlışlıkla kapatmadan aktif tutar (ayar ekranlarında tercih edilir).Keeps active without accidental toggle-off (preferred in settings screens).
GET /get_plugin_settings	Eklentinin settings.json'ı.The plugin's settings.json.
POST /save_plugin_settings	Ayarları kaydet.Save settings.

SınırlarLimits

• En fazla 8 yüklü eklenti, aynı anda en fazla 3 aktif.At most 8 installed plugins, at most 3 active at once.
• id: küçük harf/rakam/_/-, en fazla 40 karakter; klasör adıyla aynı; / \ .. yasak.id: lowercase/digits/_/-, max 40 chars; same as folder; / \ .. forbidden.
• Hedef çözünürlük tam 240×240, schema_version: 1.Target resolution exactly 240×240, schema_version: 1.
• Aktif limit (3) doluysa aktivasyon sessizce başarısız olabilir → ensure_screen_plugin_active kullan.If the active limit (3) is full, activation can silently fail → use ensure_screen_plugin_active.