7.5 Protocol Specification

The following are the control and data commands that are supported in this protocol specification for the transport of a blob of file from the application server and network server to the end device.

All commands are sent uni-cast to the end device.

The diagram below describes the high level messaging flow from Developer to the device.

fig 7.3 High Level Messaging Flow from Developer to End Device

All messages follow the Sidewalk application layer message frame formats below refer to Chapter 3 of specification document for more details.

fig 7.4 Sidewalk Application Layer Format

7.5.1 SBDT Commands

All SBDT commands share the same command class

Table 7.1 SBDT Commands

Mnemonic	Length	Value	Description
cmd_class	12b	0x03	This value is common for all sbdt control and data commands

7.5.1.1 Application Layer Commands

TLV

Sidewalk TLV format is adopted to encode the command data. The format of the TLV is as below. In TLV encoding, value determines the length, even though type is UINT32, if the value is less than 255 then the length encoded in TLV will be only one byte.

Table 7.2 TLV Format 1

Value Length	Key	Value
2b	6b	xB

Table 7.3 TLV Format 2

Value Length(2b)	Length	Comments
0b00	1
0b01	2
0b10	3
0b11	length encoded in next byte	[2b(11) — 6b key — 1B value length — xB value]

Table 7.4 TLV Format 3

Key	Value (6b)	Size
TAG_ID_SBDT_FILE_ID	0x01	4B
TAG_ID_SBDT_NUM_OF_BLOCKS	0x02	2B
TAG_ID_SBDT_BLOCK_SIZE	0x03	2B
TAG_ID_SBDT_BLOCK_ID	0x04	2B
TAG_ID_SBDT_LAST_BLOCK_SIZE	0x05	2B
TAG_ID_SBDT_CHUNK_MTU	0x06	2B
TAG_ID_CHUNK_ID	0x07	1B
TAG_ID_SBDT_WINDOW_SIZE	0x08	1B
TAG_ID_SBDT_BIT_MASK_SIZE	0x09	4B
TAG_ID_SBDT_STATUS	0x0A	1B
TAG_ID_SBDT_AES_KEY	0x0B	16B
TAG_ID_SBDT_META_DATA_OFFSET	0x0C	1B-2B
TAG_ID_SBDT_DATA	0x0D	1B-nB
TAG_ID_SBDT_START_TIME	0x0E	4B
TAG_ID_SBDT_SEQUENCE_NUMBER	0x0F	2B
TAG_ID_SBDT_TIME_REF	0x10	4B
TAG_ID_SBDT_CUSTOMER_REASON	0x11	1B
TAG_ID_SBDT_ACTUAL_BLOCK_SIZE	0x12	2B
TAG_ID_SBDT_NUMBER_OF_CHUNKS	0x13	2B

Transfer Request

The application transfer request is sent by the application server to the end device to initiate the file transfer session. Below is a description of the frame format.

Table 7.5 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	14b	0x01	Write	TRANSFER_APPLICATION_REQUEST	DL
	14b	0x03	Response	TRANSFER_APPLICATION_RESPONSE	UL

Table 7.6 Command Data - TRANSFER APPLICATION REQUEST

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0	fixed	SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
fragment_size	1B-2B	1K-8K	0x03	user supplied fragment size range from 1K to 8K
	1B-2B	1K-8K	0x43
number_of_fragments	1B-2B	variable	0x02	number of fragment size fragments in a file
	1B-2B	variable	0x42
last_fragment_size	1B-2B	variable	0x05	size of the last fragment of the file
	1B-2B	variable	0x45
start_time	4B	variable	0x8E	time to start the transfer
file_descriptor	1B-32B	variable	0x0, 0x4, 0x8, 0xc	user supplied file meta data

Table 7.7 Command Data - TRANSFER APPLICATION RESPONSE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
fragment_id	1B-2B	variable	0x04	current fragment index
	1B-2B	variable	0x44
sbdt_status	1B	variable	0x0A	SBDT error status code

Transfer File Finalize

The transfer file finalize command is sent by the application server to the end device to exit the file transfer session. Below is a description of the frame format.

Table 7.8 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x21	Write	TRANSFER_FILE_FINALIZE	DL
	12b	0x23	Response	TRANSFER_FILE_FINALIZE_RESPONSE	UL

Table 7.9 Command Data - TRANSFER FILE FINALIZE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file

Table 7.10 Command Data - TRANSFER FILE FINALIZE RESPONSE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
sbdt_status	1B	variable	0x0A	SBDT error status code

Transfer Cancel

The transfer cancel command is sent by the application server to the end device to cancel an ongoing transfer session. Below is a description of the frame format.

Table 7.11 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x2D	Write	TRANSFER_CANCEL	DL
	12b	0x2F	Response	TRANSFER_CANCEL_RESPONSE	UL
	12b	0x2E	Notify	TRANSFER_CANCEL_NOTIFY	UL

Table 7.12 Command Data - TRANSFER CANCEL

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file

Table 7.13 Command Data - TRANSFER CANCEL RESPONSE

Mnemonic	Length	Value	TLV	Description
file_id	4B	0	0x81	unique file id crc32 of file
sbdt_status	1B	variable	0x0A	SBDT error status code

Table 7.14 Command Data - TRANSFER CANCEL NOTIFY

