Error Handling: Our Safety Seatbelts

USMP operates on a very simple, security-first philosophy: fail fast.

In some network protocols, if something goes wrong, the systems will try to negotiate, recover, or patch things up on the fly. In a security protocol, this is extremely dangerous. If there is a crack in a secure tunnel, we don't try to repair it while it's active. Instead, we immediately shred the session keys, close the connection, and build a brand-new tunnel from scratch.

Think of our error handling rules as safety seatbelts: if they detect any abnormal movement, they lock down instantly to protect your device and your data.

The PKT_ERROR Frame (0xFF) [Reserved]

When supported in future versions, if one side detects a protocol violation or cryptographic failure, it will attempt to tell the other side why it is disconnecting by sending a PKT_ERROR packet before closing the socket.

Payload Layout (3 bytes)

• Byte 0 (1 byte): code — The error code integer.
• Bytes 1..2 (2 bytes): detail — Optional supplementary details (u16 little-endian, such as the sequence number that caused a mismatch).

Standardized Error Codes (Reserved)

Safety Rules: How We Handle Violations

Here is exactly how the client and server react to various protocol violations:

Programmatic Status Codes (usmp_err_t & USMPErrorCode)

USMP operations return strongly typed status codes across the C core, Arduino port, and Python SDK:

Developer Implementation

C Client Library (ESP-IDF & Core)

On microcontrollers, functions return usmp_err_t status codes directly. Translate any code to a human-readable string with usmp_strerror():

usmp_err_t err = usmp_send(&ctx, data, len);
if (err != USMP_OK) {
    ESP_LOGE(TAG, "Transmission failed: %s (code %d)", usmp_strerror(err), err);
    if (err == USMP_ERR_PEER_CLOSED) {
        ESP_LOGI(TAG, "Server shut down gracefully.");
    }
}

Arduino Port

USMPClient automatically captures status codes and provides helper getters:

if (!usmp.begin(transport)) {
    Serial.printf("Connection failed: %s (error %d)\n",
                  usmp.lastErrorString(), usmp.lastError());
}

Python SDK Exceptions

The Python SDK maps errors into rich exception classes, each providing a .code: USMPErrorCode attribute:

from usmp import USMPSession
from usmp.errors import ConnectionClosedError, CryptoError, USMPTimeoutError, USMPError

async def handle_telemetry(session: USMPSession):
    try:
        while True:
            data = await session.recv()
            session.print(data)
    except ConnectionClosedError:
        print(f"Device {session.device_id} disconnected cleanly (sent BYE).")
    except CryptoError as e:
        print(f"Decryption failed ({e.code}): Key mismatch or tampering.")
    except USMPTimeoutError:
        print(f"Session timed out waiting for device heartbeat.")
    except USMPError as e:
        print(f"USMP error ({e.code}): {e}")

Here are the exception classes you can catch:

• USMPError — Base exception for all USMP errors. Carries .code: USMPErrorCode.
• FrameError — Malformed binary structure (ERR_BAD_FRAME).
• CRCError — CRC check failed.
• MagicError — Magic bytes (0xABCD) mismatch.
• VersionError — Unsupported version (ERR_VERSION).
• HandshakeError — Key negotiation failed.
• AuthError — PSK verification failed (ERR_AUTH).
• CryptoError — Decryption or GCM authentication tag failed (ERR_CRYPTO).
• SequenceError — Replay protection triggered or sequence overflow (ERR_SEQ).
• USMPTimeoutError — Keepalive watchdog timer expired (TimeoutError alias provided for backward compatibility).
• ConnectionClosedError — Remote peer closed or sent PKT_BYE (USMPErrorCode.PEER_CLOSED).