Referenční dokumentace HBUS API pro HELLOS-UNI

Tato dokumentace se vztahuje k verzi protokolu HBUS 01 a verzi firmwaru HELLOS-UNI 4.0. Popis chování portů se vztahuje k verzi hardwaru HELLOS-UNI 2.1.

Tento dokument popisuje přenosový protokol a aplikační data implementovaná ve firmwaru HELLOS-UNI. Ukázky JSON pod označením Data požadavku a Data odpovědi obsahují pouze hodnotu pole HBUS p.

Autor a cíle návrhu

Autorem HBUS je HELLOS smart tech s.r.o. Protokol má otevřenou specifikaci, která umožňuje vývojářům implementovat jej ve vlastních projektech.

Protokol byl navržen pro:

• Master-master (multi-master) komunikaci na RS-485, aby zařízení mohla odesílat okamžité události bez čekání na dotaz řídicí jednotky.
• Zjednodušení implementace a integrace do vlastních projektů díky čitelnému textovému formátu. Pakety lze kontrolovat pouhým okem, bez speciálního dekodéru binárního protokolu.
• Nahrazení téměř 50 let starého protokolu Modbus RTU v aplikacích, pro které je jeho model master/slave s periodickým dotazováním nevhodný, zejména při komunikaci řízené událostmi.

HBUS používá rámce JSON založené na ASCII pro soužití se slave zařízeními Modbus RTU na RS-485. Bajty funkcí běžného čtení a zápisu Modbus, například 0x01-0x06, 0x0f a 0x10, jsou řídicí znaky a v kompaktních JSON paketech HBUS se jako nezakódované bajty nevyskytují.

Software a samostatný provoz

K HBUS je k dispozici:

• hbusd, server a MQTT gateway distribuovaný jako Debian balík.
• Desktopová aplikace pro Linux a Windows.
• Mobilní aplikace, zatím pouze pro Android.

Čidla s HBUS mohou fungovat také samostatně, bez hbusd, MQTT brokeru nebo kterékoli z těchto aplikací. Jejich čitelný JSON výstup lze přijímat a prohlížet přes libovolný RS-485 převodník s odpovídajícím nastavením sériové komunikace. To usnadňuje integraci do vlastních projektů. Vlastní řídicí jednotka může pomocí níže popsaného protokolu posílat požadavky a potvrzovat pakety, které vyžadují spolehlivé doručení.

HELLOS-UNI lze také nastavit tak, aby svůj úplný stav posílal automaticky v pravidelných intervalech, bez dotazování a potvrzování. Po nastavení tedy pro příjem těchto hlášení není potřeba programovat vlastní logiku požadavků ani ACK. Čitelný textový výstup lze přímo sledovat v sériovém terminálu nebo zpracovávat běžnými textovými nástroji a jednoduchými skripty. Viz Nastavení intervalu automatického odesílání stavu.

Přenos

HBUS přenáší kompaktní JSON po poloduplexní lince RS-485 s nastavením 8N1. Výchozí rychlost 19200 Bd je naprosto dostačující pro běžné pollované čtení vstupů a čidel. Pro aplikace využívající okamžité události je doporučeno 115200 Bd a více, aby se zkrátila doba přenosu paketů a latence událostí. Úplný paket má následující strukturu:

{"H":"01","l":"0073","c":"84449af2","d":"00000000","s":"cf38542d","r":1,"p":{"button_press":{"A":{"1":[1082810]}}}}

CRC se počítá z celého JSON paketu po nahrazení osmi znaků v poli c osmi podtržítky:

"c":"________"

