Component - Large File Upload¶

Introduction¶

The Large File Upload (LFU) service, available as part of the LoRa Cloud™ Modem & Geolocation Services, is a fragmentation and reassembly Modem service that is useful when the device backhaul has a very low-throughput and can’t accept large amounts of data all at one time. It can also handle the variable MTU of LoRaWAN® networks, so it can be used with any adaptive data rate (ADR) strategy.

Once reassembled in the back-end LoRa Cloud™ Modem & Geolocation Services, the large file will be delivered to the application server through an API call. The LFU adds Forward Error Correction to the file to be transferred, which compensates for lost packets.

Compatibility¶

Prerequisites¶

Common:

• The device is connected to its application server, typically over a LoRaWAN network

• The application server forwards messages on a configured Device Management FPort (FPort 199 by default) to mgs.loracloud.com.

Prerequisites for LoRa Basics™ Modem:

• Maximum file size is 8 KB

Prerequisites for LoRa Basics™ Modem-E:

• Maximum file size is 2 KB

Step-by-Step Procedure¶

1. Initiate the Large File Upload session via the UploadInit() command, specifying the following parameters:

   1. Select plain text or encrypted with the AppSKey. (The file will be processed as cipher text by the service if it is encrypted).

   2. Determine the FPort to send the file to.

   3. Set the size of the file in Bytes.

   4. Set a reasonable delay, in seconds, between transmitted frames (in accordance with your connectivity plan). Local duty-cycle restrictions will be enforced by the modem.

2. Load the file to be transferred by invoking UploadData() with chunk(s) of 255 bytes or less.

3. Launch the file upload with the UploadStart() command, providing the expected CRC.

4. In the event of an error, the command will return one of the following codes.

   1. BadSize: indicates a file size other than that declared with UploadInit().

   2. BadSig: indicates that the file integrity could not be verified against the CRC provided.

   3. Busy : indicates that a file upload session is already in progress.

5. The file upload starts. For details see In-depth Behavior.

6. Once the upload completes:

   • The LoRa Cloud™ Modem & Geolocation Services will provide the reassembled file in the UPLINK_RESPONSE JSON object.

   • The modem generates an UploadDone event.

Sample code¶

End-Device Application

#include "lr1110_modem_lorawan.h"

// Initialize file upload
uint8_t data_to_send[300] = {0};
lr1110_modem_upload_init(
      &context,
      0,        // LFU internal port
      LR1110_MODEM_FILE_ENCRYPTION_DISABLE,
      300,      // File size
      5*60      // Delay between fragments (sec)
);

// Send all the data
lr1110_modem_upload_data( &context, data_to_send, 255 );
lr1110_modem_upload_data( &context, data_to_send + 255, 45 );

// Start the upload
uint32_t crc = compute_crc( data_to_send );
lr1110_modem_upload_start( &context, crc );

// Modem event call-back
customer_event_callback_upload_done(  ) {
   printf( "LFU completed\n" );
}

Application Server

Pseudocode to get a file after the LoRa Cloud™ Modem & Geolocation Services reassembles it:

# Call the LoRa Cloud™ Modem & Geolocation Services and get the answer to an uplink
res = call_v1_device_send(uplink)  # /api/v1/device/send

# Extract file array, if any
if ( res["uplink"]["file"] != None ):
   file = res["uplink"]["file"]
   print( f'File port={file["port"]}  -  data: 0x{file["data"]}' )

Pseudocode to get the last eight (8) files stored in the LoRa Cloud™ Modem & Geolocation Services from the device_info API:

# Call the LoRa Cloud™ Modem & Geolocation Services to query device information
res = call_v1_device_info( devEUI )  # /api/v1/device/info
res = res["result"][devEUI]

# Extract file array, if any
if ( res["result"]["file"] != None ):
   for file in res["result"]["uploaded_files"]:
      print( f'File port={file["port"]}  -  data: 0x{file["data"]}' )

Pseudocode to get the last eight (8) files stored in the LoRa Cloud™ Modem & Geolocation Services from the fetch file upload API. This API will also clear the file upload history on the server:

# Call the LoRa Cloud™ Modem & Geolocation Services to query device information
res = call_v1_file_uploads_fetch( devEUI )  # /api/v1/uploads/fetch
res = res["result"][devEUI]

# Extract file array, if any
if ( res["file"] != None ):
   for file in res["result"]["uploaded_files"]:
      print( f'File port={file["port"]}  -  data: 0x{file["data"]}' )

In-depth Behavior¶

1. The Forward Error Correction feature of the Large File Upload service eliminates the need for each fragment to be acknowledged.

2. If a Large File Upload is being processed, this is indicated in the Upload flag of the modem status messages.

3. When the upload stream stops, an UploadDone event is generated. This event carries a status byte indicating Success or Timeout.

4. The Timeout status is issued when twice the number of uplink packets have been sent, which corresponds to a Forward Error Correction algorithm with a Code Rate equal to 1/2; in other words the data is repeated twice.

Used by¶

References¶

• LoRa Basics™ Modem-E API Reference Manual, sections 2.3, 6.39, 6.40, and 6.41.