Image and File Upload

Image and File Upload allows devices to send images, documents, and other files to /IOTCONNECT™. Once uploaded, the device publishes the file location along with optional classification data through the device’s file upload MQTT topic.

What is D2C Image and File Upload?

Telemetry tells you what your sensors measured. Image and File Upload adds the file itself: a camera frame, an inspection photo, a log or a report. The device calls one SDK method, and the SDK stores the file in secure storage and tells /IOTCONNECT™ where it is.

Vision and AI at the edge: upload a captured image together with the classification your model produced, such as defect or good, plus a confidence score.

Camera capture: send a frame straight from memory (for example an OpenCV JPEG buffer) without writing it to disk first.

Documents and data files: upload PDFs, archives, JSON, CSV, text or log files from the device.

Prerequisites

File Support enabled on the device template. This is what makes the sync response include the file upload configuration (p.fs) and the file upload topic (p.topics.fu). See the next section.

Certificate-based (X.509) device authentication. The SDK only creates its file upload client when the device is configured with a certificate (SSLKeyPath, SSLCertPath, SSLCaPath). It uses the same certificate to request AWS credentials.

The /IOTCONNECT™ Python SDK with file upload support. The feature is in the iotc-python-sdk repository on the std-21-kinesis-video-stream branch. It needs no new Python packages; it uses requests and the standard library.

A connected, started device. Both upload methods return an error if the SDK has not finished starting, because they publish to MQTT after the upload.

For a customer account bucket (ca = true): the bucket entry must include a role ARN (rarn) that the device’s credentials are allowed to assume, and the bucket policy must allow the upload.

Enable File Support in the Device Template

File upload is switched on per device template, following the usual /IOTCONNECT™ template-then-device pattern, so every device created from the template gets it.

1. Open the template: in the /IOTCONNECT™ portal, go to the device template your device uses (or create a new one).

2. Turn on File Support for the template and save it.

3. Use certificate authentication: make sure devices on this template authenticate with X.509 certificates, because file upload is not available with other authentication types.

4. Restart the device application: the SDK reads the file upload configuration during its sync, so start (or restart) the device so it syncs with the updated template.

5. Check that it worked: on start-up the SDK prints File_Upload_Task : File upload configuration found and then File_Upload_Task : File upload client initialized successfully. If you don’t see these lines, the sync response did not include p.fs.

How It Works

Here is what happens from the moment the device connects to the moment your upload call returns:

1. Sync: the device connects and makes its sync (identity) call.

2. Configuration: because File Support is on, the response includes p.fs (the bucket list and the credential provider URL) and p.topics.fu (the file upload MQTT topic).

3. Client ready: the SDK creates its file upload client using the device certificate.

4. Your app uploads: you call UploadImage() or UploadImageWithClassification() with a file path, bytes or a base64 string.

5. Temporary credentials: the SDK calls the credential provider URL with the device’s X.509 certificate and receives short-lived AWS credentials. No permanent AWS keys are stored on the device.

6. Cross-account role (customer bucket only): if the bucket has ca: true, the SDK calls AWS STS AssumeRole with the bucket’s rarn.

7. Upload: the SDK uploads the file to S3 over HTTPS using the S3 REST API and AWS Signature Version 4, under device-uploads/{UniqueId}/{YYYY}/{MM}/{DD}/{GUID}-{filename}.

8. Publish: the SDK publishes a message with the file’s short URL (and any classification data) on the p.topics.fu topic.

9. Result: the method returns a dictionary telling you whether the upload succeeded, where the file is, and whether the MQTT message was published.

File Upload Configuration in the Sync Response

When File Support is enabled, the sync response carries the bucket list and credential URL under p.fs, and the upload topic under p.topics.fu. The SDK reads these automatically; you don’t pass them yourself.

SDK Methods

The SDK adds two methods to the IoTConnectSDK object. Each accepts either a file path, or a stream plus a file name.

Method	What it does
`UploadImage(file_path=None, file_stream=None, file_name=None)`	Uploads the file to S3, then publishes the file URL on the file upload topic with an empty `cf` object.
`UploadImageWithClassification(file_path=None, file_stream=None, file_name=None, classification=None, custom_attributes=None)`	Uploads the file to S3, then publishes the file URL together with your classification result and any custom attributes in `cf`.

Parameters

Parameter	Type	Description
`file_path`	str	Path to the file on disk. The file name stored in S3 is taken from the path.
`file_stream`	bytes or str	File content in memory. Pass `bytes` for raw data, or a `str` for base64-encoded data (the SDK decodes it).
`file_name`	str	Required when you use `file_stream`. Its extension sets the content type.
`classification`	str	Only for `UploadImageWithClassification`. Your result, such as `"defect"` or `"good"`. Optional.
`custom_attributes`	dict	Only for `UploadImageWithClassification`. Extra key/value pairs added to the published message. Optional.

Pass either file_path, or file_stream and file_name. If neither is provided, the method returns an error.

UploadImage

Upload a file from disk, from bytes, or from a base64 string. Always check result[“success”] before relying on the upload.

UploadImageWithClassification

