LOGGING

Summary

File transfer message. Acts as a transport layer for the MAVLink FTP protocol (an FTP-like protocol over MAVLink).

Status

Supported (RX & TX)

Directionality

• TX (Transmit): All Vehicles - Sends FTP replies (file data, directory listings).
• RX (Receive): All Vehicles - Receives FTP requests (read, list, write).

Reception (RX)

Handled by GCS_MAVLINK::handle_file_transfer_protocol.

Source: libraries/GCS_MAVLink/GCS_FTP.cpp

Protocol Logic

Implements a stateful FTP server.

• OpCodes: Open, Read, Write, Terminate, ListDirectory, CreateDirectory, RemoveFile, etc.
• Transport: Data is encapsulated in the payload field.

Data Fields

• target_network: Network ID (0 for default).
• target_system: System ID.
• target_component: Component ID.
• payload: Variable length payload containing OpCode, Session ID, Offset, and Data.

Practical Use Cases

1. Log Downloading:
   • Scenario: Downloading Dataflash logs via MAVLink.
   • Action: Mission Planner uses MAVFTP to list files in @SYS/logs and download the .bin files.
2. Script Upload:
   • Scenario: Uploading a Lua script.
   • Action: User uploads script.lua to the scripts/ directory on the SD card via MAVFTP.

Key Codebase Locations

• libraries/GCS_MAVLink/GCS_FTP.cpp:71: Handler.

Summary

The LOG_REQUEST_LIST message is sent by a Ground Control Station (GCS) to request a list of available logs on the vehicle's DataFlash storage. The vehicle responds by streaming LOG_ENTRY messages for the requested range.

Status

RX Only

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles (Starts log listing)

Reception (RX)

Reception is handled by AP_Logger::handle_log_request_list within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:68.

Protocol Logic

1. State Check: It checks if a log download is already in progress (_log_sending_link != nullptr). If so, it rejects the request.
2. Range Setup: It parses the start and end log indices.
3. Sanitization: It clamps the range against the actual number of logs present (_log_num_logs).
4. Activation: It sets the transfer_activity state to TransferActivity::LISTING and assigns the requesting link as the active channel. The scheduler then iteratively sends LOG_ENTRY messages.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• start: First log ID to list.
• end: Last log ID to list.

Practical Use Cases

1. Log Browser:
   • Scenario: A user connects to the drone via USB and opens the "Download Logs" screen in Mission Planner.
   • Action: The GCS sends LOG_REQUEST_LIST (start=0, end=0xFFFF) to get a full directory of flight logs.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:68: Implementation of the handler.

Summary

The LOG_ENTRY message is a reply to a LOG_REQUEST_LIST (117) command. It provides metadata about a single DataFlash log file on the vehicle, including its ID, size, and timestamp. The vehicle sends a stream of these messages to list all available logs.

Status

TX Only

Directionality

• TX (Transmit): All Vehicles (Log listing response)
• RX (Receive): None (Ignored)

Transmission (TX)

Transmission is handled by AP_Logger::handle_log_send_listing within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:250.

Protocol Logic

1. Iteration: The logger iterates from start to end as requested by LOG_REQUEST_LIST.
2. Metadata Retrieval: For each log index, it calls get_log_info to retrieve the file size (bytes) and UTC timestamp.
3. Completion: When the last entry is sent, the transfer activity state is reset to IDLE.

Data Fields

• id: Log id.
• num_logs: Total number of logs available.
• last_log_num: High log number.
• time_utc: UTC timestamp of log creation (seconds since 1970).
• size: Log size in bytes.

Practical Use Cases

1. Log Browser:
   • Scenario: A user clicks "Download Logs" in Mission Planner.
   • Action: Mission Planner receives a stream of LOG_ENTRY messages and populates a table showing Log ID, Date, and Size, allowing the user to select specific flights for download.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:250: Implementation of the sender.

Summary

The LOG_REQUEST_DATA message is sent by a Ground Control Station (GCS) to request a specific chunk of data from a log file. It initiates or continues the download of a DataFlash log.

Status

RX Only

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles (Starts/Continues log download)

Reception (RX)

Reception is handled by AP_Logger::handle_log_request_data within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:107.

Protocol Logic

1. State Check: Verifies if another download is active on a different channel.
2. Initialization: If this is a new request or a different log ID, it looks up the log's physical location on storage (page/offset boundaries).
3. Range Setup: It sets the internal read pointer (_log_data_offset) to the requested offset (ofs) and calculates the bytes remaining to send (count).
4. Activation: It transitions to the TransferActivity::SENDING state, which causes the scheduler to pump LOG_DATA packets.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• id: Log ID (from LOG_ENTRY).
• ofs: Offset into the log file (bytes).
• count: Number of bytes to send.

Practical Use Cases

