File Transfer

2026-11-05Loading rating…

1. Feature Overview

The plugin app and Pilot run in two separate processes, so the plugin cannot hand local files directly to Pilot. The file transfer capability pushes the plugin's local files to Pilot and persists them, after which capabilities like AR projection and map widgets reference these resources by file name. It is the foundation of the "upload the resource first, then use it" pattern.

1.1 Capability Overview

CapabilityDescription
Upload filePush a local file to Pilot for storage, with an upload progress callback
Query file listQuery the list of file names this plugin has uploaded to Pilot

1.2 Use Cases

  • AR projection: upload the SVG icons used by annotations, referenced by file name in the AR tutorial
  • Map widgets: upload marker icons, referenced by file name by the map widget
  • Resource check: query the file list to deduplicate before upload, or confirm resources are ready

2. Interface Call Examples

The examples below assume you have completed SDK initialization and the plugin is connected to Pilot (for connection state, see the Plugin Connection State documentation). All interfaces are called through the manager singleton FileTransferManager.getInstance().

2.1 Upload a File (pushFileToRemote)

Pass the absolute path of the local file; the callbacks are progress, success, and failure. You pass only the local path, but Pilot stores the file using the file name (without directory) as the server-side unique identifier, and later capabilities reference the resource by that file name:

val fileManager = FileTransferManager.getInstance()             // get the manager singleton

val filePath = "/sdcard/Android/data/<your_pkg>/files/star_max.svg"   // TODO: replace with your local file's absolute path

fileManager.pushFileToRemote(filePath, object : CommonCallbacks.CompletionCallbackWithProgress<Double> {
    override fun onProgressUpdate(progress: Double) {
        // upload progress, 0.0 to 100.0 (percent)
    }
    override fun onSuccess() {
        // upload complete; you can now reference the resource by the file name "star_max.svg"
    }
    override fun onFailure(error: IDJIError) {
        // get the code via error.errorCode()
    }
})

The server has three storage rules:

  • Isolated by plugin package name: each plugin's files live in a separate directory, invisible to others.
  • Same-name overwrite: uploading a file with the same name deletes the old one first, then writes the new one, so re-uploading the same file name is an update.
  • Progress guarantees only start/end: progress goes from 0.0 to 100.0; if the file size cannot be obtained, no intermediate progress is reported, so use onSuccess as the completion signal.

Caution:

  1. Uploads are serial—the server processes only one upload at a time. Starting a new one before the previous finishes immediately returns UPLOAD_FILE_BUSY. Start the next upload only after the previous upload's onSuccess / onFailure, or queue them serially on your side.
  2. When the plugin is uninstalled, the files it uploaded through pushFileToRemote are deleted.

2.2 Query the Uploaded File List (queryFileListFromRemote)

Query all file names this plugin has uploaded to Pilot; use it to deduplicate before upload or to verify that resources are ready:

fileManager.queryFileListFromRemote(object : CommonCallbacks.CompletionCallbackWithParam<List<String>> {
    override fun onSuccess(fileList: List<String>) {
        // fileList is a list of file names, e.g., ["star_max.svg", "star_min.svg"]
        val alreadyUploaded = fileList.contains("star_max.svg")
    }
    override fun onFailure(error: IDJIError) {
        // get the code via error.errorCode()
    }
})

It returns only the file names in this plugin's directory; if the server directory does not exist, it returns an empty list (not a failure).


3. API Reference

For the full definitions of these interface methods, see the API documentation: IFileTransferManageropen in new window.

IFileTransferManager is the entry point of the server-side file transfer interface, exposing the following methods:

ItemDescription
IFileTransferManagerEntry point of the file transfer interface
pushFileToRemoteUpload a local file to Pilot, with a progress callback
queryFileListFromRemoteQuery the list of file names this plugin has uploaded

4. Sample Source Code

File Transfer Sampleopen in new window


5. FAQ

Q1: pushFileToRemote fails immediately with FILE_NOT_EXIST / EXECUTION_FAILED?

These are local checks before upload failing. Troubleshoot in this order:

  1. FILE_NOT_EXIST: the file at the given path does not exist; check the absolute path.
  2. EXECUTION_FAILED (not a file): you passed a directory, not a file; pushFileToRemote uploads a single file at a time.
  3. EXECUTION_FAILED (not readable): the file has no read permission; ensure the app has storage permission and the file is readable.

Q2: Concurrent uploads return UPLOAD_FILE_BUSY?

The server processes only one upload at a time. Starting a new one before the previous finishes returns UPLOAD_FILE_BUSY immediately. The correct approach: start the next upload only after the previous upload's onSuccess / onFailure; for batch uploads, queue serially on your side rather than calling concurrently.

Q3: Does uploading a file with the same name duplicate or overwrite it?

Overwrite. The server uses the file name as the unique identifier and deletes the old same-name file before writing. So to "update a resource," re-upload with the same file name—no need to delete first.

Q4: onProgressUpdate has no intermediate progress and jumps straight to 100?

When the server cannot obtain the file size, it does not report intermediate percentages, guaranteeing only the start 0.0 and end 100.0. This is normal—use onSuccess as the completion signal rather than relying on intermediate progress for business logic.

Q5: pushFileToRemote takes a path, but queryFileListFromRemote returns file names—how do they correspond?

On upload you pass a local absolute path, but the server stores only the file name from it; the query returns those file names. So all later capabilities (AR icons, marker icons, etc.) reference the resource by file name, independent of the local path.

Appendix: Error Code Quick Reference

The error codes below come from dji.open.pilot.base.error.RemoteError:

Error code constantTriggerSuggested handling
REMOTE_DISCONNECTEDCalled before the connection is readyRetry after the connection state is CONNECTED
FILE_NOT_EXISTThe local file to upload does not existCheck the absolute path; see Q1
EXECUTION_FAILEDPath is not a file / not readable / transfer errorEnsure a single readable file; see Q1
UPLOAD_FILE_BUSYAn upload task is already in progressQueue serially and wait for the previous upload; see Q2
Last Updated: