Řešení potíží při integraci SDK

Regenerace projektu CubeMX

Příklad je projekt CubeMX; Generate Code přepíše vše mimo USER CODE BEGIN/END. Před regenerací si přečtěte examples/nucleo_h723zg/REGEN-NOTES.md (u projektu bez RTOS examples/nucleo_h723zg_baremetal/REGEN-NOTES.md) — stručná verze:

Svá volání vkládejte pouze do sekcí USER CODE se jmény, která CubeMX zná. Sekci s vymyšleným jménem příští generování tiše zahodí.
Jména úloh, priority a zásobníky žijí v .ioc (Tasks and Queues) — měňte je tam, ne ve freertos.c.
Hodnoty lwipopts.h, které CubeMX zná, nese .ioc; blok USER CODE v něm (LWIP_TCP_KEEPALIVE, LWIP_SO_LINGER, …) přežije; obdobně FreeRTOSConfig.h (configNUM_THREAD_LOCAL_STORAGE_POINTERS v USER Defines).
Paměť STM32H7: Ethernet DMA nedosáhne na DTCM RAM, proto linker skript příkladu umisťuje .data/.bss/heap/stack do AXI SRAM (RAM_D1) a deskriptory DMA plus pool RX bufferů do RAM_D2 (32 KB na H723). Linker skript regenerace zcela přepíše — obnovte jej ze správy verzí.
LWIP/Target/ethernetif.c: INTERFACE_THREAD_STACK_SIZE (výchozí ST 350 B = přetečení zásobníku s CMSIS v2, použijte 2048) a ETH_RX_BUFFER_CNT (v příkladu 16; RX pool se musí vejít do RAM_D2, jinak ASSERT v linker skriptu překlad zastaví) se každou regenerací vrátí — .ioc je nenese.
Heap lwIP je v příkladu umístěn přes LWIP_RAM_HEAP_POINTER na surovou adresu na vrcholu AXI SRAM; RAM_D1 je v linker skriptu zkrácena, aby na ni linkerem umístěná data nikdy nedosáhla.
550 MHz na H723 vyžaduje option byte CPU_FREQ_BOOST; kód HAL option byty neprogramuje: STM32_Programmer_CLI -c port=SWD -ob CPU_FREQ_BOOST=1 jednou pro každou desku.
Po každé regeneraci: git diff je kontrolní seznam, poté překlad (ASSERTy linkeru hlídají rozložení RAM), poté znovu spustit scanner adres (Adresy proměnných pro QInsight).

Příznaky, příčiny, nápravy

