Resolving JavaScript File Download Issues from ESP32 Webserver

Understanding JavaScript File Download Problems with ESP32

Downloading files from a webserver can sometimes be tricky, especially when dealing with microcontrollers like the ESP32. When attempting to download a file using JavaScript, there may be instances where the download works perfectly when accessed directly from the browser but fails when initiated through a script.

In this scenario, the ESP32 is serving a static .CSV file using a PsychicHTTP webserver. The problem arises when the file doesn't download through JavaScript, despite being accessible through a direct HTML link in the browser. This issue can be frustrating, but it's a common one faced when working with embedded systems.

The JavaScript code uses an XMLHttpRequest to request the file from the ESP32, but it doesn’t trigger the download as expected. This article will explore why the direct link works but the JavaScript method doesn’t. It will also provide insights on how to modify the JavaScript using a more modern 'fetch' API to solve this issue.

Furthermore, we'll discuss if changes are needed in the ESP32 code when switching from XMLHttpRequest to the fetch API. By examining these two questions, we’ll uncover the underlying problem and provide solutions for reliable file downloads.

Analyzing JavaScript File Download Methods and Solutions

In the provided examples, the goal was to download a CSV file from an ESP32 web server running PsychicHTTP. The first script utilizes the modern Fetch API, a powerful tool for making HTTP requests in JavaScript. This method simplifies the process by handling promises and is more readable than older techniques like XMLHttpRequest. The fetch request sends a GET request to the ESP32, retrieves the file, and then converts it into a blob format, which is essential for handling binary data like CSV files. A temporary URL is then generated to allow the user to download the file via an anchor tag.

The second script is an alternative using XMLHttpRequest, a more traditional way of making HTTP requests. Although XMLHttpRequest is older, it’s still used in many applications. In this example, the responseType is set to ‘blob’ to handle the binary file being returned by the server. The script listens for the response, and upon a successful return, it dynamically creates an anchor element to trigger the download. This method provides more granular control over the request, but it lacks the simplicity and flexibility of the Fetch API, especially when handling promises.

The third solution is a fallback that doesn’t require JavaScript at all. It uses an HTML anchor tag with the download attribute, allowing users to click on the link and automatically download the file. This is the most basic solution and doesn't require any scripting. However, it’s less flexible, as it doesn't allow you to programmatically handle file downloads or add any conditions or logic before triggering the download.

Each of these solutions addresses a different use case. The Fetch API is the recommended solution for modern applications because of its simplicity and performance. XMLHttpRequest is useful when you need more control over the request and response. Lastly, the HTML-only solution is ideal for static or simple web pages where JavaScript is not needed. By implementing one of these methods, you can ensure reliable file downloads from an ESP32 web server, improving both user experience and functionality.

function downloadFile(url, fileName) {
  fetch(url, { method: 'GET', mode: 'cors' })
    .then(response => {
      if (!response.ok) {
        throw new Error('Network response was not ok');
      }
      return response.blob();
    })
    .then(blob => {
      const aElement = document.createElement('a');
      const objectUrl = URL.createObjectURL(blob);
      aElement.href = objectUrl;
      aElement.download = fileName;
      document.body.appendChild(aElement);
      aElement.click();
      URL.revokeObjectURL(objectUrl);
      document.body.removeChild(aElement);
    })
    .catch(error => console.error('Fetch error:', error));
}
downloadFile('http://192.168.0.136/saveFile', 'sample.csv');

function saveFile() {
  var xhr = new XMLHttpRequest();
  xhr.open('GET', '/saveFile', true);
  xhr.responseType = 'blob';
  xhr.onload = function () {
    if (xhr.status === 200) {
      var blob = xhr.response;
      var aElement = document.createElement('a');
      var url = URL.createObjectURL(blob);
      aElement.href = url;
      aElement.download = 'sample.csv';
      document.body.appendChild(aElement);
      aElement.click();
      URL.revokeObjectURL(url);
      document.body.removeChild(aElement);
    }
  };
  xhr.send();
}

<a href="http://192.168.0.136/saveFile" download="sample.csv">Download CSV</a>

describe('Download File Test', function() {
  it('should successfully download a file using fetch', function(done) {
    const url = 'http://192.168.0.136/saveFile';
    fetch(url, { method: 'GET' })
      .then(response => {
        expect(response.ok).toBe(true);
        return response.blob();
      })
      .then(blob => {
        expect(blob.size).toBeGreaterThan(0);
        done();
      })
      .catch(done.fail);
  });
});

Exploring Differences in JavaScript and HTML File Download Methods

When downloading files via JavaScript, it's important to understand how different methods interact with the browser's security policies. One reason that the direct address bar link works is because the browser can immediately resolve the request and handle the download. However, when attempting this through JavaScript, browsers apply stricter rules, such as requiring correct CORS (Cross-Origin Resource Sharing) settings. Without setting no-cors or cors modes correctly, the download might not occur.

In addition, modern browsers prefer the use of the fetch() API over older methods like XMLHttpRequest, since it provides more control over how responses are handled, especially for blob or file-like objects. It also handles errors more gracefully, making it a more reliable solution for downloading files dynamically. Setting the proper MIME types is another key factor in ensuring that the file is handled correctly by the client.

For applications like downloading from an ESP32, it’s crucial to ensure that the server correctly handles requests and responses, serving the correct MIME types and headers. The Fetch API also allows for better promise handling, which is particularly useful in asynchronous environments like file downloading, ensuring the user experience remains smooth and responsive.