OTA Streams

In IoT, a stream is a publicly addressable resource that is an abstraction for a list of files that can be transferred to an IoT device. A typical stream contains the following information:

A stream ID that identifies your stream.
A stream description that provides a description of the stream resource.
A stream version that identifies a particular version of the stream. Because stream data can be modified immediately before devices start the data transfer, the stream version can be used by the devices to enforce a consistency check.
A list of files that can be transferred to devices. Each file in the list contains, the stream records a file ID and the file size.

Functionality

Data transfer using the MQTT protocol.
Support for JSON or CBOR formats.
Support for a dynamic block size per request, to support devices that have different memory capacities.

####Describe Stream

DescribeStream request can return the metadata about the streams. The stream data returned includes the stream ID, stream version, stream description and a list of stream files, each of which has a file ID and the file size in bytes.

!!!Note Replace json with cbor in the below topics shown, to receive messages in the CBOR format.

Request Topic	$aws/things/{clientId}/streams/{streamname}/describe/json
Request Payload	```json { "c": "string" } ```

c : (Optional) “c” is the client token field. The client token can’t be longer than 64 bytes. A client token that is longer than 64 bytes causes an error response and an InvalidRequest error message.

Response Topic	$aws/things/{clientId}/streams/{streamname}/description/json
Response Payload	```json { "c": "string", "s": number, "d": "string", "r": [ { "f": number, "z": long }, { "f": number, "z": long } ] } ```

c is the client token field. This is returned if it was given in the DescribeStream request. Use the client token to associate the response with its request.
s is the stream version as an integer.
r contains a list of the files in the stream.
f is the stream file ID as an integer.
z is the stream file size in number of bytes.
d contains the description of the stream.

Response Topic	$aws/things/{clientId}/streams/{streamname}/rejected/json
Response Payload	Error

####Get Stream

Devices can receive stream files in small data blocks using Get Stream request. To receive an entire data file, a device might need to send or receive multiple requests and responses until all data blocks are received and processed.

!!!Note Replace json with cbor in the below topics shown, to receive messages in the CBOR format.

Request Topic $aws/things/{clientId}/streams/{streamname}/get/json

Request Payload

```json { "c": "string", "s": number, "f": number, "l": long, "o": number, "n": number }

</td></tr>
</table>

* **c** [optional] - It refers to the client token field. The client token can be no longer than 64 bytes.
* **s** [optional] - It is the stream version field (an integer).
* **f** - It refers to the stream file ID (an integer in the range 0 to 255).
* **l** - It refers to the data block size in bytes (an integer in the range 256 to 131,072).
* **o** [optional] - is the offset of the block in the stream file (an integer in the range 0 to 98,304).
* **n** [optional] - It is the number of blocks requested (an integer in the range 0 to 98,304).

!!!Note
    * Requests for a block that is more than 128 KB will fail. Request for multiple blocks whose total size is greater than 128 KB is supported (for example, if you make a request for 5 blocks of 32 KB each for a total of 160 KB of data)
    * Either “n” or “b” should be specified. If neither of them is specified, the GetStream request might not be valid when the file size is less than 131072 bytes (128 KB).


<table>
<tr><td><b>Response Topic</b></td><td>$aws/things/{clientId}/streams/{streamname}/data/json</td></tr>
<tr><td><b>Response Payload</b></td><td>
```json
{
    "c": "string",
    "f": number,
    "l": long,
    "i": number,
    "p": "string"
}

c is the client token field. This is returned if it was given in the GetStream request. Use the client token to associate the response with its request.
f is the ID of the stream file to which the current data block payload belongs.
l is the size of the data block payload in bytes.
i is the ID of the data block contained in the payload. Data blocks are numbered starting from 0.
p contains the data block payload. This field is a string, which represents the value of the data block in Base64 encoding.
Devices will receive one or more GetStream responses on the above. Each response message contains basic information and a data payload for a single block. Repeat the above request to receive all data blocks.

Response Topic	$aws/things/{clientId}/streams/{streamname}/rejected/json
Response Payload	Error

####Error Structure

Error

```json { "o": "string", "m": "string", "c": "string" } ```

o is the error code that indicates the reason an error occurred. Refer to the error codes later in this section for more details.
m is the error message that contains details of the error.
c is the client token field. This may be returned if it was given in the DescribeStream request. You can use the client token to associate the response with its request.

For more details on error codes, refer to the Streams Error Codes section.