solutions
LoRa Basics Modem and LoRa Edge documentation
Component - Reliable Octet Stream Encoding¶
Introduction¶
The Reliable Octet Stream Encoding (ROSE), available as a part of the LoRa Cloud™ Modem & Geolocation Service (MGS), is a fragmentation and reassembly service. ROSE serves two purposes:
Provides a virtual MTU of 254 bytes, regardless of the underlying transport layer.
Protects the data stream against packet loss via forward error correction.
In addition to respecting data privacy, the stream can be encrypted so that the LoRa Cloud™ Modem & Geolocation Service is not able to access the data.
Note
Abstracting the MTU is useful when the LoRa Basics™ Modem is used in the US915 region, where the size of a GNSS scan may exceed the maximum payload length.
Compatibility¶
Prerequisites¶
Common:
The device is connected to its application server.
The application server forwards messages on a configured Device Management FPort (FPort 199 by default) to
mgs.loracloud.com
.
Prerequisites for LoRa Basics™ Modem:
encryptionKey: the key may be personalized
Prerequisites for LoRa Basics™ Modem-E:
encryptionKey: the key used is the AppSKey
Step-by-Step Procedure¶
Initiate the ROSE session with the
StreamInit()
command and the following parameters:Select
plain text
orencrypted
: If encrypted, the stream will not be seen as plain text by the LoRa Cloud™ Modem & Geolocation Service.Select the
FPort
to send the byte stream to.
Submit the records to be transferred to a 512-byte buffer by invoking
SendStreamData()
.Whenever the modem’s internal buffer contains data records, packets are sent autonomously with redundancy and (optionally) with encryption.
Use
StreamStatus()
to query the status of the streaming buffer on the specified FPort. This command returns the following:Pending
: Indicates the number of bytes pending transmission.Free
: Indicates the number of free bytes in the buffer.
When all fragments (including redundancy) are sent, the modem will generate the event
StreamingDone
.Once the stream is reconstructed the LoRa Cloud™ Modem & Geolocation Service will return it in the
UPLINK_RESPONSE
JSON objectstream_records
.
Note
ROSE differs from Large File Upload (LFU) in that it does not generate a downlink when the stream is delivered to the LoRa Cloud™ Modem & Geolocation Service.
The maximum record size sent in one call to
SendStreamData()
is 254 bytes.If the
FPort
value is 0, or is the same as the DM FPort (FPort 199 by default) the modem will encapsulate the streaming fragments in the modem sub-protocol.
Sample Code¶
End Device Application
#include "lr1110_modem_lorawan.h"
// Initialize streaming
lr1110_modem_stream_init(
&context,
0, // Steaming FPort. 0 = transported by modem sub-protocol
LR1110_MODEM_FILE_ENCRYPTION_DISABLE,
);
// Add data to the stream buffer
uint8_t data_to_stream[200] = {0};
lr1110_modem_send_stream_data(
&context,
0, // Same FPort than lr1110_modem_stream_init()
data_to_stream,
200
);
// Streaming starts immediately in background
// Add other data to the stream buffer, even if the first stream is not over
uint8_t other_data_to_stream[150] = {0};
lr1110_modem_send_stream_data(
&context,
0, // Same FPort than lr1110_modem_stream_init()
other_data_to_stream,
150
);
// Get stream status
lr1110_modem_stream_status_t stream_status;
lr1110_modem_stream_status(
&context,
0, // Same FPort than lr1110_modem_stream_init()
&stream_status
);
printf(
"%d bytes pending, %d bytes left\n",
stream_status.pending,
stream_status.free,
);
// Modem event call-back
customer_event_callback_streaming_done( ) {
printf( "Modem streaming buffer is empty\n" );
}
Application Server
Pseudocode to retrieve a stream when the LoRa Cloud Modem & Geolocation Services reassembles it.
# Call the LoRa Cloud™ Modem & Geolocation Service and get the answer to an uplink
res = call_v1_device_send(uplink) # /api/v1/device/send
# Extract stream_records array, if any
if ( res["stream_records"] != None or res["stream_records"] != []):
for stream in res["stream_records"]
printf( f"stream offset: {stream[0]} - data: {stream[1]}" )
Pseudocode to retrieve the last eight (8) streams stored in the LoRa Cloud™ Modem & Geolocation Service from the device_info
API.
# Call the LoRa Cloud™ Modem & Geolocation Service to query device information
res = call_v1_device_info( devEUI ) # /api/v1/device/info
res = res["result"][devEUI]
# Extract stream_records array, if any
if ( res["result"]["uploaded_stream_records"] != None ):
for stream in res["stream_records"]
printf( f"stream offset: {stream.off} - data: {stream.data}" )
In-depth Behavior¶
ROSE fragments should be sent in non-confirmed uplink frames.
A running stream is indicated in the
Stream
flag of the modem’s status.New data records can be added to the buffer at any time during the stream, provided there is enough space available in the buffer.
When the upload stream is finished, and all fragments have been sent, a
StreamingDone
even is generated.The streaming FPort can be changed after a reset or a
streamingDone
event by by callingStreamInit()
again with the new FPort number.
Used by¶
Applications |
References¶
LoRa Basics™ Modem-E API Reference Manual, sections 2.3, 6.42, 6.43, and 6.44.
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