OTA with 4G/3G/GPRS/WiFi via FTP
Last updated
Last updated
It is possible to update the Waspmote\'s program using Over The Air Programming and the following modules: 4G, 3G, GPRS or WiFi module.
The Waspmote reprogramming is done using an FTP server and an FTP client which is Waspmote itself. The FTP server can be configured by Meshlium. Otherwise, the user will have to setup an FTP server with the settings described in this guide.
There are two basic steps involved in OTA procedure:
Step 1: Waspmote requests a special text file which gives information about the program to update: program name, version, size, etc.
Step 2: If the information given is correct, Waspmote queries the FTP server for a new program binary file and it updates its flash memory in order to run the new program.
The FTP server that Waspmote connects to needs a specific configuration so as to OTA work properly. There are two ways to set up the FTP server:
Extern user\'s FTP server
Meshlium FTP server
There is a special text file called UPGRADE.TXT which defines several fields. This file must be located in the FTP Server root directory. Each field is defined by a specific label as shown below. Each line of the text file must end with the corresponding line end character: \'\n\'.
There are labels defined for each parameter:
FILE: identifies the name of the binary to be downloaded (it is a 7-character name).
PATH: identifies the path inside the FTP server where the file is found.
SIZE: identifies the size of the binary file. It must be written as the number of bytes.
VERSION: identifies the program version. It must be defined as a 1-unsigned-byte number (range: from 0 to 255). This label must be used by the user so as to validate new program versions when the file name specified in FILE does not change. Thus, Waspmote will know if the same program has changed its version and if it is necessary to download it or not.
There is a restriction regarding the filename: it must be defined by 7 characters given by the Waspmote IDE when it generates the binary file. It is important not to change the file name. If no OTA file needs to be downloaded, then the FILE field must be filled with "NO_FILE" pattern. Thus, Waspmote will know that no downloading process is required. If no UPGRADE.TXT file is found in the FTP server, the OTA process will be called off as well.
Example 1: No binary file has to be downloaded
Example 2: Filename and Path specified in the text file. Notice that no \'/\' character appears at the end of the path.
Example 3: Filename and FTP Server\'s Root Directory are specified in the text file. Notice that root directory is specified as a unique \'/\' character.
During Waspmote program execution, several cases can occur when the mote requests OTA via 4G/3G/GPRS/WiFi module:
If there is no UPGRADE.TXT file or it is not found, Waspmote will not perform any OTA process and will carry on with the current program.
If there is an UPGRADE.TXT file and NO_FILE is specified as filename, then Waspmote will carry on with the current program.
If every label is correctly defined, Waspmote will attempt to download and update the new program automatically.
The other possibility is to setup the FTP server using Meshlium.
Meshlium works as the Gateway of the Waspmote Sensor Networks. It reads the sensor frames coming from the nodes and store them in its internal data base and in external cloud systems located on the Internet.
The Manager System is a web interface which comes with Meshlium. It allows you to control all the interfaces and system options in a secure, easy and quick way. For more information: https://development.libelium.com/meshlium/
There is a plug-in for Meshlium\'s Manager System which permits to set up the FTP server automatically. Thus, it is easier to prepare the binary files to be downloaded by Waspmote. This plug-in is already installed in Manager System version 3.0.7 or more. Please check the Technical Guide in order to update the Manager System to its last version.
OTA via GPRS, 3G or WiFi is supported by Meshlium Xtreme. If you have a previous version, you need to upgrade it; please contact the Sales Department for more information: https://www.libelium.com/contact/
Besides, a default user is configured in Meshlium FTP Server with the following settings:
user: ota
password: libelium
This user directly connects to the following path in Meshlium\'s system directory where the application creates all the binary and UPGRADE.TXT files: /mnt/user/ota
The OTA-FTP application can be found inside the Manager System → Sensor Networks → OTA-FTP
Firstly, there are three possibilities to be chosen:
Select NO_FILE to inform Waspmote that no OTA is necessary.
Select a new file generated by Waspmote-IDE so as to update the Waspmote\'s program.
Select a existing binary if the user needs to update to an older program. The files are stored in the following path: /mnt/user/ota.
Secondly, the program version is always set by the user before generating the new UPGRADE.TXT file. There is a specific input to indicate the program version. It must be defined as a 1-unsigned-byte number (range: from 0 to 255).
Finally, there is a button to generate the new UPGRADE.TXT file.
Once these steps have been followed, the binary file and the proper UPGRADE.TXT file are ready for the Waspmote devices deployed which try to perform OTA via FTP transmission. This file is shown in the last window of the application representing the actual binary prepared for OTA.
Every Waspmote sketch which provides OTA via FTP must have the following appearance:
Step by step:
Step 1: The first checking is done by calling a specific function defined in Utilities library. This function must be called at the beginning of the code. This function returns three possible values. This allows the user to perform an action when a reprogramming has taken place.
Returns
0: Reprogramming error
1: Reprogramming OK
2: Normal starting (no OTA process)
Step 2: The user must fill this point with the code which is executed just once.
Step 3: The user must fill this point with the code which is executed every loop repeatedly.
Step 4: The OTA request function depends on the module used. This function should be called when the user considers it so as to keep battery, i.e. once a day or once a week.
When using a GPRS module, Waspmote connects to the nearest Mobile Cell and follows the OTA procedure.
The GPRS_Pro and GPRS+GPS libraries implement the request function indicating four input parameters: FTP address, port, user and password. So a function example for GPRS_Pro is:
This function returns an int8_t variable which indicates the error found:
1: if success
-2 if error
-4 if error setting the type of Internet connection
-5 if error setting the apn
-6 if error setting the user name
-7 if error setting the password
-8 if error saving the configuration
-9 if error opening connection with the GPRS provider
-10 error downloading OTA version file
-11 if error getting the IP address
-12: if error setting the FTP/HTTP ID (-50 if CME error available)
-13: if error setting the FTP mode (-51 if CME error available)
-14: if error setting the FTP type (-52 if CME error available)
-15: if error setting the FTP server (-53 if CME error available)
-16: if error setting the FTP port (-54 if CME error available)
-17: if error setting the user name (-55 if CME error available)
-18: if error setting the password (-56 if CME error available)
-21: if error setting the file name in the FTP server (-57 if CME error available)
-22: if error setting the path of the file in the FTP server (-58 if CME error available)
-23: if error opening the FTP session (-59 if CME error available)
-24: if error starting the SD
-25: if error creating the file
-26: error requesting data to the FTP (-60 if CME error available)
-27: if error saving data into the SD
-28: if error requesting more data to the FTP (-61 if CME error available)
-30: setting the file name in the FTP to get the file size (-62 if CME error available)
-31: setting the path in the FTP to get the file size (-63 if CME error available)
-32: if error getting the file size (-64 if CME error available)
-65: if FTP is busy
-66: if there isn\'t FILE tag
-67: if there isn\'t PATH tag
-68: if there isn\'t VERSION tag
-69: if OTA is not necessary
-70: if OTA files are the same program version
-71: if error opening connection with the GPRS provider
-72: error downloading OTA file
-73: if error getting the IP address
-74: if error setting the FTP/HTTP ID (-112 if CME error available)
-75: if error setting the FTP mode (-113 if CME error available)
-76: if error setting the FTP type (-114 if CME error available)
-77: if error setting the FTP server (-115 if CME error available)
-78: if error setting the FTP port (-116 if CME error available)
-79: if error setting the user name (-117 if CME error available)
-80: if error setting the password (-118 if CME error available)
-83: if error setting the file name in the FTP server (-119 if CME error available)
-84: if error setting the path of the file in the FTP server (-120 if CME error available)
-85: if error opening the FTP session (-121 if CME error available)
-86: if error starting the SD
-87: if error creating the file
-88: error requesting data to the FTP (-122 if CME error available)
-89: if error saving data into the SD
-90: if error requesting more data to the FTP (-123 if CME error available)
-92: setting the file name in the FTP to get the file size (-124 if CME error available)
-93: setting the path in the FTP to get the file size (-125 if CME error available)
-94: if error getting the file size (-126 if CME error available)
-127: if FTP is busy
Before calling the request function, it is necessary to switch on the GPRS module and connect to a GPRS network.
The following example shows how to perform OTA via GPRS_Pro module. Keep in mind that the user has to change the APN settings to their own (constants AT_GPRS_APN, AT_GPRS_LOGIN and AT_GPRS_PASSW into the file "WaspGPRS_Pro_core.h") and must keep the OTA_FUSE with \'1\':
http://www. https://development.libelium.com/gprs-24-ota
*Note: It is absolutely necessary to use the proper firmware in the GPRS module so as to perform the OTA process. The correct firmware version is 1137B01SIM900M64_ST_ENHANCE. You can check the firmware version executing the following example:*
https://development.libelium.com/gprs-22-getting-imsi-from-sim-and-imei
*Note: It is absolutely necessary to use the proper firmware in the GPRS+GPS module so as to perform the OTA process. The correct firmware version is 1137B03SIM908M64_ST_ENHANCE . You can check the firmware version executing the following example:*
https://development.libelium.com/gprs-sim908-22-getting-imsi-from-sim-and-imei
*NOTE: In the case you want to upgrade the firmware to a valid version, please ask Libelium Sales Department (sales@libelium.com) for more information.
When using the 3G module, Waspmote connects to the nearest Mobile Cell and follows the OTA procedure.
The 3G library implements the request function indicating four input parameters: FTP address, port, user and password. So a function example is:
This function returns an int8_t variable which indicates the error found:
1: on success
-2: if error setting the connection parameters (APN)
-3: if error setting the FTP server (\'-13\' if CME error available)
-4: if error setting the FTP port (\'-14\' if CME error available)
-5: if error setting the FTP mode (\'-15\' if CME error available)
-6: if error setting the FTP type (\'-16\' if CME error available)
-7: if error setting the user name (\'-17\' if CME error available)
-8: if error setting the FTP password (\'-18\' if CME error available)
-19: if error downloading the OTA version file
-21: if error with CME code (FTP error) downloading the OTA version file
-22: if error sending the OTA version file from 3G module to Waspmote\'s SD
-23: if there isn\'t FILE tag
-24: if there isn\'t PATH tag
-25: if there isn\'t VERSION tag
-26: if OTA is not necessary
-27: if OTA files are the same program version
-28: if error downloading the OTA file
-31: if error with CME code (FTP error) downloading the OTA file
-32: if error sending the OTA file from 3G module to Waspmote\'s SD
Before calling the request function, it is necessary to switch on the 3G module and connect to a 3G or GPRS network.
The following example shows how to perform OTA via 3G module. Keep in mind that the user has to change the APN settings to their own (constants _3G_APN, _3G_LOGIN and _3G_PASSW into the file "Wasp3G.cpp") and must keep the OTA_FUSE with \'1\':
https://development.libelium.com/3g-32-ota
When using the 4G module, Waspmote connects to the nearest Mobile Cell and follows the OTA procedure.
The 4G library implements the request function indicating four input parameters: FTP address, port, user and password. So a function example is:
This function returns a uint8_t variable which indicates the error found:
1: SD not present
2: error downloading UPGRADE.TXT
3: error opening FTP session
4: filename is different to 7 bytes
5: no \'FILE\' pattern found
6: \'NO_FILE\' is the filename
7: no \'PATH\' pattern found
8: no \'SIZE\' pattern found
9: no \'VERSION\' pattern found
10: invalid program version number
11: file size does not match in UPGRADE.TXT and server
12: error downloading binary file: server file size is zero
13: error downloading binary file: reading the file size
14: error downloading binary file: SD not present
15: error downloading binary file: error creating the file in SD
16: error downloading binary file: error opening the file
17: error downloading binary file: error setting the pointer of the file
18: error downloading binary file: error opening the GET connection
19: error downloading binary file: error module returns error code after requesting data
20: error downloading binary file: error getting packet size
21: error downloading binary file: packet size mismatch
22: error downloading binary file: error writing SD
23: error downloading binary file: no more retries getting data
24: error downloading binary file: size mismatch
Before calling the request function, it is necessary to switch on the 4G module and connect to a 4G network.
The following example shows how to perform OTA via 4G module. Keep in mind that the user has to change the APN settings to their own so there are some variables at the beginning of the code to be filled:
https://development.libelium.com/4g-20-ota/
The WiFi PRO V3 module does not support the OTA feature. It is the old WiFi PRO module the one that supports it.
When using the WiFi module, Waspmote connects to the Access Point set up by the user and follows the OTA procedure.
Note: Be aware of the decrease in success percentage depending on the devices the user sets up in a WiFi network working together.
The requestOTA() function permits to open the FTP session to the desired FTP server and request the new binary. This function needs four input parameters:
server: IP address or URL of the FTP server
port: port number (21 is default port number for FTP)
user: user for opening the FTP session
password: password needed for opening the FTP session
Example:
This function returns \'1\' in case of error. There is an error code variable called _errorCode, which permits to know what kind of error happened. The possibilities are:
ERROR_CODE_0010: SD not present
ERROR_CODE_0021: error downloading UPGRADE.TXT
ERROR_CODE_0022: filename in UPGRADE.TXT is not a 7-byte name
ERROR_CODE_0023: no FILE label is found in UPGRADE.TXT
ERROR_CODE_0024: NO_FILE is defined as FILE in UPGRADE.TXT
ERROR_CODE_0025: no PATH label is found in UPGRADE.TXT
ERROR_CODE_0026: no SIZE label is found in UPGRADE.TXT
ERROR_CODE_0027: no VERSION label is found in UPGRADE.TXT
ERROR_CODE_0028: version indicated in UPGRADE.TXT is lower/equal to Waspmote\'s version
ERROR_CODE_0029: file size does not match the indicated in UPGRADE.TXT
ERROR_CODE_0030: error downloading binary file
Before calling the request function, it is necessary to switch on the WiFi module and join a network.
The following example shows how to perform OTA via WiFi module. Keep in mind that the user has to change the AP settings to their own. Besides, the FTP server settings must be changed in the case an extern FTP server is used. If not, the default Meshlium\'s parameters are set, but the Meshlium\'s network address must be specified as the real one:
