Widget yazın.
Canlı veri gönderin.
Çerçeveye düşsün.
Tomi Frame Geliştirici API'si ile kendi widget'larınızı yazabilir, webhook veya HTTP üzerinden anlık veri gönderebilir ve çerçevenizi programatik olarak yönetebilirsiniz. Açık SDK — herkes geliştirip yayınlayabilir.
Nasıl çalışır
Veriniz → saniyeler içinde çerçevede
Bir webhook endpoint'i yayına alın
JSON nesnesi döndüren herhangi bir URL barındırın. Tomi Frame her yenileme döngüsünde bu adresi çağırır ve dönen değeri e-ink ekrana çizer.
Widget'ınızı tanımlayın
Uygulamada bir webhook widget'ı ekleyin, URL'nizi yapıştırın, bir etiket ve grid boyutu seçin. SDK kurmanıza gerek yok — tek gereken bir HTTP endpoint'i.
Ya da doğrudan gönderin
Geliştirici katmanında, bir endpoint barındırmak yerine değerleri doğrudan eklenti widget'ına POST edebilirsiniz. Gönderdiğiniz değer bir sonraki uyanma döngüsü için bekletilir — bu süre 60 saniyeye kadar inebilir.
Webhook biçimi
Endpoint'iniz JSON döndürür. Hepsi bu.
Tomi Frame URL'nizi belirli aralıklarla çağırır ve gelen yanıtı çizer. SDK yok, bağımlılık yok — istediğiniz dil, istediğiniz sunucu.
Yanıt şeması
{
"value": "22°C", // primary display value (required)
"label": "Kitchen", // footer label (optional, overrides config)
"secondary": "Humid 62%" // supporting text (optional)
}value alanı büyük punto ile çizilir. Kısa tutun — dar boyutlarda en fazla 6–8 karakter.
Örnek — Python (Flask)
from flask import Flask, jsonify
import requests
app = Flask(__name__)
@app.route("/widget/weather")
def weather():
data = requests.get(
"https://wttr.in/?format=j1"
).json()
temp = data["current_condition"][0]["temp_C"]
return jsonify({
"value": f"{temp}°C",
"label": "Live Temp",
"secondary": "via wttr.in"
})Örnek — Node.js
export async function GET() {
const res = await fetch(
"https://api.coincap.io/v2/assets/bitcoin"
);
const { data } = await res.json();
const price = Number(data.priceUsd).toFixed(0);
const change = Number(data.changePercent24Hr).toFixed(2);
return Response.json({
value: `$${Number(price).toLocaleString()}`,
label: "Bitcoin",
secondary: `${change > 0 ? "↑" : "↓"} ${Math.abs(change)}%`
});
}curl ile deneyin
# Add a webhook widget via API
curl -X POST https://api.tomiframe.com/user/widgets \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{
"type": "webhook",
"col": 0, "row": 0,
"col_span": 2, "row_span": 2,
"config": {
"url": "https://your-server.com/widget",
"label": "My Widget"
}
}'Doğrudan push (yalnızca Geliştirici)
Endpoint barındırmak yerine değeri siz gönderin
Push, kurulu bir eklenti widget'ına doğrudan yazar; böylece herkese açık bir URL yayınlamanız gerekmez. Çerçeve ömrünün büyük bölümünü telsizi kapalı şekilde uykuda geçirir, yani ona dışarıdan habersiz ulaşmak mümkün değildir — gönderdiğiniz değer yerinde bekler ve bir sonraki uyanmada çizilir. Geliştirici katmanında bu süre 60 saniyedir.
ttl_sec alanı, gönderdiğiniz değerin çerçeve eklentinin endpoint'ini çağırmaya dönmeden önce ne kadar süre geçerli kalacağını belirtir. TTL'den daha sık gönderin ya da TTL'i gönderim aralığınızdan uzun tutun.
# Push values into an installed plugin widget
curl -X POST https://api.tomiframe.com/plugins/YOUR_PLUGIN_ID/push \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"primary": "42",
"secondary": ["passing"],
"ttl_sec": 300
}'
# Response
{ "plugin_id": "ci-builds", "primary": "42",
"secondary": ["passing"], "expires_in_sec": 300 }API Referansı
Endpoint'ler
Base URL: https://api.tomiframe.com · Tüm endpoint'ler şunu gerektirir: Authorization: Bearer <token>
Cihaz
/device/{id}/frameGüncel kareyi sorgular — checksum, BMP verisi, sonraki yenileme aralığı ve sıradaki alarmı döndürür
/device/{id}/configYenileme aralığını ayarlar, firmware sürümünü günceller
Eklentiler
/pluginsMağazayı ve kendi özel eklentilerinizi listeler; her birinde kurulu olup olmadığı bilgisiyle
/plugins/{id}/installEklentiyi sığdığı ilk boş alana yerleştirir — yapılandırma değerlerini burada gönderin
/plugins/{id}/installEklentiyi kaldırır ve kapladığı hücreleri serbest bırakır
/plugins/{id}/pushKurulu bir eklenti widget'ına değer gönderir (yalnızca Geliştirici)
/plugins/privateYalnızca kendi hesabınızda görünen bir manifest tanımlar (yalnızca Geliştirici)
/plugins/private/{id}Özel eklentinin kaydını siler ve widget'larını kaldırır
Widget'lar
/user/widgetsTüm widget'ları türü, konumu ve yapılandırmasıyla listeler
/user/widgetsWidget oluşturur — tür, grid konumu, col_span, row_span ve yapılandırma
/layoutTüm düzeni (widget dizisi) tek çağrıda kaydeder
Ekran
/user/display-modeGeçerli modu döndürür: dashboard / minimal_clock / art / photo
/user/display-modeMod değiştirir, zamanlama tanımlar (örn. 22:00–07:00 arası sanat modu)
/user/frame-previewGüncel kareyi web önizlemesi için PNG olarak çizip döndürür
Alarmlar
/user/alarmsAlarmları saati, gün maskesi ve açık/kapalı durumuyla listeler
/user/alarmsAlarm oluşturur — etiket, time_hhmm (24 saat), days (Pzt–Paz bit maskesi)
/user/alarms/{id}Alarm ayarlarını günceller
/user/alarms/{id}Alarmı siler
Kimlik doğrulama
Kullanıcı endpoint'leri /auth/login adresinden alınan bir JWT bearer token kullanır. Cihaz endpoint'leri ise kayıt sırasında dönen bearer token'ı kullanır. Geliştirici API anahtarları ikisine birden erişim verir.
# Get a user JWT
curl -X POST https://api.tomiframe.com/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "••••••"}'
# { "access_token": "eyJ...", "refresh_token": "eyJ..." }Grid sistemi
6 × 4 grid, 800 × 480 piksel
Tuval 6 sütun × 4 satırdır. Her hücre 122 × 107 piksel; aralarda 8 piksel boşluk, kenarlarda 14 piksel pay vardır. Widget'lar 1–6 sütun ve 1–4 satır kaplayabilir. Standart referans boyut 3 × 2 hücredir (382 × 222 piksel).
| Widget türü | Gereken yetki | Yenileme | Yapılandırma alanları |
|---|---|---|---|
clock | Yok | Her karede | timezone |
weather | Yok (OWM anahtarı) | 5 dk | city |
rss | Yok | 15 dk | feed_url |
price | Yok | 5 dk | symbol, asset_type |
countdown | Yok | Her karede | event_name, date |
text | Yok | Sabit | text, font_size |
webhook | Yok (kendi URL'niz) | 5 dk (Geliştirici ile 1 dk) | url, label, json_path |
spotify | Spotify OAuth | 30 sn | — |
calendar | Google OAuth | 1 dk | — |
github | GitHub OAuth | 5 dk | — |
slack | Slack OAuth | 5 dk | — |
home_assistant | HA token'ı | 1 dk | url, token, entity_ids |
Geliştirmeye hazır mısınız?
Tek seferlik erişim. Yinelenen ücret yok. Sonsuza dek tam API erişimi.