Firmware ve cihaz ayarları API’si

Bu sayfa iki rota ailesini kapsar: firmware güncellemeleri (OTA) ve uzaktan cihaz ayarları. İkisinin kullanıcılar için nasıl çalıştığı Firmware güncellemeleri (OTA), Firmware yayın dalgaları ve Uzaktan cihaz ayarları bölümlerinde anlatılır. Yollar https://<your host>/tenant/<tenantId> altındadır.

Firmware rotaları

İmzalama anahtarı ekleme ve iptal etme bir Owner yetkisidir, bu yüzden bir API anahtarı bunu yapamaz.

Paket yükle

POST /api/iot/ota/packages iki bölümlü multipart/form-data alır: file (imaj) ve meta (JSON metni). Sağlama toplamı hiçbir şey saklanmadan önce denetlenir ve imza kayıtlı anahtarlarınıza karşı doğrulanır.

curl -s -X POST "https://$HOST/tenant/$TENANT/api/iot/ota/packages" \
  -H "Authorization: Bearer $HERMETRY_KEY" \
  -F "file=@router-fw-2.5.0.bin" \
  -F 'meta={"title":"router-fw","version":"2.5.0","checksum":"<sha256 of the file>","signatureScheme":"usign-ed25519","signature":"<text of the .sig file>","profileId":"a1b2…","releaseNotes":"Fixes LTE reconnect."}'

Varsayılan en büyük boyut 64 MiB’tir. Yanıt 201 { "package": {...} }.

Ata ve yayınla

{
    "packageId": "f00d…",
    "targetType": "PROFILE",
    "targetId": "a1b2…",
    "waves": [
        {
            "size": {
                "percent": 5
            },
            "soakMin": 60,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 1440
        },
        {
            "size": {
                "percent": 100
            },
            "soakMin": 0,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 2880
        }
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/ota/assignments' \
  -H 'Content-Type: application/json' \
  -d '{"packageId":"f00d…","targetType":"PROFILE","targetId":"a1b2…","waves":[{"size":{"percent":5},"soakMin":60,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":1440},{"size":{"percent":100},"soakMin":0,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":2880}]}'

{
    "assignment": {
        "…": "…"
    },
    "preview": {
        "…": "…"
    },
    "result": {
        "…": "…"
    }
}

{
    "assignment": null,
    "preview": {
        "…": "…"
    }
}

{
    "message": "Only a ready package can be assigned.",
    "code": "CONFLICT"
}

Bir dalganın size değeri { "percent": 0–100 } veya { "count": 1–100000 }; son dalga kalanı alır. soakMin 0 ila 10.080, minSuccessPct ve maxFailurePct 0 ila 100, isteğe bağlı maxFailures, maxDurationMin 5 ila 43.200.

Yayın durumları: RUNNING, PAUSED, COMPLETED, ABORTED. Başarısız bir kapı yayını duraklatır; resume devam ettirir, abort sonlandırır.

Güncelleme durumları

Bir cihazın güncellemesi QUEUED, INITIATED, WAITING, DOWNLOADING, DOWNLOADED, VERIFIED, UPDATING durumlarından geçer ve UPDATED, FAILED, TIMEOUT, ROLLED_BACK, SKIPPED veya CANCELLED ile biter. Yalnızca FAILED, TIMEOUT ve ROLLED_BACK yeniden denenebilir ({ "action": "retry" }), deneme sınırına kadar.

OTA ayarları

PUT /api/iot/ota/settings/profile/{profileId} şunları alır: otaEnabled, allowMetered, allowUnsigned, downloadTimeoutMin (5 ila 1.440), updateTimeoutMin (2 ila 240), maxAttempts (1 ila 10); null varsayılana döndürür. Bir cihaz için (/settings/device/{deviceId}) yalnızca allowMetered alınır: “Bir cihaz yalnızca ölçülü bağlantı ayarını alır.”

Webhook olayları: ota.update.* ve ota.rollout.*, bkz. Webhook olay başvurusu.

Cihaz ayarları rotaları

Uzaktan ayarlar, modeli bir ayar manifestosu yayınlayan lisanslı cihazlar içindir.

Bir yazma neyi değiştirebilir, değişen her ayarın sınıfına bağlıdır: çalışma ayarları iot_device_settings.operate gerektirir, yapılandırma ayarları iot_device_settings.write, tehlikeli ayarlar iot_device_settings.dangerous.write (yalnızca Owner, yani asla bir API anahtarı değil) ve "confirm": true.

Bir bölümü değiştir

GET  /api/iot/devices/{deviceId}/settings/network        → ETag: "7"
PATCH /api/iot/devices/{deviceId}/settings/network
If-Match: "7"
{ "patch": { "lte": { "apn": "iot.example" } } }

• If-Match gereklidir: olmadan 428 “If-Match gerekli: okuduğunuz rev’i gönderin.”
• Bölüm okuduğunuzdan beri değiştiyse: 412 “Bölüm okunduğundan beri değişti; yeniden okuyun.” (rev_mismatch).
• ?dryRun=true doğrular ve neyin değişeceğini listeler, hiçbir şey saklamaz.
• Birleştirme yaması nesneleri birleştirir, null ile siler ve listeleri bütün olarak değiştirir.
• Yazmalar kuruluş başına dakikada 600 ile sınırlıdır.
• Gizli bilgiler asla döndürülmez: gizli bir ayar { "set": true } olarak okunur.

Bölümlere göre ayar almayan bir cihaz 409 “Bu cihaz bölümlere göre ayar almıyor.” yanıtını verir; manifestosu henüz kataloğda olmayan cihaz ise “Bu cihazın modeli ve firmware’inin ayar manifestosu henüz kataloğda değil.”

Toplu işler

Idempotency-Key başlığıyla POST /api/iot/device-settings/jobs: name (en fazla 80), baselineId veya sections, selector (deviceIds, profileId veya models), isteğe bağlı waves ({ "percent": [1, 10, 100] } veya { "count": [...] }, en fazla 10), gates (minApplied, maxReverted 0 ila 1 arasında oranlar olarak), onConflict (queue veya skip), offlineExpiryDays (1 ila 90), waveTimeoutMin (1 ila 1.440), confirm. Tekrarlanan bir Idempotency-Key ilk işi yanıtlar (200). ?dryRun=true planı yanıtlar. Redler: 409 too_many_jobs; 422 confirm_required, invalid_sections, no_devices, too_many_devices; 403 class_forbidden.