API Status Codes
Artok uses a standardized set of status codes across the C Widget API, the Lua Engine, and the Connect Protocol. These codes allow your master firmware to handle errors—such as missing assets or hardware failures—gracefully.
🟢 1. Success Codes (0x00 - 0x0F)
These codes indicate that the requested operation was completed successfully or that the system is in an optimal state.
| Constant | Value | Description |
|---|---|---|
ATK_API_OK | 0x00 | The command was executed and acknowledged. |
ATK_CONN_SYNCED | 0x01 | Handshake complete; Runtime is linked with Artok Studio. |
🟡 2. Widget & Logic Errors (0x10 - 0x2F)
These codes are returned by atk_api.c functions when the request is valid but cannot be executed due to the current UI state.
| Constant | Value | Description | Recovery Step |
|---|---|---|---|
ATK_API_ERR_INVALID | 0x01 | Malformed request or missing JSON fields. | Verify your JSON payload structure. |
ATK_API_ERR_NOT_FOUND | 0x02 | The UUID does not exist in the loaded ui.bin. | Check the spelling in Artok Studio and re-flash. |
ATK_API_ERR_TYPE | 0x03 | Operation mismatch (e.g., set_text on a Gauge). | Use the correct API setter for the widget type. |
ATK_API_ERR_BUSY | 0x12 | The UI thread is currently locked or transitioning. | Retry the operation in the next ART_MainLoop. |
🔴 3. System & Transport Errors (0x40 - 0x5F)
These codes indicate a failure at the hardware or protocol level. They are often logged to the System Output in Artok Studio.
| Constant | Value | Description | Recovery Step |
|---|---|---|---|
ATK_ERR_PROTOCOL | 0x40 | Framing error or Start-of-Frame (SOF) mismatch. | Check for UART wiring noise or baud rate mismatch. |
ATK_ERR_CRC | 0x41 | The packet payload was corrupted during transit. | Ensure you are using shielded cables for long runs. |
ATK_ERR_FLASH_CRC | 0x42 | The ui.bin header CRC does not match the data. | Re-flash the device from Artok Studio. |
ATK_ERR_MALLOC | 0x43 | The HMI failed to allocate memory for a widget. | Reduce image asset sizes or increase heap size. |
🛠️ Handling Errors in C
Always check the return status of an API call. For non-critical UI updates, a simple log is sufficient; for critical systems, you may want to trigger a retry.
atk_api_status_t status = atk_api_set_value("UUID_PUMP_SPEED", 85);
if (status != ATK_API_OK) {
// Log the error for debugging
printf("HMI Error: %s (0x%02X)\n", atk_status_to_str(status), status);
if (status == ATK_API_ERR_NOT_FOUND) {
// Handle missing UI component gracefully
emergency_shutdown();
}
}