page_type	languages	products	name	urlFragment	extendedZipContent	description
sample	c	azure azure-sphere	Azure Sphere – HTTPS cURL Multi	HTTPS-cURL-Multi	path target HardwareDefinitions HardwareDefinitions path target .clang-format .clang-format path target BUILD_INSTRUCTIONS.md BUILD_INSTRUCTIONS.md path target Samples/SECURITY.md SECURITY.md path target Samples/troubleshooting.md troubleshooting.md	Demonstrates how to use the cURL Multi interface with Azure Sphere over a secure HTTPS connection.

Sample: HTTPS cURL Multi

This sample demonstrates how to use the cURL Multi interface with Azure Sphere over a secure HTTPS connection. For details about using the libcurl library with Azure Sphere, see Connect to web services using cURL.

By default, this sample uses the proxy configured for the device. The sample downloads multiple web pages concurrently by using the cURL Multi interface. The content is output as soon as it arrives. Pressing button A on the MT3620 development board initiates the web transfers. After the sample validates the server identity, communication occurs over HTTP or HTTPS. At the same time, LED1 blinks at a constant rate, demonstrating that the cURL Multi interface is non-blocking.

The sample uses the following Azure Sphere libraries.

Library	Purpose
curl	Configures the data transfer and downloads the web page over HTTP/HTTPS.
eventloop	Invokes handlers for timer events.
gpio	Enables digital input for button A.
log	Displays messages in the Device Output window during debugging.
networking	Gets and sets network interface configuration.
storage	Gets the path to the certificate file that is used to authenticate the server.

Contents

File/folder	Description
app_manifest.json	Application manifest file, which describes the resources.
CMakeLists.txt	CMake configuration file, which Contains the project information and is required for all builds.
CMakePresets.json	CMake presets file, which contains the information to configure the CMake project.
launch.vs.json	JSON file that tells Visual Studio how to deploy and debug the application.
LICENSE.txt	The license for this sample application.
main.c	Main C source code file.
README.md	This README file.
.vscode	Folder containing the JSON files that configure Visual Studio Code for deploying and debugging the application.
HardwareDefinitions	Folder containing the hardware definition files for various Azure Sphere boards.

Prerequisites

The sample requires the following hardware:

• An Azure Sphere development board that supports the Sample Appliance hardware requirements.

  Note: By default, the sample targets the Reference Development Board design, which is implemented by the Seeed Studios MT3620 Development Board. To build the sample for different Azure Sphere hardware, change the value of the TARGET_HARDWARE variable in the CMakeLists.txt file. For detailed instructions, see the Hardware Definitions README file.

Setup

Complete the following steps to set up this sample.

1. Ensure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.

2. Ensure that you have Azure Sphere SDK version 24.03 or above. At the command prompt, run az sphere show-sdk-version to check. Upgrade the Azure Sphere SDK for Windows or Linux as needed.

3. Ensure that the Azure CLI is installed. At a minimum, the Azure CLI version must be 2.45.0 or later.

4. Install the Azure Sphere extension.

5. Enable application development, if you have not already done so, by entering the az sphere device enable-development command in the command prompt.

6. Clone the Azure Sphere samples repository and find the HTTPS_Curl_Multi sample in the HTTPS folder or download the zip file from the Microsoft samples browser.

7. Note that the sample can connect only to websites listed in the AllowedConnections capability of the app_manifest.json file. The sample is set up to connect to the website httpstat.us:

   "Capabilities": {
       "AllowedConnections": [ "httpstat.us" ],
     },

   You can revise the sample to connect to a different website for downloading, as described in the Rebuild the sample to download from a different website section of this README.

8. By default, this sample configures the cURL handle to use the proxy. To bypass the proxy, add "--BypassProxy" in the CmdArgs field.

   CmdArgs: [ "--BypassProxy" ],

   For further details see connect through a proxy.

9. Configure networking on your device. You must either set up WiFi or set up Ethernet on your development board, depending on the type of network connection you are using.

Configure a static IP address

You can configure a static IP address on an Ethernet or a Wi-Fi interface. If you have configured a device with a static IP and require name resolution, your application must set a static DNS address. For more information, see the sections Static IP address and Static DNS address in Use network services.

Best practice when using libcurl

When using libcurl, as with other networking applications, the Azure Sphere OS will allocate socket buffers which are attributed to your application's RAM usage. You can tune the size of these buffers to reduce the RAM footprint of your application as appropriate. Refer to Manage RAM usage for further details.

Make libcurl verbose

When developing and debugging libcurl, you can configure libcurl to display verbose information about its operations on the cURL handle. To make this sample display verbose information, search for the following line in web_client.c

if ((res = curl_easy_setopt(easyHandle, CURLOPT_VERBOSE, 0)) != CURLE_OK) {

and change it to:

if ((res = curl_easy_setopt(easyHandle, CURLOPT_VERBOSE, 1L)) != CURLE_OK) {

Build and run the sample

To build and run this sample, follow the instructions in Build a sample application.

To start the download, press button A on the board. The sample downloads status information for HTTP statuses 200 (success) and 400 (bad request) from the httpstat.us website.

Rebuild the sample to download from a different website

To download data from a website other than the default website, you'll need to get the root CA certificate from the website, modify the sample to use the new website and its certificate, and build and run the modified sample.

Complete the steps described in the following sections.

Download the root CA certificate

If the website uses SSL, you may need to use a different root CA certificate. To download the certificate from the website, complete the following steps:

1. Open the browser and click the Secure icon, which is a padlock in the address bar.

2. If you're using Microsoft Edge, select Connection is secure; then click the certificate icon (highlighted yellow):

   

3. Select Certificate.

4. Open the Certification Path tab.

5. Select the top certificate in the hierarchy and then select View Certificate.

6. Open the Details tab and select Copy to File.

7. In the Certificate Export Wizard, click Next.

8. Select the Base-64 encoded X.509 (.CER) format and then click Next.

9. Type the file name to which to export the certificate and then click Next.

10. Click Finish to complete the wizard.

11. Rename the downloaded certificate file to have the .pem extension.

Modify the sample to use the new website

Complete the following steps to modify the sample to use the new website.

1. In the app_manifest.json file, add the hostname of the new website to the AllowedConnections capability. For example, the following adds Contoso.com to the list of allowed websites.

   "Capabilities": {
       "AllowedConnections": [ "httpstat.us", "Contoso.com"],
     },

2. Open web_client.c. Find the following code and change https://httpstat.us/200?sleep=5000 and https://httpstat.us/400?sleep=1000 to the URLs of the website you want to connect to.

   // The web transfers executed with cURL.
   WebTransfer webTransfers[] = {
               // Download a web page with a delay of 5 seconds with status 200.
               {.url = "https://httpstat.us/200?sleep=5000", .easyHandle = NULL},
               // Download a web page with a delay of 1 second with status 400.
               {.url = "https://httpstat.us/400?sleep=1000", .easyHandle = NULL}};

3. Update the sample to use a different root CA certificate, if necessary:

   1. Put the trusted root CA certificate in the certs/ folder (and optionally remove the existing bundle.pem certificate).
   2. Update line 16 of CMakeLists.txt to include the new trusted root CA certificate in the image package, instead of the bundle.pem certificate.
   3. Update line 195 of web_client.c to point to the new trusted root CA certificate.

Build and run the sample modified to use the new website

To build and run the modified sample, follow the instructions in the Build and run the sample section of this README.

Next steps

• For an overview of Azure Sphere, see What is Azure Sphere.
• To learn more about Azure Sphere application development, see Overview of Azure Sphere applications.
• For network troubleshooting, see Troubleshoot network problems.