Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Cihazlara komut gönderme

Define a command catalog with tiers, send commands, follow their states and expiry, answer them on the device, and receive device requests.

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:

AlanAnlamı
YöntemKablo üzerindeki ad, namespace.verb biçiminde, örneğin sys.info. Harfler, rakamlar, _ ve ..
Etiket, AçıklamaOperatörlerin gördükleri.
KademeBasic, 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.
ParametrelerFields (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ş parametrelerDeğ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

SeviyeKimin gönderebileceği (varsayılan)
TemelKullanıcılar
AyrıcalıklıYöneticiler
KritikYö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

  1. Cihazı ve Commands sekmesini açın.
  2. Choose a command altında bir komut seçin (ya da yalnızca sahipler için Other method (raw)) ve Parameters alanlarını doldurun.
  3. Gerekirse seçenekleri ayarlayın:
SeçenekAnlamı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
  1. 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ı

DurumGösterilenAnlamı
QUEUEDKuyruktaSaklandı, cihaz bekleniyor.
SENTGönderildiCihaza gönderildi.
DELIVEREDTeslim edildiCihaz aldı.
SUCCESSFULBaşarılıCihaz başarıyla yanıt verdi.
FAILEDBaşarısızCihaz bir hatayla yanıt verdi.
TIMEOUTZaman aşımına uğradıZamanında yanıt yok. Bu, “yanıt gelmedi” anlamına gelir, “çalışmadı” anlamına gelmez.
EXPIREDSüresi dolduGönderilemeden süresi doldu.
CANCELLEDİptal edildiBiri 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 expirationTime iç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.downlink komutuyla 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.