1. Downloading a Log:
   • Scenario: A user downloads a 10MB log.
   • Action: The GCS sends a sequence of LOG_REQUEST_DATA messages.
     1. id=5, ofs=0, count=90 -> Receives LOG_DATA.
     2. id=5, ofs=90, count=90 -> Receives LOG_DATA.
     3. ...until EOF.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:107: Implementation of the handler.

Summary

The LOG_DATA message carries a fixed-size chunk of binary data from a specific DataFlash log file. It is the response to a LOG_REQUEST_DATA (119) message. A sequence of these messages constitutes a file download.

Status

TX Only

Directionality

• TX (Transmit): All Vehicles (Log content transfer)
• RX (Receive): None (Ignored)

Transmission (TX)

Transmission is handled by AP_Logger::handle_log_send_data within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:302.

Protocol Logic

1. Read: It reads len bytes (max 90) from the storage backend (File or Block) at the current _log_data_offset.
2. Pack: It packs the data into the data array of the message.
3. Pad: If the read bytes are fewer than 90, the remaining bytes are zeroed out.
4. Send: The message is broadcast on the requesting channel.
5. Advance: The _log_data_offset is incremented. If the requested byte count is met or the end of the log is reached, transmission stops (IDLE).

Data Fields

• id: Log ID (1 through N).
• ofs: Offset into the log file (bytes).
• count: Number of bytes in this packet (typically 90).
• data: Raw log data (90 bytes).

Practical Use Cases

1. Downloading a Log:
   • Scenario: Mission Planner is downloading a log.
   • Action: ArduPilot sends LOG_DATA packets rapidly. Mission Planner concatenates the data fields to reconstruct the .BIN file on the user's disk.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:302: Implementation of the sender.

Summary

The LOG_ERASE message is sent by a Ground Control Station (GCS) to command the vehicle to erase all stored DataFlash logs.

Status

RX Only

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles (Erases all logs)

Reception (RX)

Reception is handled by AP_Logger::handle_log_request_erase within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:165.

Protocol Logic

1. Decoding: The message is decoded (though it has no fields to use).
2. Action: The EraseAll() function is called on the logger backend. This typically reformats the SD card or erases the flash chip, removing all logs.

Data Fields

• target_system: System ID.
• target_component: Component ID.

Practical Use Cases

1. Maintenance:
   • Scenario: A user wants to clear space on the SD card before a new mission.
   • Action: Clicking "Erase Logs" in the GCS sends this message.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:165: Implementation of the handler.

Summary

The LOG_REQUEST_END message is sent by a Ground Control Station (GCS) to terminate a log transfer session. This tells the vehicle to stop sending LOG_DATA or LOG_ENTRY messages and release any resources associated with the transfer.

Status

RX Only

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles (Stops log transfer)

Reception (RX)

Reception is handled by AP_Logger::handle_log_request_end within libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:174.

Protocol Logic

1. State Reset: It sets transfer_activity to IDLE.
2. Resource Release: It clears the _log_sending_link pointer, allowing other MAVLink channels to initiate log transfers.
3. Backend Notification: It calls end_log_transfer() on the active logger backend (e.g., to close the file handle).

Data Fields

• target_system: System ID.
• target_component: Component ID.

Practical Use Cases

1. Cancel Download:
   • Scenario: A user realizes they selected the wrong log and clicks "Cancel" in the GCS.
   • Action: The GCS sends LOG_REQUEST_END, and the stream of LOG_DATA packets stops immediately.
2. Download Complete:
   • Scenario: The GCS successfully receives the last byte of the log file.
   • Action: It sends LOG_REQUEST_END to politely close the session.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLinkLogTransfer.cpp:174: Implementation of the handler.

Summary

A block of dataflash log data sent to a remote listener. This is part of the "Remote Logging" feature where logs are streamed to a companion computer or GCS in real-time.

Status

Supported (TX Only)

Directionality

• TX (Transmit): All Vehicles (if configured) - Sends log blocks.
• RX (Receive): None

Transmission (TX)

ArduPilot sends this message via AP_Logger_MAVLink when remote logging is enabled.

Source: libraries/AP_Logger/AP_Logger_MAVLink.cpp

Protocol Logic

The logger buffers log data and sends it in 200-byte chunks (blocks) to the MAVLink stream.

• Reliability: The system expects REMOTE_LOG_BLOCK_STATUS acks to ensure data integrity.

Data Fields

• target_system: System ID of listener.
• target_component: Component ID of listener.
• seqno: Sequence number (high/low or 32-bit index).
• data: Log data block (200 bytes).

Practical Use Cases

1. Redundant Logging:
   • Scenario: A high-value drone operation requires logs to be saved on a companion computer (Raspberry Pi) in case the flight controller is destroyed.
   • Action: The FC streams REMOTE_LOG_DATA_BLOCK messages to the Pi, which writes them to disk.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger_MAVLink.cpp: Implementation.

Summary

Status/Acknowledgment message for the Remote Logging protocol. Sent by the listener (e.g., companion computer) to the autopilot.

Status

Supported (RX Only)

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles - Receives acks for sent log blocks.

Reception (RX)

Handled by AP_Logger::handle_remote_log_block_status.

Source: libraries/AP_Logger/AP_Logger.cpp

Protocol Logic

The autopilot maintains a buffer of sent blocks. It waits for this status message to confirm which blocks have been safely received by the remote node.

• Gap Filling: If the status indicates missing blocks, the autopilot re-sends them.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• seqno: Latest received sequence number.
• status: Boolean/Enum status (1=OK).

Practical Use Cases

1. Reliable Log Streaming:
   • Scenario: Companion computer misses a packet due to CPU load.
   • Action: It sends REMOTE_LOG_BLOCK_STATUS with the last valid sequence number. ArduPilot resends the missing data.

Key Codebase Locations

• libraries/AP_Logger/AP_Logger.cpp:850: Handler.

Summary

The LOGGING_DATA message is part of a protocol for streaming log data from the vehicle to a Ground Control Station (GCS) in real-time or as a robust download mechanism. It works in conjunction with LOGGING_DATA_ACKED (267) to ensure data integrity.

Status

Unsupported

Directionality

• TX (Transmit): None
• RX (Receive): None

Description

ArduPilot does not implement this message.

For downloading DataFlash logs (.BIN files), ArduPilot uses the standard MAVLink log download protocol involving:

• LOG_REQUEST_LIST (117)
• LOG_ENTRY (118)
• LOG_REQUEST_DATA (119)
• LOG_DATA (120)

The LOGGING_DATA (266) message appears to be an alternative or streaming-focused mechanism that is not currently part of the ArduPilot codebase.

Intended Data Fields (Standard)

• target_system: System ID of the target.
• target_component: Component ID of the target.
• sequence: Sequence number (can wrap).
• length: Data length (bytes).
• first_message_offset: Offset into data where the first message starts.
• data: Logged data (buffer).

Alternative

For log downloads in ArduPilot, refer to LOG_DATA (120).

Theoretical Use Cases

1. Black Box Streaming:
   • Scenario: A high-value experimental aircraft.
   • Action: The vehicle streams critical log data in real-time via LOGGING_DATA. If the vehicle is lost or destroyed, the last seconds of telemetry are preserved on the GCS.
2. Reliable Download:
   • Scenario: Downloading logs over a lossy telemetry link.
   • Action: The protocol uses the sequence numbers and ACKs to re-transmit only the lost packets, ensuring a bit-perfect copy of the log file eventually arrives.

Summary

The LOGGING_DATA_ACKED message is the acknowledged variant of the LOGGING_DATA (266) streaming protocol. It sends log data that requires an explicit LOGGING_ACK (268) from the receiver, ensuring critical data is not lost during transmission.

Status

Unsupported

Directionality

• TX (Transmit): None
• RX (Receive): None

Description

ArduPilot does not implement this message.

It is part of the same unsupported log streaming protocol as LOGGING_DATA (266). ArduPilot relies on the standard LOG_DATA (120) message for log downloads.

Intended Data Fields (Standard)

• target_system: System ID of the target.
• target_component: Component ID of the target.
• sequence: Sequence number.
• length: Data length.
• first_message_offset: Offset to start of first message.
• data: Logged data.

Alternative

For log downloads in ArduPilot, refer to LOG_DATA (120).

Theoretical Use Cases

1. Guaranteed Delivery:
   • Scenario: Sending a critical "Crash Report" packet.
   • Action: The vehicle sends the crash dump via LOGGING_DATA_ACKED and re-transmits it until the GCS confirms receipt with LOGGING_ACK, ensuring the data is not lost in radio noise.

Summary

The LOGGING_ACK message is used to acknowledge the receipt of a LOGGING_DATA_ACKED (267) packet. This closes the loop for the reliable log streaming protocol.

Status

Unsupported

Directionality

• TX (Transmit): None
• RX (Receive): None

Description

ArduPilot does not implement this message.

It is part of the same unsupported log streaming protocol as LOGGING_DATA (266) and LOGGING_DATA_ACKED (267).

Intended Data Fields (Standard)

• target_system: System ID of the target.
• target_component: Component ID of the target.
• sequence: Sequence number (must match the one in LOGGING_DATA_ACKED).

Theoretical Use Cases

1. Flow Control:
   • Scenario: The GCS is overwhelmed by incoming log data.
   • Action: The GCS delays sending LOGGING_ACK, implicitly telling the vehicle to pause transmission until the buffer clears.