solutions
LoRa Basics Modem and LoRa Edge documentation
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¶
Initiate the Large File Upload session via the
UploadInit()
command, specifying the following parameters:Select
plain text
orencrypted with the AppSKey
. (The file will be processed as cipher text by the service if it is encrypted).Determine the
FPort
to send the file to.Set the
size
of the file in Bytes.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.
Load the file to be transferred by invoking
UploadData()
with chunk(s) of 255 bytes or less.Launch the file upload with the
UploadStart()
command, providing the expected CRC.In the event of an error, the command will return one of the following codes.
BadSize
: indicates a file size other than that declared withUploadInit()
.BadSig
: indicates that the file integrity could not be verified against the CRC provided.Busy
: indicates that a file upload session is already in progress.
The file upload starts. For details see In-depth Behavior.
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.
Note
The LFU
FPort
is an internal index to the file upload. It differs from the LoRaWANFPort
. All values [0:255] may be used. Data is still transmitted on theDM FPort
(default: 199).To cancel the current file upload session call
UploadInit()
again, using the sameport
but setting thesize
value to0
.
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¶
The Forward Error Correction feature of the Large File Upload service eliminates the need for each fragment to be acknowledged.
If a Large File Upload is being processed, this is indicated in the
Upload
flag of the modem status messages.When the upload stream stops, an
UploadDone
event is generated. This event carries a status byte indicatingSuccess
orTimeout
.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.
Note
If EncryptMode = 1, the file is delivered to the application server encrypted with the AppSKey of the LoRaWAN session. Otherwise, it is transferred as plain text.
Used by¶
Applications |
References¶
LoRa Basics™ Modem-E API Reference Manual, sections 2.3, 6.39, 6.40, and 6.41.
LoRa Basics Modem and LoRa Edge documentation
Table of Contents
- Overview - LoRa Edge™ Asset Management Platform
- Use Case - Basic Asset Tracking
- Use Case - IR Image Upload on Detected Motion
- Scenario - GNSS Assisted Scan
- Scenario - GNSS Autonomous Scan
- Scenario - LoRa Basics™ Wi-Fi Passive Scan
- Scenario - GNSS Scan with ROSE
- Scenario - Wi-Fi Scan with ROSE
- Scenario - LoRa Cloud™ Join Server
- Scenario - Claiming a Device
- Scenario - Unclaiming a Device
- Scenario - Modem-E Initialization
- Scenario - LoRa Basics™ Almanac Update
- Scenario - User Loaded Almanac Update
- Scenario - Intermittent Network
- Component - Clock Synchronization
- Component - Large File Upload
- Component - Reliable Octet Stream Encoding
- Cryptographic Engine
- Glossary
ADDITIONAL RESOURCES - VIDEOS