Bir komut (RPC olarak da anılır), cihazdan bir şey yapmasını ister: yeniden başlatma, bir çıkışı değiştirme, bir test çalıştırma. Her komut bir istek olarak saklanır ve cihaz yanıt verene kadar takip edebilirsiniz. Komutlar yalnızca TLS oturumları üzerinden gönderilir (profil bir komuta düz metinle izin vermediği sürece), telemetriyi işleyen akışlardan asla geçmez ve her biri gönderenin yetkilerine karşı denetlenir.
Komut kataloğu
Her cihaz profilinin bir Commands sekmesi vardır: “Bu profildeki cihazlara operatörlerin gönderebileceği komutlar; her seviye kendi iznini gerektirir.” Bunu düzenlemek, komutları yönetme iznini (yöneticiler) gerektirir.
Add command seçeneğini seçin ve şunları doldurun:
| Alan | Anlamı |
|---|---|
| Yöntem | Kablo üzerindeki ad, namespace.verb biçiminde, örneğin sys.info. Harfler, rakamlar, _ ve .. |
| Etiket, Açıklama | Operatörlerin gördükleri. |
| Kademe | Basic, Privileged veya Critical: kimin gönderebileceği (aşağıya bakın). |
| Yüksek etki (onay ister) | Gönderen onaylamalıdır; komut en fazla bir kez gönderilir ve denetlenir. |
| Yazılı onay ifadesi | İsteğe bağlı, yalnızca yüksek etkili komutlar için: göndermek için operatör bunu yazar (örneğin REBOOT). |
| Tek yönlü (yanıt yok) | Cihaz yanıt vermez. |
| Uzun süren (yanıt yalnızca başladığını bildirir) | Cihaz hemen yanıt verir ve sonucu daha sonra bildirir. |
| Varsayılan zaman aşımı (ms) | 1.000 ila 600.000. Boşsa: profilin Default RPC timeout değeri. |
| Varsayılan olarak kalıcı (cihaz geri geldiğinde iletilir) | Cihaz çevrimdışıyken komutu kuyruğa alır. |
| Parametreler | Fields (ad, etiket, tür Text, Number, Yes / no, Choice veya Any value (JSON), zorunlu, min, max, choices) ile ya da Advanced (JSON) olarak oluşturulur. En fazla 50 parametre. |
| Maskelenmiş parametreler | Değerleri geçmişte hiçbir zaman görünmeyen parametre adları. |
From a template, platformun zaten gönderdiği bir komuttan (örneğin bir kart kontrolü gibi) formu başlatır. Import, tüm kataloğu bir dışa aktarmayla ({"commands": [ … ]}) değiştirir; Export, kataloğu JSON olarak gösterir. Bir profil en fazla 200 komut içerebilir.
Seviyeler
| Seviye | Kimin gönderebileceği (varsayılan) |
|---|---|
| Temel | Kullanıcılar |
| Ayrıcalıklı | Yöneticiler |
| Kritik | Yöneticiler |
| Ham (katalogda olmayan bir yöntem) | Sahipler |
Not
Bazı komutlar kim isterse istesin asla gönderilmez: fabrika ayarlarına dönüş, eşleştirme, Wi-Fi unutma ve cloud.forget. Bazı yöntem aileleri bir modüle aittir ve yalnızca o modül gönderir (örneğin uzak erişim için tunnel.* ve esim.*). Yalnızca Legacy compatible konu şemasını kullanan profillerde komut bulunmaz: “RPC, Legacy compatible şemasındaki cihazlar için kullanılamaz; ayarları göndermek için paylaşılan öznitelikleri (Attributes sekmesi) kullanın.”
Komut gönderme
- Cihazı ve Commands sekmesini açın.
- Choose a command altında bir komut seçin (ya da yalnızca sahipler için Other method (raw)) ve Parameters alanlarını doldurun.
- Gerekirse seçenekleri ayarlayın:
| Seçenek | Anlamı | Varsayılan |
|---|---|---|
| Yanıt beklenmesin (tek yönlü) | Cihaz yanıt vermez. | Kapalı (iki yönlü) |
| Yanıt zaman aşımı (saniye) | Yanıt için ne kadar bekleneceği, 1 ila 600 saniye. | Komutun varsayılanı, yoksa 10 saniye |
| Cihaz geri geldiğinde teslim et (kalıcı) | Cihaz çevrimdışıyken komutu kuyrukta tutar. | Komutun varsayılanı |
| Şu süreden sonra vazgeç (dakika) | Kuyruğa alınmış bir komutun vazgeçileceği süre. | 24 saat; en fazla 7 gün |
- Send seçeneğini seçin. Yüksek etkili bir komut Send sys.reboot? sorusunu sorar (“Bu komutun cihaz üzerinde etkisi vardır (yeniden başlatabilir veya oturumunu kaybedebilir).”) ve bir ifadesi varsa Type REBOOT to confirm istenir.
Cihaz çevrimdışıysa sekme uyarır: “Cihaz çevrimdışı: “persistent” seçeneği olmadan komut hemen başarısız olur.”
Gösterge panelleri, SCADA sembolleri, kurallar ve akışlar da komut gönderebilir. Bir kart kontrolü yalnızca basic seviyesindeki komutları gönderir. Bkz. Control cards.
Komut durumları
| Durum | Gösterilen | Anlamı |
|---|---|---|
QUEUED | Kuyrukta | Saklandı, cihaz bekleniyor. |
SENT | Gönderildi | Cihaza gönderildi. |
DELIVERED | Teslim edildi | Cihaz aldı. |
SUCCESSFUL | Başarılı | Cihaz başarıyla yanıt verdi. |
FAILED | Başarısız | Cihaz bir hatayla yanıt verdi. |
TIMEOUT | Zaman aşımına uğradı | Zamanında yanıt yok. Bu, “yanıt gelmedi” anlamına gelir, “çalışmadı” anlamına gelmez. |
EXPIRED | Süresi doldu | Gönderilemeden süresi doldu. |
CANCELLED | İptal edildi | Biri iptal etti. |
Uzun süren bir komut, sonucu gelene kadar Running on the device gösterir; zaman aşımına uğrayan bir komut No answer: the outcome is unknown gösterir; süre dolduktan sonra gelen bir yanıt Answered after the end gösterir.
Geçmiş
Commands sekmesindeki History, Method, Status, Sent by (Console, API, A flow, Firmware update, An alarm action, A dashboard control), Created, Completed ve Duration alanlarını listeler. Bir komutu açarak Request, Response ve Progress alanlarını görebilir, kuyruğa alınmış veya gönderilmiş iken Cancel command seçeneğini kullanabilir ya da Send again seçeneğiyle yeniden gönderebilirsiniz. Gizli parametreler maskelenir.
Varsayılan sınırlar: cihaz başına dakikada 10 komut ve kuruluş başına dakikada 600 komut; parametreler en fazla 16 KiB JSON; yanıt en fazla 64 KiB. Geçmiş 90 gün saklanır.
Cihazda
Cihaz v1/rpc/req/+ konusuna abone olur ve şunları alır:
PUBLISH v1/rpc/req/42
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}
İki yönlü bir komut için aynı kimlik üzerinden yanıt verir:
PUBLISH v1/rpc/res/42
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}
Cihaz için kurallar:
- Bir komut iki kez gelebilir. En az son 32 istek kimliğini 10 dakika boyunca hatırlayın ve aynı kimliği asla iki kez çalıştırmayın.
- İstek
expirationTimeiçeriyorsa ve süresi geçmişse, çalıştırmayın;{"ok": false, "error": "expired"}ile yanıt verin. - İstek cihazın kaldırabileceğinden büyükse, çalıştırmayın;
{"ok": false, "error": "payload_too_large"}ile yanıt verin. - Komutlar yalnızca cihaz bu bağlantıda
v1/rpc/req/+konusuna abone olduktan sonra iletilir.
HTTP cihazları komutları GET /api/v1/rpc ile bekler ve POST /api/v1/rpc/{id} ile yanıt verir. Bkz. Device HTTP API.
Uzun süren komutlar
PUBLISH v1/rpc/res/43
{"ok": true, "accepted": true, "job_id": "43"}
PUBLISH v1/attributes
{"rpc_result": {"job_id": "43", "method": "sys.traceroute", "ok": true, "result": {...}, "ts": 1759572042000}}
Cihazdan gelen istekler
Bir cihaz buluttan da istekte bulunabilir: {"method": …, "params": …} ile v1/rpc/up/req/{id} konusuna yayımlayın ve yanıtı v1/rpc/up/res/{id} konusundan okuyun. Akışlarınız bu istekleri alır ve yanıtlar.
LoRaWAN
- LoRaWAN cihazları
lora.downlinkkomutuyla ham downlink alır. Bkz. Sending downlinks.
API ile
POST/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc
Bir cihaza komut gönderin. Gövde alanları: method (zorunlu), params, oneway, persistent, timeoutMs (1.000 ile 600.000 arası), expiresInS (1 ile 604.800 arası), wait, confirm, confirmText, source (console, api veya dashboard_control). params en fazla 16 KiB JSON olabilir. Çift yönlü, kalıcı olmayan ve zaman aşımı en fazla 30 saniye olan bir çağrı sonlanana kadar bekler ve 200 yanıtı verir. Diğer tüm çağrılar hemen 202 yanıtı verir. Yüksek etkili bir komut için "confirm": true gerekir.
İstek gövdesi application/json
{
"method": "sys.ping",
"params": {
"host": "8.8.8.8",
"count": 3
},
"timeoutMs": 10000
}
Örnek curl
curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
-H 'Content-Type: application/json' \
-d '{"method":"sys.ping","params":{"host":"8.8.8.8","count":3},"timeoutMs":10000}'
Yanıtlar
200OK
{
"rpc": {
"rpcId": "…",
"deviceId": "…",
"method": "sys.ping",
"status": "SUCCESSFUL",
"outcome": null,
"response": {
"ok": true,
"result": {
"sent": 3,
"received": 3,
"avg_ms": 18.2
}
},
"tier": "basic",
"highImpact": false,
"source": "api",
"…": "…"
}
}
202Kabul edildi
{
"rpc": {
"rpcId": "…",
"deviceId": "…",
"method": "sys.reboot",
"status": "QUEUED",
"…": "…"
}
}
400Hatalı İstek
{
"message": "This command needs confirm: true.",
"code": "VALIDATION_ERROR",
"details": {
"reason": "confirm_required"
}
}
403Erişim Engellendi
Yanıt gövdesi yok.
404Bulunamadı
{
"message": "Device not found.",
"code": "NOT_FOUND"
}
429Çok Fazla İstek
Yanıt gövdesi yok.
GET /tenant/{tenantId}/api/iot/rpc/{rpcId} ile bir komutu okuyun ve POST …/rpc/{rpcId}/cancel ile iptal edin (yalnızca QUEUED veya SENT durumundayken; denetlenir). outcome alanı, yukarıda açıklandığı gibi running, unknown veya late değerlerini okur. Bkz. Commands API.
Webhook olayları rpc.completed ve rpc.failed sonucu diğer sistemlere bildirir. Yüksek etkili ve ham komutlar oluşturulduklarında ve sonlandıklarında denetim günlüğüne yazılır.

