kaptan/docs/src/errors.md

Errors

Public Kaptan error enums derive the pure KaptanError implementation:

#[derive(Debug, kaptan_log::KaptanError)]
enum SensorError {
    TransferFault,
    UnexpectedIdentity(u8),
}

The derive implements core::error::Error, Display, and ErrorReport. It creates a static module::Type::Variant error path without allocating, publishing telemetry, exposing generic source values, or changing safety state. Renaming a module, type, or variant changes that path; it is not a stable machine protocol identity.

Normal-task code may use log::error!("{error}"); it is routed as a bounded KAPTAN_ERROR. ISR-adjacent flight paths may enqueue the derived static message through their existing bounded mailbox. Neither route is a replacement for safety state, actuator inhibit, or typed configuration results.

What the receiver sees

• Configuration writes receive authoritative structured failures through KAPTAN_CONFIG_RESULT: operation, lifecycle state, field IDs, validation rule, and protocol error code.
• Runtime driver and link faults reach the F722 MAVLink worker as a KAPTAN_ERROR path, subject to bounded transport admission. The error payload is { flags, path_length, additional_information_length, path[96], additional_information[64] }; each length identifies the valid UTF-8 prefix and the optional information field may be empty. A KaptanError derive supplies the type/variant path and normally leaves additional information empty. log::error! uses the Rust log target as the path and the formatted message as additional information.
• A rejected configuration operation may enqueue a companion KAPTAN_ERROR whose path is the high-level ProtocolError identity. It is intentionally not correlated and carries no field/rule detail; the matching KAPTAN_CONFIG_RESULT remains the sole precise authority.
• Control, navigation, safety, and simulator error types are derive-ready but their live owners are not yet attached to a MAVLink worker.
• KAPTAN_SHUTDOWN, defined in definitions/kaptan/shutdown.xml, represents only a future completed orderly, output-inhibited shutdown. It is not a shutdown request, panic, hard-fault, reset, or retention-record protocol. F722 still uses panic-halt; it does not claim a live panic frame or retained-record replay.

No diagnostic message may synchronously transmit from a panic handler, hard fault, ISR, DMA callback, or motor-inhibit path. A later target integration must inhibit outputs first, persist a validated crash record, then report it only after the next boot’s static board telemetry is available.