Upload a file and publish your classification result and custom attributes with it, for example the output of an image classification model.

Upload Result

Both methods return a dictionary. They never raise for upload problems; check success and read error instead.

Key	Type	Description
`success`	bool	True when the file was uploaded to S3.
`s3_key`	str	Full S3 object key, for example `device-uploads/device-id/2025/11/04/guid-image.jpg`.
`bucket`	str	Name of the S3 bucket the file was uploaded to.
`url`	str	Short path published over MQTT: `{YYYY}/{MM}/{DD}/{GUID}-{filename}`.
`mqtt_published`	bool	True when the file upload message was published to `p.topics.fu`.
`error`	str	Error message when something failed; `None` on success.

A result can have success set to true and mqtt_published set to false: the file is in S3, but the platform was not notified. Check both values when the notification matters.

MQTT Message Format

After a successful upload, the SDK publishes on the p.topics.fu topic from the sync response (for example $aws/rules/msg_d2c_file/{DeviceId}/2.1/11). The payload below is built by the SDK; you don’t publish it yourself.

Complete Example

A full device application: connect with certificate authentication, upload an image with a classification, check the result, and dispose of the SDK.

Test with the SDK Sample

The sample sample/iotconnect-sdk-1.0-firmware-python_msg-2_1.py in the SDK repository includes a testFileUpload(sdk) function that runs four tests:

Test	Method	Needs
1	`UploadImage(file_path)`	`test_image.jpg` in the sample folder
2	`UploadImageWithClassification(file_path, ...)`	`test_image.jpg` in the sample folder
3	`UploadImage(file_stream, file_name)`	Nothing; creates a text file in memory
4	`UploadImageWithClassification(file_stream, ...)`	Nothing; rotates classifications defect, good, anomaly, normal

1. Enable the test: set test_file_upload = True in the sample.

2. Add a test image (optional): copy any JPG into the sample folder as test_image.jpg. Tests 3 and 4 run without it.

3. Run the sample: python sample/iotconnect-sdk-1.0-firmware-python_msg-2_1.py. The tests run once when the SDK is ready, then normal telemetry continues.

4. Run it periodically (optional): uncomment the block if test_file_upload and loop_counter % 5 == 0: in the main loop to repeat the tests every 5 telemetry loops (about every 50 seconds).

Verify the results

Console: each test prints Upload Success! with the S3 key, bucket and URL, and MQTT Published: True for the classification tests.

S3: list the device folder, for example aws s3 ls s3://your-bucket-name/device-uploads/your-device-id/ --recursive.

/IOTCONNECT™ portal: open the device and check Live Data for the file upload messages.

Limitations

Certificate authentication only. Devices without an X.509
certificate configuration don’t get a file upload client.

No offline queue. The device must be online and started;
uploads are not queued for later.

Single request upload. Each file is sent in one S3
request with a 5-minute timeout. Multipart upload and upload progress
callbacks are not available.

Recommended size: keep files reasonably small; under 10
MB is recommended.

Region. The current implementation signs S3 and STS
requests for the
us-east-1 region.

Troubleshooting

Problem	Likely cause	What to do
File upload client not initialized	The sync response has no `p.fs`, or the device is not using certificate authentication.	Enable File Support on the device template, restart the device, and confirm the certificate paths in the SDK options. With `"IsDebug": True`, check the sync response and the File_Upload_Task log lines.
Device not started	The upload was called before the SDK finished connecting and syncing.	Wait until the device is connected and ready, then upload.
File not found	The `file_path` does not exist on the device.	Check the path. For the sample tests, copy an image to `test_image.jpg`.
Either file_path or (file_stream + file_name) must be provided	A stream was passed without a file name, or nothing was passed.	Pass `file_name` whenever you pass `file_stream`.
Failed to get IoT credentials	The credential provider rejected the request or could not be reached.	Check the certificate paths, that the certificates are not expired, the credential URL in the sync response, and network access.
Role ARN (rarn) not found or STS AssumeRole failed	Customer bucket (`ca: true`) without a usable role.	Review the cross-account role configuration for the bucket.
S3 upload failed: HTTP 403	Permission denied on the bucket.	Check the bucket permissions and IAM policies, and the cross-account role if `ca: true`.
mqtt_published is False	The device is not connected to MQTT, or `p.topics.fu` is missing.	Check the MQTT connection and that the sync response includes `p.topics.fu`. The file is still in S3.

Best Practices

Check the result: always check result["success"] (and result["mqtt_published"] when the platform must be notified).

Clean up: delete local files after a successful upload to save space on the device.

Rate limit: don’t upload too often; respect your network and storage limits.

Keep files small: under 10 MB is recommended.

Name files clearly: use descriptive file names with timestamps.

Log during development: set "IsDebug": True to see each upload step in the console.

ⓘ NOTE

File upload must be enabled with File Support on the device template, and the device must use X.509 certificate authentication. The device receives its upload configuration (p.fs) and topic (p.topics.fu) in the sync response and requests short-lived AWS credentials with its certificate, so no permanent AWS keys are stored on the device.