Using embedded files in an HTTP callback

Using embedded files in an HTTP callback

This week, we tell you about a new feature for HTTP callbacks. We have added a new method that enables the use of files located on YoctoHubs in the HTTP callback script.







Note: this post talks about advanced features of Yoctopuce HTTP callbacks. If you have never used this feature, we advise you to start with the following post HTTP callbacks.

The HTTP callback is a specific working mode in which it is the YoctoHub or the VirtualHub that establishes the connection to the Yoctopuce library. Once the communication is established, all the data of all the functions of the modules are sent in one block. The script that uses the Yoctopuce library works on this data and returns the commands that the modules must execute (for example, to switch a relay because the temperature is too low).

The limitation of this working mode is that the script has access only to the data that the YoctoHub sent when the connection was established. That is, the current state of all functions of the connected Yoctopuce modules. However, the files stored in the internal memory of the modules are not transmitted.

To access these files, you must use the addFileToHTTPCallback method of the YModule object. This method sends a message to the YoctoHub so that it adds a file to the list of data that will be sent during the next callback.

For example, the following code is a PHP script of an HTTP callback that uses the content of the myconfig.txt file that is on the flash memory of the YoctoHub. Before calling the download method, you must call the addFileToHTTPCallback method so that the YoctoHub also sends this file.

YAPI::RegisterHub("callback");
$module = YModule::FindModule("hub_logical_name");
$module->addFileToHTTPCallback("myconfig.txt");
$filecontent = $module->download("myconfig.txt");
...



Warning, the addFileToHTTPCallback method only impacts the next execution of the callback. This modification is not permanent. This means that at the very first execution of the callback, the file is not present and that consequently the access to this file returns an error. To come back to the previous example, the call $module->download("myconfig.txt") would return an error on the very first execution. But all subsequent callbacks will work, because the previous execution will have called addFileToHTTPCallback("myconfig.txt").

Note that if we had reversed the last two lines, the code would never work, because the script would crash before it had executed the call to addFileToHTTPCallback.

It is important to take this into account in your application and to design your code so that it correctly handles the cases in which the call to download doesn't work.

For example, the following code correctly handles the error of the download method. In case of an error, the script immediately calls a callback with the triggerCallback method and ends the execution.

YAPI::RegisterHub("callback");
$module = YModule::FindModule("hub_logical_name");
$module->addFileToHTTPCallback("myconfig.txt");
try {
    $filecontent = $module->download("myconfig.txt");
} catch(YAPIException $e){
    print("file is not yet uploaded by the YoctoHub");
    $network->triggerCallback();
    die();
}
...



Some comments


What we have just explained is not completely accurate. If you call the download("myconfig.txt") method without using addFileToHTTPCallback, your callback may work, but not systematically.

This is the reason: when the library tries to access a resource or a file that has not been sent by the YoctoHub, it implicitly calls the addFileToHTTPCallback function to add the file to the list of resources to be uploaded, and then returns an error. On the next callback, the file is sent by the YoctoHub and the call to download works, but the addFileToHTTPCallback method is not called.

In short, without explicitly calling addFileToHTTPCallback, every other callback generates an error. Worse, depending on how you coded your callback and how many files you need, your callback may never work.

That's why we decided to add the addFileToHTTPCallback method that allows you to explicitly control when a file should be uploaded.

Finally, this new feature is available in Yoctopuce libraries since version v1.10.51266 and is compatible with all the versions of the YoctoHubs and the VirtualHub. However, the YoctoHub firmware prior to version v51218 had a bug that prevented the use of this feature on binary files (for example .gif or .png files).

As usual, everything is available on our website and on GitHub.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.