Sistem Konsolu — Firmware · OTA
Sistem Konsolu (/console), platform yöneticileri (süper yönetici) için
ayrılmış bir kontrol panelidir. Firmware · OTA (/console/firmware) sayfası,
platformdaki tüm firmaların (tenant) ESP32 gateway'lerine yönelik firmware
kataloğunu ve uzaktan güncelleme (OTA) süreçlerini tek merkezden yönetmenizi
sağlar: firmware sürümü yükleme/yayınlama, tekil ve firmalar arası (cross-tenant)
toplu OTA başlatma, rollback ve takılan güncellemeleri teşhis edip temizleme.
Firmware · OTA yalnızca süper yönetici yetkisine sahip platform operatörlerine açıktır. Firma (tenant) kullanıcıları bu ekranı görmez. İşlemler firmalar arası (cross-tenant) yapılır: bir süper yönetici herhangi bir firmanın gateway'inde OTA başlatabilir.
Firmware, cihazın çalıştırdığı donanım/protokol seviyesi yazılımdır — yanlış ya da uyumsuz bir sürüm bir gateway'i çevrimdışı bırakabilir, telemetri bütünlüğünü bozabilir. Bu yüzden firmware kataloğu tek merkezî kaynak olarak tutulur ve yönetimi yalnız süper yöneticiye açıktır (Modbus register haritası kilidiyle aynı vizyon). Firmware, bir firmanın kendi başına ayarladığı bir tercih değil, platform genelinde tutarlı yönetilen bir varlıktır.
Firma menüsündeki eski Firmware ve Toplu OTA girişleri kaldırıldı; tüm
firmware/OTA yönetimi bu konsol modülünde toplandı. Daha önce kaydettiğiniz
/admin/firmware veya /admin/batch-ota bağlantıları otomatik olarak
/console/firmware sayfasına yönlendirir. Cihaz tarafında hiçbir değişiklik
yoktur — OTA altyapısı, MQTT komut akışı ve cihaz firmware indirme yolu aynıdır.
Özet göstergeler (KPI) — tıklanabilir hızlı geçiş
Sayfanın üstünde dört canlı sayaç bulunur (yaklaşık 30 saniyede bir tazelenir). Her biri, ilgili sekmeye götüren bir kısayoldur:
| Gösterge | Anlamı | Tıklanınca |
|---|---|---|
| Firmware Sürümü | Kullanımdaki (kullanımdan kaldırılmamış) firmware sürümü sayısı. | Katalog sekmesi. |
| Kritik Sürüm | "Kritik" işaretli sürüm sayısı (0'dan büyükse sarı vurgulanır). | Katalog sekmesi. |
| Beta Sürüm | Beta kanalındaki sürüm sayısı. | Katalog sekmesi. |
| Takılan Cihaz | Son 24 saattir OTA'da ilerlemeyen cihaz sayısı (0'dan büyükse kırmızı vurgulanır). | Takılan Cihazlar sekmesi. |
Sayfa dört sekmeden oluşur: Katalog, Toplu OTA, Tekil OTA ve
Takılan Cihazlar. Sekmeye ?tab= parametresiyle doğrudan (derin-link) de
açılabilir.
1. Katalog — firmware sürümlerini yönet
Katalog sekmesi firmware sürümlerinin tek kaynağıdır: yeni sürüm yükleme, yayınlama (latest yapma) ve kullanımdan kaldırma (deprecate) buradan yapılır.
Yeni firmware yükleme
Üstteki Yeni Firmware Yükle formu bir .bin dosyasını ve meta bilgisini
alır. Alanlar:
| Alan | Zorunlu | Açıklama |
|---|---|---|
| Firmware Dosyası (.bin) | ✅ | Yalnızca .bin uzantısı kabul edilir; en fazla 2 MB (ESP32 flash bölümü sınırı). Yanlış uzantı veya büyük dosya anında reddedilir. |
| Sürüm | ✅ | Semantik sürüm (ör. 2.0.0). |
| Donanım Sürümü | — | Uyumlu donanım revizyonu (varsayılan 1.0). Ardışık yüklemelerde korunur. |
| Yayın Kanalı | — | Stable veya Beta (varsayılan Stable). |
| Min. Gerekli Sürüm | — | Bu sürüme geçmeden önce cihazda olması gereken en düşük sürüm (opsiyonel). |
| Değişiklik Notları (Changelog) | ✅ | Sürümdeki değişiklikler — zorunludur (boş bırakılamaz). |
| Yayın Açıklaması | — | Serbest metin ek açıklama (opsiyonel). |
| Kritik güncelleme (zorunlu OTA) | — | İşaretlenirse sürüm "Kritik" rozetiyle işaretlenir. |
Yükle düğmesi ancak dosya + sürüm + changelog dolu olduğunda etkinleşir.
"Kritik" işaretliyken formun altında Kritik firmware tüm gateway'lerde zorunlu güncelleme tetikleyebilir. uyarısı görünür — bu bilinçli bir karardır.
Filtreleme ve katalog tablosu
Formun altında kanal çipleri (Tümü / Stable / Beta) ve Kullanımdan kaldırılanları göster anahtarı ile liste daraltılır. Tablo sütunları:
| Sütun | Açıklama |
|---|---|
| Sürüm | Sürüm numarası ve altında cihaz tipi. |
| Kanal | Stable / Beta rozeti. |
| Boyut | .bin dosya boyutu (KB). |
| Durum | Yayında (kanalın en güncel sürümü) / Kritik / Kullanımdan kaldırıldı rozetleri. |
| Oluşturma | Sürümün yüklenme zamanı. |
| İşlem (⋮) | Yayınla / Kullanımdan kaldır. |
Yayınla (release)
⋮ → Yayınla, sürümü kanalının en güncel (latest / "Yayında") sürümü olarak işaretler ve cihazlara duyurur. Aynı kanaldaki önceki "Yayında" sürümün işareti otomatik geri alınır. Onay penceresi metin girişi istemez (geri alınabilir bir işlemdir). Zaten "Yayında" olan ya da kullanımdan kaldırılmış bir sürümde bu seçenek pasiftir.
Kullanımdan kaldır (deprecate) — sebep zorunlu
⋮ → Kullanımdan kaldır, sürümü emekliye ayırır. Onay penceresinde sebep yazmak zorunludur — sebep boşken "Kullanımdan kaldır" düğmesi pasif kalır.
Kullanımdan kaldırılan sürüm yeni OTA güncellemelerinde artık seçilemez (Toplu/Tekil OTA firmware listesinde görünmez). Ancak o sürümü halihazırda çalıştıran cihazlar etkilenmez — geriye dönük bir zorlama yapılmaz. Yani "deprecate" bir hatırlatma/engelleme değil, yalnızca ileriye dönük seçim kısıtıdır.
2. Toplu OTA — cross-tenant hedef seçip parti parti güncelle
Toplu OTA sekmesi, birden çok gateway'i tek işte güncellemenizi sağlar. Gateway'ler firmalar arası listelenir; farklı firmaların gateway'lerini aynı partiye alabilirsiniz.
Hedef seçimi (Gateway filo seçici)
- Filtreler — Tenant (Tüm tenant'lar / belirli firma), Durum (Aktif / Pasif / Çevrimdışı / Hata) ve arama (gateway adı veya MAC). Filtre değişince liste ilk sayfaya döner; sonuçlar Önceki / Sonraki ile sayfalanır.
- Tablo — her satırda seçim kutusu, gateway adı + MAC, bağlı olduğu firma, mevcut firmware sürümü ve durum (gateway + MQTT rozeti) yer alır.
- Seçim özeti — kaç gateway seçildiğini gösterir; Seçimi temizle ile sıfırlanır.
Henüz bir firmaya sahiplenilmemiş (unclaimed) gateway'ler tabloda "Sahiplenilmemiş" rozetiyle ve seçilemez (soluk/pasif) satır olarak görünür. Sebep: sahibi olmayan bir gateway için firma-izolasyonlu MQTT komut kanalı kurulamaz. Böyle bir hedefi yine de göndermeye çalışırsanız sistem işlemi "GATEWAY_NOT_CLAIMED" (400) ile reddeder. Bu yüzden seçici bu gateway'leri baştan devre dışı bırakır (erken uyarı).
Parti düzeni ve başlatma
- Firmware — yalnız kullanımdaki (deprecated olmayan) sürümler listelenir.
- Parti Boyutu — aynı anda kaç gateway'in güncelleneceği (1–50). Büyük filolarda bant genişliğini ve broker yükünü dengelemek için kullanılır.
- Partiler Arası Bekleme (saniye) — her parti arasında verilen ara (0–3600).
Seçim yapıldığında sistem kaba bir tahmini süre gösterir (parti sayısı × bekleme). Toplu OTA Başlat işi kuyruğa alır ve kaç gateway'in hedeflendiğini bildirir.
Başlatma sonrası bildirilen gateway sayısı, seçtiğiniz listeden küçük olabilir: sistem sahiplenilmemiş hedefleri sessizce ayıklar ve yalnız geçerli gateway'leri işler. Aradaki fark "atlanan sahiplenilmemiş hedef" demektir. (Seçici bunları zaten devre dışı bıraktığından normal akışta bu fark oluşmaz.)
Toplu OTA işleri
Alttaki tablo başlatılan işleri (yaklaşık 30 saniyede bir tazelenir) listeler: firmware sürümü + gateway sayısı, ilerleme çubuğu (tamamlanan / toplam / hatalı), durum (Bekliyor / Sürüyor / Tamamlandı / İptal edildi / Başarısız) ve oluşturma zamanı. Bekliyor veya Sürüyor durumundaki işler satırdaki İptal düğmesiyle durdurulabilir.
3. Tekil OTA — tek gateway güncelleme + rollback
Tekil OTA sekmesi tek bir gateway'i hedefler; hem ileri güncelleme hem de geri alma (rollback) buradan yapılır.
OTA gönderme
- Gateway seçimi — Toplu OTA'daki aynı filo seçicisi, bu kez tek seçim (radyo) modunda. Sahiplenilmemiş gateway'ler yine seçilemez. Seçilen gateway'in adı ve MAC'i özet satırında görünür.
- Firmware — hedef sürüm (deprecated olmayanlar).
- Zorla (sürüm kontrolünü atla) — sürüm karşılaştırmasını atlayarak gönderir.
- Sürüm düşürmeye izin ver — daha eski bir sürüme geçişe (downgrade) izin verir.
OTA Gönder işlemi başlatır ve hedef sürümü bildirir.
Rollback — sebep zorunlu
Seçili gateway için Rollback düğmesi, cihazı bir önceki firmware sürümüne geri alır. Onay penceresinde sebep yazmak zorunludur (ör. "yeni sürümde açılış hatası") — sebep boşken düğme pasiftir. Komut, gateway'in kendi firmasının MQTT kanalından gönderilir.
OTA geçmişi
Alttaki tablo bu gateway'e ait güncellemeleri (yaklaşık 30 saniyede bir tazelenir) gösterir: gateway kimliği (kısa), hedef sürüm, ilerleme, durum (Bekliyor / Planlandı / İndiriliyor / Sürüyor / Tamamlandı / Başarılı / Başarısız / İptal edildi / Geri alındı) ve başlama zamanı. Aktif durumdaki (bekliyor / planlandı / indiriliyor / sürüyor) güncellemeler satırdaki İptal düğmesiyle durdurulabilir; iptal, cihaza gönderilmiş kalıcı (retained) OTA komutunu da temizler.
4. Takılan Cihazlar — teşhis ve zorla temizleme
Takılan Cihazlar sekmesi, belirlenen süre boyunca ilerlemeyen OTA işlerini listeler — tıkanmış güncellemeleri tespit edip temizlemek için kullanılır.
- Eşik seçimi — "kaç saattir ilerlemeyen" (24 / 48 / 72 / 168 saat). Seçime göre liste ve "X saattir ilerlemeyen N cihaz bulundu" özeti güncellenir.
- Tablo — cihaz (MAC + gateway adı), aşama (durum + OTA aşaması), ilerleme çubuğu ve takılı süre (saat). Hiç takılan cihaz yoksa "Takılan cihaz yok — tüm OTA'lar sağlıklı" durumu gösterilir.
Zorla temizle (force-clear)
Her satırdaki Temizle düğmesi bir onay penceresi açar. Onaylandığında cihaz için:
- bekleyen/çalışan tüm OTA işleri iptal edilir,
- cihaza gönderilmiş kalıcı (retained) MQTT OTA komutu temizlenir,
- gateway'in OTA kilidi (in-progress bayrağı) sıfırlanır.
Böylece cihaz OTA döngüsünden çıkar. Bu, kalıcı (retained) mesaj yüzünden aynı OTA'ya sürekli takılan bir cihazı kurtarmanın en hızlı yoludur. İşlem sonunda kaç işin iptal edildiği bildirilir. Ayrıntılı teşhis (broker/MinIO/checksum/ESP32 logları) için OTA Güncelleme Takıldı runbook'una bakın.
Denetim izi
Bu modüldeki her yazma işlemi — firmware yükleme / yayınlama / kullanımdan kaldırma ve OTA başlatma / iptal / rollback / zorla temizleme — başarılı olduktan sonra Denetim · Güvenlik kaydına yazılır. Kimin, hangi firmanın gateway'inde, hangi sürüme geçtiğini oradan geriye dönük izleyebilirsiniz.
Sık karşılaşılan durumlar
"403 / yetkiniz yok" alıyorum. Firmware · OTA modülünün tamamı yalnız süper
yöneticiye açıktır. Süper yönetici olmayan bir hesap bu ekranı zaten görmez; bir
istek yine de gönderilirse sistem SUPERUSER_REQUIRED (403) döner. Eski firma
düzeyi firmware/OTA izinleri (read:firmware, initiate:ota, batch:ota vb.) artık
hiçbir işlevi tetiklemez (bkz. RBAC İzin Matrisi).
"GATEWAY_NOT_CLAIMED" hatası ne demek? Hedef gateway henüz bir firmaya sahiplenilmemiştir (owner yok). Sahibi olmayan bir gateway için firma-izolasyonlu MQTT komutu kurulamaz, bu yüzden OTA/rollback başlatılmaz ve net bir 400 döner. Çözüm: önce gateway'in ilgili firma tarafından sahiplenilmesini (claim) sağlayın; filo seçici sahiplenilmemiş gateway'leri zaten seçilemez gösterir.
Bir OTA "Sürüyor"da takılı kaldı. Takılan Cihazlar sekmesinden eşiği ayarlayıp cihazı bulun ve Temizle (force-clear) ile OTA döngüsünü kırın; ardından gerekirse Tekil OTA'dan yeniden gönderin. Derin teşhis için OTA Güncelleme Takıldı runbook'unu izleyin.
Ne zaman kullanılır?
- Yeni bir firmware sürümü yükleyip yayınlamak ve saha filosuna dağıtmak.
- Belirli firmaların (ya da tüm platformun) gateway'lerine toplu OTA planlamak, parti boyutu ve bekleme ile bant genişliğini yönetmek.
- Tek bir gateway'de sorun sonrası rollback yapmak veya kontrollü tek güncelleme göndermek.
- Bir sürümü sahadan çekmek için kullanımdan kaldırmak (yeni güncellemelerde seçilemez yapmak).
- Takılan OTA'ları tespit edip zorla temizleyerek cihazları döngüden kurtarmak.