Mnemonic	Length	Value	TLV	Description
file_id	4B	0	0x81	unique file id crc32 of file
sbdt_status	1B	variable	0x0A	SBDT error status code
cancel_reason	1B	variable	0x11	cancel reason

7.5.1.2 Network Layer Commands

Transfer Request

The transfer request command is sent by the network server to the end device to initiate the file transfer session. Below is a description of the frame format.

Table 7.15 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x05	Write	TRANSFER_REQUEST	DL
	12b	0x07	Response	TRANSFER_RESPONSE	UL

Table 7.16 Command Data - TRANSFER REQUEST

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
fragment_size	1B-2B	1K-8K	0x03	user supplied fragment size range from 1K to 8K
	1B-2B	1K-8K	0x43
chunk_size	1B-2B	variable	0x06	size of link mtu chunks
	1B-2B	variable	0x46
window_size	1B	variable	0x08	size of fragment window

Table 7.17 Command Data - TRANSFER RESPONSE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
fragment_size	1B-2B	1K-8K	0x03	user supplied fragment size range from 1K to 8K
	1B-2B	1K-8K	0x43
fragment_id	1B-2B	variable	0x04	current fragment index
	1B-2B	variable	0x44
number_of_fragments	1B-2B	variable	0x02	number of fragment size fragments in a file
	1B-2B	variable	0x42
chunk_size	1B-2B	variable	0x06	size of link mtu chunks
	1B-2B	variable	0x46
window_size	1B	variable	0x08	size of fragment window
number_of_chunks	1B-2B	variable	0x13	number of chunks per fragment
	1B-2B	variable	0x93
sbdt_status	1B	variable	0x0A	SBDT error status code

Transfer Request Finalize

The transfer request finalize command is sent by the network server to the end device to finish the transfer request handshaking to initiate the file transfer session. Below is a description of the frame format.

Table 7.18 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x09	Write	TRANSFER_REQUEST_FINALIZE	DL
	12b	0x0B	Response	TRANSFER_REQUEST_FINALIZE_RESPONSE	UL

Table 7.19 Command Data - TRANSFER REQUEST FINALIZE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
chunk_size	1B-2B	variable	0x06	size of link mtu chunks
	1B-2B	variable	0x46
window_size	1B	variable	0x08	size of fragment window

Table 7.20 Command Data - TRANSFER REQUEST FINALIZE RESPONSE

Mnemonic	Length	Value	TLV	Description
sbdt_version	1B	0		SBDT version
file_id	4B	0	0x81	unique file id crc32 of file
sbdt_status	1B	variable	0x0A	SBDT error status code

Transfer Block

The transfer block command is sent by the network server to the end device to transport a fragment of the file. Below is a description of the frame format.

Table 7.21 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x15	Write	TRANSFER_BLOCK_DATA	DL
	12b	0x17	Response	TRANSFER_BLOCK_DATA_RESPONSE	UL

Table 7.22 Command Data - TRANSFER BLOCK DATA

Mnemonic	Length	Value	TLV	Description
header	1B			block header info
file_id	4B	0	0x81	unique file id crc32 of file
chunk_id	1B-2B	variable	0x07, 0x47	current chunk index
fragment_id	1B-2B	variable	0x04	current fragment index
seq_num	12B	variable	0x4F	fragment sequence number
chunk_data	1B-nB	variable	0x0D, 0x4D, 0x8D, 0xCD	file payload

Table 7.23 Command Data - TRANSFER BLOCK DATA RESPONSE

Mnemonic	Length	Value	TLV	Description
header	1B			block header info
file_id	4B	0	0x81	unique file id crc32 of file
fragment_id	1B-2B	variable	0x04	current fragment index
seq_num	12B	variable	0x4F	fragment sequence number
bitmask_size	1B-4B	variable	0x09, 0x49, 0x89, 0xC9	bitmask size
sbdt_status	1B	variable	0x0A	SBDT error status code
bitmask	1B-nB	variable		received data bitmask

Transfer Exit

The transfer exit command is sent by the network server to the end device to exit the transfer session on a completed transfer. Below is a description of the frame format.

Table 7.24 Command ID

Mnemonic	Length	Value	Type	command_name	Direction
cmd_id	12b	0x36	Notify	TRANSFER_FILE_EXIT	DL

Table 7.25 Command Data - TRANSFER FILE EXIT

Mnemonic	Length	Value	TLV	Description
file_id	4B	0	0x81	unique file id crc32 of file

7.5.2 Status

The following lists the status information returned by SBDT.

Table 7.26 SBDT Status Information

Value	Definition (FuotaDeviceStatus)	Description
0x00	Successful	Success
0x01	Wrong_descriptor	Generic Error
0x02	Wrong_descriptor	Version mismatch
0x03	Package_Not_Supported	File too Big
0x04	Not_enough_memory	No Memory
0x05	Low_Battery	Low Battery
0x06	Security_Error	Block Verification Failed
0x07	MissingFrag	Missing Chunks
0x08	File_System_Error	Write Failed
0x09	Security_Error	File Verification Failed
0x0A	Restart_Transfer	Restart
0x0B	Already_Available	File Exists
0x0C	Link_Not_Supported	Unsupported Link
0x0D	Internal_Error	Invalid File ID
0x0E	Internal_Error	Invalid Block Size
0x0F	MissingFrag	Invalid Block ID
0x10	Initial	Ready Status
0x11	InProgress	InProgress