Upload files from your device to the cloud with IoT Hub

This article shows how to use the file upload capabilities of IoT Hub to upload a file to Azure blob storage. The tutorial shows you how to:

  • Securely provide a storage container for uploading a file.

  • Use the Python client to upload a file through your IoT hub.

The Send telemetry from a device to an IoT hub quickstart demonstrates the basic device-to-cloud messaging functionality of IoT Hub. However, in some scenarios you cannot easily map the data your devices send into the relatively small device-to-cloud messages that IoT Hub accepts. When you need to upland files from a device, you can still use the security and reliability of IoT Hub.


IoT Hub Python SDK currently only supports uploading character-based files such as .txt files.

At the end of this tutorial you run the Python console app:

  • FileUpload.py, which uploads a file to storage using the Python Device SDK.


IoT Hub supports many device platforms and languages (including C, .NET, Javascript, Python, and Java) through Azure IoT device SDKs. Refer to the Azure IoT Developer Center for step-by-step instructions on how to connect your device to Azure IoT Hub.

To complete this tutorial, you need the following:

  • Python 2.x or 3.x. Make sure to use the 32-bit or 64-bit installation as required by your setup. When prompted during the installation, make sure to add Python to your platform-specific environment variable. If you are using Python 2.x, you may need to install or upgrade pip, the Python package management system.

  • If you are using Windows OS, then Visual C++ redistributable package to allow the use of native DLLs from Python.

  • An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.

  • An IoT hub in your Azure account, with a device identity for testing the file upload feature.

Associate an Azure Storage account to IoT Hub

Because the simulated device app uploads a file to a blob, you must have an Azure Storage account associated with your IoT hub. When you associate an Azure Storage account with an IoT hub, the IoT hub generates a SAS URI. A device can use this SAS URI to securely upload a file to a blob container. The IoT Hub service and the device SDKs coordinate the process that generates the SAS URI and makes it available to a device to use to upload a file.

Follow the instructions in Configure file uploads using the Azure portal. Make sure that a blob container is associated with your IoT hub and that file notifications are enabled.

Enable File Notifications in portal

Upload a file from a device app

In this section, you create the device app to upload a file to IoT hub.

  1. At your command prompt, run the following command to install the azure-iothub-device-client package:

    pip install azure-iothub-device-client
  2. Using a text editor, create a test file that you will upload to blob storage.


    IoT Hub Python SDK currently only supports uploading character-based files such as .txt files.

  3. Using a text editor, create a FileUpload.py file in your working folder.

  4. Add the following import statements and variables at the start of the FileUpload.py file.

    import time
    import sys
    import iothub_client
    import os
    from iothub_client import IoTHubClient, IoTHubClientError, IoTHubTransportProvider, IoTHubClientResult, IoTHubError
    CONNECTION_STRING = "[Device Connection String]"
    PROTOCOL = IoTHubTransportProvider.HTTP
    PATHTOFILE = "[Full path to file]"
    FILENAME = "[File name for storage]"
  5. In your file, replace [Device Connection String] with the connection string of your IoT hub device. Replace [Full path to file] with the path to the test file that you created, or any file on your device that you want to upload. Replace [File name for storage] with the name that you want to give to your file after it's uploaded to blob storage.

  6. Create a callback for the upload_blob function:

    def blob_upload_conf_callback(result, user_context):
        if str(result) == 'OK':
            print ( "...file uploaded successfully." )
            print ( "...file upload callback returned: " + str(result) )
  7. Add the following code to connect the client and upload the file. Also include the main routine:

    def iothub_file_upload_sample_run():
            print ( "IoT Hub file upload sample, press Ctrl-C to exit" )
            client = IoTHubClient(CONNECTION_STRING, PROTOCOL)
            f = open(PATHTOFILE, "r")
            content = f.read()
            client.upload_blob_async(FILENAME, content, len(content), blob_upload_conf_callback, 0)
            print ( "" )
            print ( "File upload initiated..." )
            while True:
        except IoTHubError as iothub_error:
            print ( "Unexpected error %s from IoTHub" % iothub_error )
        except KeyboardInterrupt:
            print ( "IoTHubClient sample stopped" )
            print ( "generic error" )
    if __name__ == '__main__':
        print ( "Simulating a file upload using the Azure IoT Hub Device SDK for Python" )
        print ( "    Protocol %s" % PROTOCOL )
        print ( "    Connection string=%s" % CONNECTION_STRING )
  8. Save and close the UploadFile.py file.

Run the application

Now you are ready to run the application.

  1. At a command prompt in your working folder, run the following command:

    python FileUpload.py
  2. The following screenshot shows the output from the FileUpload app:

    Output from simulated-device app

  3. You can use the portal to view the uploaded file in the storage container you configured:

    Uploaded file

Next steps

In this tutorial, you learned how to use the file upload capabilities of IoT Hub to simplify file uploads from devices. You can continue to explore IoT hub features and scenarios with the following articles: