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:

1. Provides a virtual MTU of 254 bytes, regardless of the underlying transport layer.

2. 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.

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¶

1. Initiate the ROSE session with the StreamInit() command and the following parameters:

   • Select plain text or encrypted: 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.

2. Submit the records to be transferred to a 512-byte buffer by invoking SendStreamData().

3. Whenever the modem’s internal buffer contains data records, packets are sent autonomously with redundancy and (optionally) with encryption.

4. 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.

5. When all fragments (including redundancy) are sent, the modem will generate the event StreamingDone.

6. Once the stream is reconstructed the LoRa Cloud™ Modem & Geolocation Service will return it in the UPLINK_RESPONSE JSON object stream_records.

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 calling StreamInit() again with the new FPort number.

Used by¶

References¶

• LoRa Basics™ Modem-E API Reference Manual, sections 2.3, 6.42, 6.43, and 6.44.