Implementace musí vypočítat l před výpočtem CRC. Paket nemá ukončovací znak řádku. Přijímač hledá v proudu bajtů hlavičku {"H":"01" a podle l určí hranici paketu. Nesouvisející bajty před paketem tedy ignoruje.

Časové limity příjmu, získání přístupu ke sběrnici a ACK závislé na délce přenosu se počítají z rychlosti použité při inicializaci UART. Spolehlivý přenos proto používá stejný stavový automat od 1200 do 460800 Bd. ACK přijaté během čekání před opakováním přenosu stále dokončí původní doručení a zabrání zbytečnému odeslání duplicitního paketu.

Adresy

Výchozí adresa modulu odpovídá posledním čtyřem bajtům unikátního ID RP2040, zapsaným jako osm hexadecimálních znaků s malými písmeny. Adresy 00000000 a ffffffff nelze modulu přiřadit.

ACK

Platný adresovaný paket s r:1 je potvrzen ještě před zpracováním aplikačního příkazu:

{"a":"84449af2"}

ACK obsahuje CRC přijatého paketu. Potvrzuje pouze správné doručení na transportní úrovni, nikoli úspěšné provedení požadované operace. Úspěch nebo neúspěch příkazu je nutné určit ze samostatného paketu odpovědi. Broadcast pakety se nepotvrzují.

Pakety tlačítek, enkodéru a měření odesílané modulem používají spolehlivé doručení. Nepotvrzený paket modul opakuje až osmkrát s postupně rostoucí náhodnou prodlevou mezi pokusy.

Použití API přes hbusd

Při výchozím pojmenování MQTT témat v hbusd odešlete celá aplikační data jako JSON do:

hbusd/<device-address>/send

Příklad:

mosquitto_pub -t hbusd/cf38542d/send -m '{"g":"a"}'

Přijaté koncové hodnoty se publikují pod:

hbusd/<device-address>/read/<payload-path>

Například odpověď na identifikaci vytvoří read/hw, read/sw a read/sw_source. Pole rozkládá hbusd na samostatné MQTT zprávy ve stejném koncovém tématu, přičemž zachovává pořadí událostí pro příjemce, například Node-RED. MQTT prefix a části send/read lze v hbusd nastavit.

Identifikace

Identifikaci lze vyžádat od všech modulů broadcastem nebo od jednoho modulu adresovaným požadavkem (unicast).

Cílová adresa požadavku: ffffffff

Data požadavku:

{"identify":true}

Modul naplánuje odpověď po náhodné prodlevě od nuly do deseti sekund, aby omezil kolize více odpovídajících zařízení. Odpočet je neblokující, takže zpracování aplikace a HBUS mezitím normálně pokračuje.

Pro okamžitou unicast odpověď odešlete na adresu modulu:

{"device":"identify"}

Data odpovědi:

{
  "hw": "UNI-2.1.0",
  "sw": "3.2-2026-09-06-1780922bd",
  "sw_source": "frozen",
  "alias": "Kitchen switches"
}

Odpověď se odesílá na adresu centrální řídicí jednotky 00000000. Modul odesílá tato data také automaticky po nastaveném intervalu nečinnosti. Režim debug je odešle jednou ihned po spuštění.

Čtení všech měření

Data požadavku:

{"g":"a"}

Odpověď obsahuje poslední naměřené hodnoty po aplikaci kompenzací. Měření standardně probíhá každých deset sekund.

Příklad dat odpovědi:

{
  "u": 234,
  "ds": {
    "100000a3": {"tmp": 24.1}
  },
  "sht3x": {
    "0": {"tmp": 23.8, "hum": 47.2}
  },
  "scd4x": {
    "0": {"co2": 612, "tmp": 24.0, "hum": 46.9}
  },
  "input": {
    "A": {"0": true, "1": false, "2": false, "3": false}
  },
  "impulse_counter": {
    "B": {"0": 12345, "1": 81, "2": 0, "3": 907}
  },
  "pwm": {
    "B": {"0": 50, "1": 0, "2": 75, "3": 100}
  },
  "output": {
    "C": {"0": 1, "1": 0, "2": 0, "3": 1}
  },
  "adc": {
    "A": {"0": 0.0, "1": 25.0, "2": 50.1, "3": 100.0}
  }
}

ID čidel DS18x20 tvoří posledních osm hexadecimálních znaků jejich ROM. ID čidel SHT3x a SCD4x jsou pořadové indexy od nuly přiřazené při spuštění.

Odpověď používá spolehlivé doručení a je adresována odesílateli požadavku.

Vstupní události

Vstupní události jsou nevyžádané pakety se spolehlivým doručením odesílané na 00000000.

Stisk tlačítka

{"button_press":{"A":{"1":[1082810]}}}

Uvolnění tlačítka

Události uvolnění se odesílají pouze pro port nastavený jako button_double.

{"button_release":{"A":{"1":[1083152]}}}

Pole umožňuje přenést v jednom paketu více událostí nashromážděných během jednoho průchodu hlavní smyčkou. Každá hodnota je časová značka time.ticks_ms(), nikoli kalendářní čas.

Stavový vstup

{"input":{"A":{"1":true}}}

Každá změna stavu po filtraci zákmitů vytvoří událost s aktuální logickou hodnotou. Pokud se pro stejný vstup před sestavením dalšího paketu nahromadí více změn, odešle se poslední stav. Modul také uchovává úplný stav všech portů nastavených jako input nebo input_safe a zahrnuje jej do každé odpovědi na {"g":"a"}.

Režim input čte přímo signálové GPIO a používá pull-up rezistor 10 kOhm na desce. Režim input_safe ponechá signálové GPIO jako vstup bez pull-upu a čte párové GPIO pro řízení pull-upu přes rezistor 10 kOhm s využitím interního pull-upu RP2040. Komunikace a filtrace zákmitů po dobu 30 ms jsou v obou režimech stejné.

Slabší interní pull-up činí input_safe citlivějším na svodové proudy a rušení na dlouhých kabelech. Sériový rezistor omezuje proud do vzorkovaného GPIO, ale nechrání proti vnějšímu přepětí; signálové GPIO zůstává fyzicky připojené k portu.

Čítač impulzů

Porty nastavené jako impulse_counter nebo impulse_counter_safe počítají platné impulzy aktivní v LOW od nuly po každém spuštění. Hodnoty se uchovávají pouze v RAM a nezapisují se do flash. Každý impulz LOW a předcházející úroveň HIGH musí trvat alespoň 1 ms. Platný impulz se započítá při náběžné hraně.

Změny čítačů nikdy nevytvářejí nevyžádané pakety. Absolutní počty jsou zahrnuty pouze do úplného stavu vraceného na {"g":"a"} a do volitelného automatického odesílání úplného stavu. Čítače lze vynulovat pouze restartem modulu nebo změnou konfigurace jeho portů.

Běžný režim čte signálové GPIO a používá pull-up rezistor 10 kOhm na desce. Bezpečný režim čte párové GPIO pro řízení pull-upu přes rezistor 10 kOhm a používá slabší interní pull-up RP2040. Pro rychlé impulzy a dlouhé nebo rušené vedení je vhodnější běžný režim.

ADC vstup

Port A lze nastavit jako čtyři ADC vstupy. Pasivní režimy publikují hodnoty pouze jako součást odpovědi na {"g":"a"}. Aktivní režimy navíc posílají nevyžádané pakety se spolehlivým doručením obsahující pouze vstupy, jejichž filtrovaná hodnota se dostatečně změnila:

{"adc":{"A":{"1":37.6}}}

Hodnoty ADC používají procentní rozsah od 0.0 do 100.0. Vzorky se filtrují v nativním 12bitovém rozlišení a před převodem na procenta se kvantují na 9 bitů. To poskytuje 512 různých vstupních úrovní; zobrazované desetinné místo tedy neznamená fyzické rozlišení 0,1 procenta.

ADC v RP2040 má přibližně 8,7 efektivního bitu a trpí dokumentovanou chybou diferenciální nelinearity RP2040-E11. Tyto vstupy jsou určeny například pro ovládání potenciometry, nikoli pro přesné měření napětí.

Hodnoty do 0,4 procenta se hlásí jako 0.0, hodnoty od 99,6 procenta jako 100.0. Aktivní hlášení používá pásmo necitlivosti 1,0 procenta a je omezeno na jeden paket za 200 ms. Změny nashromážděné během tohoto intervalu se sloučí a pro každý pin se uchová pouze poslední hodnota. Při neúspěšném doručení zůstávají poslední hodnoty připravené k odeslání a další pokus se odloží o jednu sekundu.

Režimy adc_raw_passive a adc_raw_active vypínají pull-up rezistory desky. Režimy adc_pullup_passive a adc_pullup_active je zapínají. Všechny ADC režimy jsou dostupné pouze na portu A.

PWM výstupy

PWM je dostupné pouze na portech B a C. Celý port se nastaví na jednu z pevných hardwarových frekvencí režimem pwm_50hz, pwm_1khz nebo pwm_25khz. Všechny piny jsou výstupy push-pull a po každém restartu začínají se střídou nula procent.

Jeden příkaz může změnit jeden nebo více pinů, a to i na obou nastavených portech:

{"pwm":{"B":{"0":50,"2":75}}}

Názvy portů a indexy pinů se ověřují před změnou kteréhokoli výstupu. Střídy musí být celá čísla od 0 do 100. Po provedení celého příkazu modul okamžitě vrátí úplný stav každého portu uvedeného v požadavku:

{"pwm":{"B":{"0":50,"1":0,"2":75,"3":0}}}

Aktuální stav všech nastavených PWM portů lze také vyžádat přímo:

{"pwm":"get"}

Stav PWM je součástí každé odpovědi na {"g":"a"}. Střídy jsou provozním stavem a nezapisují se do flash.

Digitální výstupy

Režimy output a output_safe poskytují čtyři logické výstupy na libovolném univerzálním portu. Každý pin po restartu začíná v logické nule. Jediný příkaz může změnit jeden nebo více pinů na jednom nebo více nastavených portech:

{"output":{"B":{"0":1,"2":0}}}

Názvy portů, indexy pinů a všechny hodnoty se ověřují před změnou kteréhokoli výstupu. Hodnoty musí být celá čísla 0 nebo 1. Odpověď obsahuje úplný stav každého portu uvedeného v požadavku:

{"output":{"B":{"0":1,"1":0,"2":0,"3":0}}}

Aktuální stav všech nastavených výstupních portů lze také vyžádat:

{"output":"get"}

Stav výstupů je součástí každé odpovědi na {"g":"a"} a neukládá se do flash.

V režimu output je signálové GPIO přímým výstupem push-pull. V režimu output_safe zůstává signálové GPIO vstupem a párové GPIO pro řízení pull-upu budí signál pouze přes rezistor 10 kOhm na desce. Oba režimy používají stejné příkazy a odpovědi HBUS.

Rezistor omezuje proud při konfliktu výstupů nebo zkratu. Nejde o ochranu proti přepětí, protože signálové GPIO zůstává fyzicky připojené k portu. Bezpečný režim je určen pro statické logické vstupy a hradla MOSFETů; nemůže přímo dodávat významný proud do zátěže. Vnější obvody musí zajistit bezpečný stav během spouštění nebo resetu modulu.

Rotační enkodér

{"encoder_delta":{"B":{"2":-1}}}

Kanál enkodéru se hlásí na indexu 2. Více pohybů nashromážděných během jednoho intervalu se sečte, takže rozdíl může být menší než -1 nebo větší než 1. Stisk tlačítka enkodéru se hlásí jako button_press na indexu 3.

Ovládání zařízení

Čtení nastavení zařízení

Data požadavku:

{"device":"get_settings"}

Data odpovědi:

{
  "device_settings": {
    "address": "cf38542d",
    "alias": "Kitchen switches",
    "hbus_baudrate": 19200,
    "identify_interval": 5,
    "state_interval": "DISABLED",
    "bus_mode": "hbus",
    "active_bus_mode": "hbus",
    "modbus_address": 17
  }
}

identify_interval je vyjádřen v minutách, state_interval v sekundách. Obě nastavení mohou obsahovat DISABLED. Nastavení zařízení je záměrně odděleno od identifikačních dat a vrací se pouze na explicitní unicast požadavek.

bus_mode je protokol zvolený pro příští spuštění. active_bus_mode je protokol používaný při aktuálním běhu a do restartu se může lišit. Přepínač DIP pro debug vynutí active_bus_mode na hbus, aniž by změnil uložené bus_mode. Hodnota modbus_address se uchovává i v režimu HBUS.

Restart

Data požadavku:

{"device":"restart"}

Modul provede okamžitý hardwarový reset po potvrzení ACK na transportní úrovni. Aplikační odpověď se neposílá.

Obnovení továrního nastavení

Data požadavku:

{"device":"factory_reset"}

Modul odstraní trvalou konfiguraci, data o pádech a veškerý firmware v souborovém systému a poté restartuje do aplikace vestavěné ve firmwaru (frozen). Před resetem se neposílá aplikační odpověď.

Nastavení adresy zařízení

Data požadavku:

{"device":{"set_device_address":"12abcdef"}}

Odpověď při úspěchu:

{"device":"DEVICE ADDRESS UPDATED"}

Odpověď při chybě:

{"device":"DEVICE ADDRESS UPDATE FAILED"}

Klienti musí posílat přesně osm hexadecimálních znaků a nesmějí posílat 00000000 ani ffffffff. Aktuální implementace vyhodnocuje prvních osm znaků, takže delší řetězce zkrátí místo odmítnutí. Adresa se převede na malá písmena a okamžitě trvale uloží. Úspěšná odpověď již používá novou zdrojovou adresu.

Nastavení rychlosti HBUS

Data požadavku:

{"device":{"set_hbus_baudrate":115200}}

Úspěšná odpověď vrací úplné trvale uložené nastavení:

{"device_settings":{"address":"cf38542d","alias":"Kitchen switches","hbus_baudrate":115200,"identify_interval":5,"state_interval":"DISABLED"}}

Odpověď při chybě:

{"device":"HBUS BAUDRATE UPDATE FAILED"}

Povolené rychlosti jsou 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400 a 460800. Odpověď se odešle aktuální rychlostí. Nová rychlost se načte z flash při příštím restartu; řídicí jednotka musí svou rychlost odpovídajícím způsobem změnit.

Nastavení režimu sběrnice

Data požadavku:

{"device":{"set_bus_mode":{"mode":"modbus","modbus_address":17}}}

mode musí být hbus nebo modbus. modbus_address musí být od 1 do 247. Příkaz uloží obě hodnoty a vrátí úplná data device_settings. Aktivní transport se změní až po restartu. Nastavená rychlost UART je společná pro HBUS a Modbus RTU.

Odpověď při chybě:

{"device":"BUS MODE UPDATE FAILED"}

Pro obnovení přístupu lze spustit modul se zapnutým debug DIP přepínačem, který vynutí HBUS při uložené rychlosti. Tovární reset obnoví HBUS na 19200 Bd.

Nastavení aliasu modulu

Data požadavku:

{"device":{"set_alias":"Kitchen switches"}}

Z aliasu se odstraní krajní bílé znaky, ihned se trvale uloží a zahrne do každé identifikační odpovědi. Může obsahovat text UTF-8, nesmí obsahovat řídicí znaky a je omezen na 64 bajtů po zakódování. Prázdný řetězec jej vymaže. Úspěšná změna vrátí úplná identifikační data unicastem. Odpověď při chybě:

{"device":"ALIAS UPDATE FAILED"}

Nastavení intervalu automatické identifikace

Data požadavku:

{"device":{"set_identify_interval":30}}

Povolené intervaly jsou 1, 5, 10, 30 a 60 minut. Automatickou identifikaci při nečinnosti lze vypnout pomocí:

{"device":{"set_identify_interval":"DISABLED"}}

Hodnota se okamžitě trvale uloží. Úspěšná změna vrátí unicastem úplná data device_settings včetně nového identify_interval. Neplatné hodnoty vrátí:

{"device":"IDENTIFY INTERVAL UPDATE FAILED"}

Vypnutí automatické identifikace nepotlačí explicitní unicast ani broadcast požadavky na identifikaci. Nepotlačí ani jednu identifikaci naplánovanou s náhodnou prodlevou až deset sekund po spuštění v režimu debug.

Nastavení intervalu automatického odesílání stavu

Data požadavku:

{"device":{"set_state_interval":30}}

Povolené intervaly jsou 5, 30, 60 a 300 sekund. Automatické odesílání stavu je ve výchozím nastavení vypnuté a lze jej explicitně vypnout pomocí:

{"device":{"set_state_interval":"DISABLED"}}

Hodnota se okamžitě trvale uloží. Úspěšná změna vrátí unicastem úplná data device_settings včetně nového state_interval. Neplatné hodnoty vrátí:

{"device":"STATE INTERVAL UPDATE FAILED"}

V každém povoleném intervalu modul sestaví stejná úplná stavová data jako pro {"g":"a"} a odešle je na 00000000. Paket má r nastavené na 0: nevyžaduje ACK a neopakuje se. Neúspěšný pokus nebo pokus při obsazené sběrnici se přeskočí až do dalšího nastaveného intervalu.

Po spuštění nebo změně intervalu se první odeslání odloží o jeden interval plus náhodný posun až do délky celého intervalu. Každý další interval má náhodnou odchylku plus nebo minus deset procent. Moduly spuštěné současně proto nezůstávají synchronizované.

Konfigurace portů

Čtení přiřazení

Data požadavku:

{"port":"get"}

Příklad odpovědi:

{"port":{"A":"button_simple","B":"encoder_reverse"}}

Prázdná tabulka se hlásí jako:

{"port":"PORT TABLE EMPTY"}

Změna přiřazení

Data požadavku:

{"port":{"A":"button_double","B":"encoder","C":"input_safe"}}

Zadané klíče se sloučí se stávajícím přiřazením a vrátí se celá tabulka. Podporované režimy jsou button_simple, button_double, input, input_safe, impulse_counter, impulse_counter_safe, output, output_safe, encoder, encoder_reverse, pwm_50hz, pwm_1khz, pwm_25khz, adc_raw_passive, adc_raw_active, adc_pullup_passive a adc_pullup_active. PWM režimy jsou povoleny pouze na portech B a C; ADC režimy pouze na portu A. Přiřazení se ihned trvale uloží. Restartujte modul, aby se podle nového přiřazení znovu vytvořila obsluha vstupů, výstupy a detekce čidel.

Vymazání přiřazení

Data požadavku:

{"port":"reset"}

Odpověď:

{"port":"PORT TABLE TRUNCATED"}

Aktivní provozní konfigurace zůstává platná až do restartu.

Kompenzace čidel

Kompenzační hodnoty jsou přičítané korekce aplikované na odpovídající pole v odpovědi na {"g":"a"}. Nepřepisují uložené nezpracované hodnoty měření.

Čtení kompenzací

{"compensation":"get"}

Příklad odpovědi:

{"compensation":{"ds":{"100000a3":{"tmp":-0.4}},"scd4x":{"0":{"co2":25}}}}

Prázdná tabulka se hlásí jako:

{"compensation":"COMPENSATION TABLE EMPTY"}

Změna kompenzací

{"compensation":{"ds":{"100000a3":{"tmp":-0.4}}}}

Zadané skupiny čidel na nejvyšší úrovni se sloučí se stávající tabulkou, ihned se trvale uloží a vrátí v odpovědi. Aktualizace skupiny, například ds, nahradí celou tuto skupinu; slučování není rekurzivní.

Vymazání kompenzací

{"compensation":"reset"}

Odpověď:

{"compensation":"COMPENSATION TABLE TRUNCATED"}

Konfigurace SCD4x

Čidla SCD4x se adresují indexem od nuly používaným v naměřených datech. Jeden požadavek může obsahovat příkazy pro více čidel, ale záznam každého čidla obsahuje jeden příkaz.

Struktura požadavku:

{
  "scd4x": {
    "0": {"cmd":"set_sensor_altitude","value":250}
  }
}

Struktura odpovědi:

{
  "scd4x": {
    "0": {"set_sensor_altitude":250}
  }
}

Před každým příkazem se periodické měření zastaví a poté znovu spustí.

Okolní tlak se interně omezí na 70000-120000 Pa. Neznámé indexy čidel a příkazy se ignorují a nevytvářejí aplikační odpověď.

Přenos firmwaru

Příkazy pro firmware používají objekt fw. Odesílatel by měl do každého požadavku vložit nové request_id tvořené osmi hexadecimálními znaky s malými písmeny. Modul je zkopíruje do odpovídající odpovědi, takže hbusd může odmítnout opožděné odpovědi z předchozího pokusu.

Odpovědi pro firmware mají tuto strukturu:

{
  "fw": {
    "request_id":"12ab34cd",
    "state":"receiving",
    "id":"4386db09768e458e",
    "offset":512,
    "size":43548
  }
}

ID přenosu tvoří prvních 16 znaků SHA-256 celého archivu. Maximální velikost dekódovaného bloku je 512 bajtů.

Zahájení nebo navázání přenosu

{
  "fw": {
    "command":"begin",
    "request_id":"12ab34cd",
    "size":43548,
    "sha256":"4386db09768e458e5f76cb9036dbbdf4f39d62d4906b76cfcf20fc8589e131fe"
  }
}

Stav odpovědi je receiving, ready nebo installed. U existujícího odpovídajícího přenosu určuje offset, odkud má odesílatel pokračovat. Zahájení přenosu jiného archivu zahodí neúplný nebo připravený archiv, ale nikdy neodstraní sloty nainstalovaného firmwaru.

Odeslání bloku

{
  "fw": {
    "command":"chunk",
    "request_id":"23bc45de",
    "id":"4386db09768e458e",
    "offset":0,
    "data":"<Base64 data>"
  }
}

Bloky musí navazovat. Opakování již kompletně uloženého bloku se přijme pouze tehdy, když se jeho bajty shodují. Překrývající se, vynechané, změněné nebo příliš velké bloky se odmítají.

Dokončení nahrávání

{"fw":{"command":"finish","request_id":"34cd56ef","id":"4386db09768e458e"}}

finish ověří celkovou velikost a SHA-256 před změnou stavu na ready. Archiv neinstaluje ani neaktivuje.

Dotaz na stav

{"fw":{"command":"status","request_id":"45de67f0"}}

Možné stavy:

Odpovědi receiving, ready, installed a rolled_back obsahují id, offset a size. Stavy po instalaci obsahují také version. rolled_back přidává reason.

Instalace

{"fw":{"command":"install","request_id":"56ef7801","id":"4386db09768e458e"}}

Instalace ověří chráněný obal HBE1, ID klíče AES, kontrolní otisk rozšifrovaného vnitřního archivu, manifest a každý rozbalený soubor. Poté přepne kompletní sloty v souborovém systému a vrátí stav installed s verzí z manifestu. Modul se automaticky nerestartuje.

Zrušení přenosu

{"fw":{"command":"abort","request_id":"67f08912","id":"4386db09768e458e"}}

Zrušení odstraní archiv ve stavu receiving nebo ready a vrátí idle. Firmware ve stavu installed nebo rolled_back nelze takto zrušit, protože již patří do sady aktivního a předchozího slotu.

Chybová odpověď

Chyby protokolu, ověření a stavu se vracejí jako:

{
  "fw": {
    "request_id":"67f08912",
    "state":"error",
    "error":"firmware chunk offset mismatch"
  }
}

Text chyby je určen pro diagnostiku a v budoucí verzi firmwaru může být upřesněn. Klienti by se měli rozhodovat především podle state, nikoli podle rozboru chybového řetězce.

Chování starších příkazů při chybách

Příkazy přenosu firmwaru vždy vracejí strukturovaný stav úspěchu nebo chyby. Starší příkazy pro zařízení, porty, kompenzace a SCD4x nemají společný formát chybové odpovědi. Podle příkazu vracejí stavový řetězec velkými písmeny, jsou tiše ignorovány nebo pouze zapíší výjimku do ladicího logu. Proto:

• Považujte transportní ACK pouze za potvrzení přijetí paketu.
• Čekejte na dokumentovanou odpověď, pokud existuje.
• Na řídicí jednotce používejte časový limit.
• Po změně trvalé konfigurace načtěte nastavení zpět.