Příznak	Pravděpodobná příčina	Co udělat
Červená LED po resetu (`QfwXcpServer_Init` vrací false)	`get_clock_us == NULL`; rekurzivní mutex nebo úloha nevytvořeny (`configSUPPORT_STATIC_ALLOCATION`, `configUSE_RECURSIVE_MUTEXES`); `qfw_xcp_init` odmítl konfiguraci (příčiny selhání inicializace); na CAN: nepodporovaná bitová rychlost nebo selhala inicializace HAL FDCAN	nastavte `log_level` 3, čtěte virtuální COM port; zkontrolujte konfiguraci FreeRTOS; porovnejte s `xcp_server.c` příkladu
Bez RTOS: `QfwXcpTcpRawGlue_Init` vrací false (`Error_Handler`)	voláno před `MX_LWIP_Init()` (naslouchající pcb nelze vytvořit), `get_clock_us == NULL`, `qfw_xcp_init` odmítl konfiguraci	pořadí volání v `main.c` podle příkladu (Integrace bez RTOS); `log_level` 3
Bez RTOS: překlad glue skončí `#error` nebo `_Static_assert`	`NO_SYS` není 1, chybí `LWIP_TCP_KEEPALIVE 1`, nebo `TCP_SND_BUF` je menší než segment enginu (1480 B)	doplňte volby do bloku `USER CODE BEGIN 1` v `lwipopts.h` (lwIP bez RTOS)
Na portu 5555 nic nenaslouchá (na COM portu chybí řádek `listening`)	úloha glue neběží (zásobník, priorita, statická alokace), lwIP neběžel v okamžiku `QfwXcpGlue_Init` (volejte po `MX_LWIP_Init()`), nesprávná IP nebo podsíť; bez RTOS: ve smyčce se nevolá `MX_LWIP_Process()`	nejprve `ping` na desku; zkontrolujte vytvoření úlohy; pořadí volání ve `StartDefaultTask` (bez RTOS tělo smyčky v `main.c`)
QInsight: timeout připojení, přestože `ping` funguje	firewall na PC, nesprávný port, deska stále drží spojení předchozího mastera, který zmizel (viz další řádek)	zkontrolujte port; počkejte na vypršení keepalive (~5 s) nebo desku resetujte
Master zmizel, deska zůstává `connected` a dalšího mastera odmítá déle než ~5 s	`LWIP_TCP_KEEPALIVE` není 1 (`TCP_KEEPIDLE/INTVL/CNT` v glue pak nemají účinek), nebo `LWIP_SO_LINGER` není 1 (zavření setrvává; jen glue s FreeRTOS)	nastavte obojí v `lwipopts.h` (nastavení CubeMX); glue se pak do ~5 s vrátí na `accept` — nebo okamžitě, když vypadne vlastní linka desky a je zapojen link callback v `lwip.c` (FreeRTOS, bez RTOS)
QInsight: `connected` a vzápětí `forcibly closed by the remote host`, dokola každou sekundu	deska má připojeného jiného mastera (druhá instance QInsight, jiný klient na portu 5555) a nové spojení odmítá; nebo předchozí relace tohoto PC po výpadku ještě nevypršela (keepalive ~11 s)	ukončete první relaci, nebo počkejte na keepalive; driver se připojí sám (spojení bez RTOS)
Bez RTOS: odpovědi a DAQ data chodí se zpožděním nebo v dávkách	dlouhý průchod hlavní smyčky (výpis logu na úrovni 3 ≈ 4 ms na řádek, blokující práce ve smyčce), nebo Nagle a zpožděný ACK mastera u pomalých proudů	zkraťte práci v průchodu, `log_level` 2; viz model kontextů
Časové značky skáčou, jdou zpět nebo běží nesprávnou rychlostí	`Clock64_Update` se nevolá, volá se z více úloh, nebo `CLOCK_TICKS_PER_S` ≠ skutečná frekvence CPU	jediný volající (`QfwXcpServer_Tick` z default tasku, perioda < 7,8 s); `CLOCK_TICKS_PER_S` nastavte podle clock tree
DAQ data se zastaví, QInsight hlásí mezery v čítači / overrun	přetečení vysílací fronty nebo backpressure transportu (`qfw_xcp_is_backpressured()`); na CAN limit sběrnice (dimenzování a propustnost); bez RTOS: `TCP_SND_BUF` příliš malý pro souvislý tok	zmenšete sadu měření nebo rychlost; na TCP zvětšete `GLUE_QUEUE_SEGMENTS` (bez RTOS i `TCP_SND_BUF`); zkontrolujte zatížení Ethernetu
Matice se načte, ale obsahuje nesmysly nebo chybí osy	adresa z jiného sestavení; objekt není souvislý blok osa X, osa Y, data (jiné pořadí, výplň mezi členy); osy mají jiný počet bodů než data	znovu spusťte scanner; dodržte konvenci z Pole, křivky a mapy (`pack(1)`, `<name>_x` / `<name>_y` / `<name>`)
STIM hodnota se nikdy neaplikuje	event STIM listu se po vaší aktualizaci nespouští, nebo váš kód proměnnou po triggeru přepisuje	spouštějte jednou za cyklus po aktualizaci; viz rozdělení raw/value/bypass v `demo_signals.cpp`
Náhodné poškození dat / hard fault při zátěži	kritická sekce není reentrantní, `rx` a `poll` ze dvou kontextů, trigger z ISR se sekcí na mutexu; bez RTOS: `qfw_xcp_rx` / `qfw_xcp_poll` nebo lwIP volané z přerušení (kontrakt enginu)	zachovejte strukturu přiložené glue; bez RTOS z přerušení jen `qfw_xcp_trigger_event` (kryje ho sekce `PRIMASK` v glue), nic jiného
CAN: žádná odpověď na `CONNECT`	zapojení transceiveru nebo zakončení, bitová rychlost nebo id neodpovídají QInsight, rámce na id mastera nedojdou do `qfw_xcp_rx_can_frame` (filtr)	zkontrolujte `[XCP I] SDK server on CAN: …` na COM portu, poté sběrnici CAN monitorem (XCP on classic CAN)
CAN: opakuje se `[XCP W] CAN bus-off, recovering`	žádný jiný uzel nepotvrzuje (transceiver, zakončení, neshoda bitové rychlosti)	opravte sběrnici; glue se zotaví automaticky a resetuje session
QInsight: proměnná ukazuje `Source: not found`, chybí modrý odznak, nelze ji navázat na control	proměnná je definována, ale není přiřazena k protokolu	přiřaďte ji k protokolu XCP a vyplňte Comm params (tři kroky v QInsight)
QInsight čte nesmyslné hodnoty nebo zápisy míří do nesprávné paměti	adresy ze staršího sestavení, obraz `Release` bez `volatile`, nebo nově přeložený obraz s posunutými objekty	znovu spusťte scanner, znovu naimportujte nebo opravte Comm params; proměnné deklarujte jako `volatile` globální

Podpora: info@qenex.net — přiložte qfw_xcp_version(), log glue z okolí problému a hodnoty své konfigurace glue. Stranu QInsight u potíží s XCP popisuje kapitola Řešení potíží — XCP a DAQ.