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:

Developer Implementation

C Client Library (ESP-IDF & Arduino)

On the microcontroller, USMP logs the error description and tears down the local session context:

if (pkt.seq != ctx->rx_seq) {
    USMP_LOGE(TAG, "Sequence mismatch detected!");
    
    // Invalidate the session locally; transport is closed by usmp_recv returning error
    ctx->established = false;
    return -1;
}

Python SDK Exceptions

The Python SDK maps these binary error codes directly into standard Python exceptions. This makes it incredibly easy to write error-handling logic:

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

async def handle_telemetry(session: USMPSession):
    try:
        while True:
            data = await session.recv()
            print(f"Received data: {data}")
    except ConnectionClosedError:
        print(f"Device {session.device_id} disconnected cleanly.")
    except CryptoError:
        # This will fire if someone tries to send data with a bad PSK or session key!
        print(f"Decryption failed for device {session.device_id}! Key mismatch or tampering.")
    except Exception as e:
        print(f"Unexpected error: {e}")

Here are the exception classes you can catch:

• USMPError — Base exception for all USMP errors.
• FrameError — Malformed binary structure.
• CRCError — CRC check failed.
• MagicError — Magic bytes (0xABCD) mismatch.
• VersionError — Unsupported version.
• HandshakeError — Key negotiation failed.
• AuthError — PSK verification failed.
• CryptoError — Decryption or GCM authentication tag failed.
• SequenceError — Replay protection triggered (sequence number mismatch).
• TimeoutError — Keepalive watchdog timer expired.