Seri protokol v2

Bu sayfa geliştiriciler içindir. Firmware 1.2.0 · proto: 2. Refix Studio ve firmware bu sözleşmeye birebir uyar.

USB CDC, 115200 baud, satırlar \n ile biter. Bir komut en fazla 600 karakter (aşılırsa ERR:long). Her yanıt tek satırdır ve önekle başlar. Cihaz ayrıca kendiliğinden akış satırları yayar.

Kurulum akışındayken (logo, tanıtım, sihirbaz) SAY, MOOD, PREVIEW komutları ERR:busy döner; CFG kaydedilir ama ekran değişmez.

Komutlar

Komut	Yanıt	Açıklama
`HELLO`	`HELLO:{json}`	Cihaz bilgisi
`GET`	`CFG:{json}`	Kayıtlı ayarlar
`CFG:{json}`	`OK:cfg` · `ERR:json` · `ERR:invalid`	Ayarları uygula ve kalıcı kaydet
`PREVIEW:<id>`	`OK:preview` · `ERR:invalid` · `ERR:busy`	Karakteri kaydetmeden dene; Refix kendini tanıtır
`PREVIEW:off`	`OK:preview`	Kayıtlı karaktere dön
`SAY:<metin>`	`OK:say` · `ERR:busy`	Refix söyler (UTF-8, Türkçe destekli)
`MOOD:<happy\|angry\|sleep\|talk\|neutral>`	`OK:mood` · `ERR:invalid` · `ERR:busy`	Duygu göster (uyku hariç 4 sn)
`TIME:<epoch>,<tzSaniye>`	`OK:time` · `ERR:invalid`	Saat eşitleme; `tzSaniye` UTC'nin doğusundaki fark (TR = `10800`)
`CAL`	`OK:cal` · `ERR:imu`	Kurulum sihirbazını yeniden başlat
`RESET`	`OK:reset`	Ayarları sil (kalibrasyon ve skorlar kalır)
`FACTORY`	`OK:factory`	Her şeyi sil, ilk açılış akışını başlat
bilinmeyen	`ERR:unknown`

HELLO

HELLO örneği (gerçekte tek satır):

HELLO:{"fw":"1.2.2","proto":2,"board":"esp32c3","imu":true,"cal":true,"turn":true,"character":"fire",
"chars":[{"id":"fire","name":"Alev","element":"Ateş"},{"id":"water","name":"Damla","element":"Su"},
{"id":"earth","name":"Kaya","element":"Toprak"},{"id":"air","name":"Esme","element":"Hava"}],
"apps":[{"id":"pomodoro","name":"Pomodoro"},{"id":"clock","name":"Saat"},{"id":"tracker","name":"Takipçi"},
{"id":"pingpong","name":"Ping-Pong"},{"id":"balance","name":"Denge"},{"id":"rhythm","name":"Ritim"}],
"talk":["off","low","medium","high"],"control":["tilt","turn","hybrid"]}

imu: false ise hareket sensörü bulunamamıştır; cal: false ise kurulum sihirbazı tamamlanmamıştır. 1.2.1 ile gelen alanlar: turn (çevirme yönü öğrenildi mi), talk ve control (cihaz ayarlarının geçerli değerleri; yoksa cihaz bu ayarları desteklemiyordur). apps yalnızca menü slotlarına konabilen uygulamalardır; Oyunlar klasörü ve Ayarlar menüde hep vardır.

Ayar dosyası

Ayar dosyası (CFG gövdesi, GET yanıtı ve Studio'nun indirdiği/yüklediği JSON aynı biçimdedir):

{"version":1,"name":"Refix","character":"fire","menuSlots":["pomodoro","clock","balance"],"quote":"Bugün harika kod yazacağız!"}

Alan	Kural
`version`	`1` (dosya biçimi sürümü)
`name`	≤ 48 bayt UTF-8
`character`	`chars` içindeki bir `id`; bilinmiyorsa `ERR:invalid`
`menuSlots`	Tam 3 eleman, her biri `apps` içindeki bir `id` (tekrar edebilir)
`quote`	≤ 128 bayt, boş olabilir
`talk`	İsteğe bağlı, `HELLO.talk` içindeki bir değer; yoksa cihazdaki kalır
`control`	İsteğe bağlı, `HELLO.control` içindeki bir değer; yoksa cihazdaki kalır
`sulk`	İsteğe bağlı, `true` / `false`

GET yanıtında talk, control ve sulk her zaman bulunur (1.2.1+). control çevirme içeren bir değere değişirse ve çevirme yönü henüz öğrenilmemişse cihaz kısa bir çevirme kurulumu açar.

Geriye uyumluluk: character yoksa eski eyeStyle alanı okunur, tanınmazsa fire kullanılır.

Akış satırları

Satır	Ne zaman
`IMU:<roll>`	Her 150 ms; kalibre sağ/sol eğim, derece, 1 ondalık, sağa +
`GEST:<left\|right\|confirm\|cancel>`	Her algılanan hareket
`ERR:fb`	Açılışta ekran belleği ayrılamadıysa

Karakterler

id	Ad	Element	Vurgu	Göz (g×y, ara, köşe)	Sabır	Konuşma
`fire`	Alev	Ateş	`#FF7828`	52×66, 28, 20	2	hızlı (26 ms)
`water`	Damla	Su	`#28AAFF`	58×58, 28, 29	4	sakin (38 ms)
`earth`	Kaya	Toprak	`#96C850`	56×50, 30, 8	5	yavaş (46 ms)
`air`	Esme	Hava	`#C8E1FF`	60×40, 26, 20	3	hızlı (30 ms)

Sabır: Refix'in sorusu cevapsız kalırsa ya da reddedilirse sabrı azalır; bu sayıya ulaşınca 1 dakika küser.

İstemci notları

Refix Studio bu sözleşmeyi şöyle uygular (kaynak: src/lib/refix/):

Satır okuyucu: Gelen baytlar akış modunda UTF-8 olarak çözülür, \n ile bölünür, \r atılır.
Komut kuyruğu: Her komut sırayla gönderilir ve kendi yanıtını bekler: HELLO → HELLO:, GET → CFG:, diğerleri → OK:. Her komut ERR: alabilir. Yanıt ~2 sn içinde gelmezse komut zaman aşımına uğrar ve sıradakine geçilir.
Akış ayrımı: IMU:, GEST: ve ERR:fb satırları hiçbir komutun yanıtı sayılmaz.
El sıkışma: HELLO → proto !== 2 ise güncelleme uyarısı → GET → TIME:<epoch>,<tz> (tz = -new Date().getTimezoneOffset() * 60).
Kimlikler: Arayüz yalnızca cihazın HELLO.chars / HELLO.apps listesinde bildirdiği kimlikleri gönderir. Sitenin listesi (src/data/refix.ts) cihazınkinden farklıysa geliştirici konsoluna uyarı yazılır.

Örnek oturum

→ HELLO
← HELLO:{"fw":"1.2.2","proto":2,...}
→ GET
← CFG:{"version":1,"name":"Refix","character":"fire","menuSlots":["pomodoro","clock","rhythm"],"quote":"Bugün harika kod yazacağız!","talk":"medium","control":"hybrid","sulk":true}
→ TIME:1791273600,10800
← IMU:-0.4
← OK:time
→ PREVIEW:water
← OK:preview
← GEST:right
→ CFG:{"version":1,"name":"Refix","character":"water","menuSlots":["pomodoro","clock","rhythm"],"quote":"","talk":"low"}
← OK:cfg