Logo
Link Labs Interface Library
External host library for using Link Lab's modules.
top
Data Structures | Macros | Typedefs | Enumerations | Functions
Symphony Link File Transfer Protocol

Detailed Description

Symphony Link File Transfer Protocol. Symphony FTP handles the detials for transfering a file over a Symphony Link network.

The file transfer is initiated at the Conductor Client-Edge. Each file transfers is identified by a 32-bit file ID and a 32-bit file version. The file ID and file version should be defined by the user of this library. The maximum file size is 256 kB.

Note: There is a unique file ID reserved for Link Labs module firmware images.

In order to use this protocol the module must be configured to use one of the two available downlink modes ("downlink always on" or "downlink mailbox").

When using downlink mailbox the protocol server must be provided with a worse-case mailbox polling interval. When the module receives the first Symphony FTP packet, it will call the dl_config callback and the user must configure the module for downlink always on mode during the file transfer state. Once the file transfer is complete, the module can return to downlink mailbox mode – waiting for the apply message.

The state machine for the client-side of this protocol is as follows:

  /------\     /----------\     /----------\
  | Idle | --> | File     | --> | Wait for |  --> return to Idle
  |      |     | Transfer |     | Apply    |
  \------/     \----------/     \----------/

Unicast

This is a file transfer from Conductor to a single Symphony module identified by it's Symphony node address (e.g. $301$0-0-0-030000001)

Multicast

This is a file transfer from Conductor to a group of Symphony modules identified by application token. The group of modules can be reduced to all Symphony modules connected through a particular gateway.

Data Structures

struct  ll_ftp
 
struct  ll_ftp_callbacks
 

Macros

#define BASE_UL_MSG_LEN   (14)
 
#define LL_FTP_HDR_LEN   (16)
 
#define LL_FTP_HDR_OFFSET_CRC   (0)
 
#define LL_FTP_HDR_OFFSET_ID   (8)
 
#define LL_FTP_HDR_OFFSET_SIZE   (4)
 
#define LL_FTP_HDR_OFFSET_VERSION   (12)
 
#define LL_FTP_TX_BUF_SIZE   (BASE_UL_MSG_LEN + MAX_NUM_RETRY_SEGS * 2)
 
#define MAX_FILE_SEGMENT_BYTES   (107)
 
#define MAX_NUM_RETRY_SEGS   (16)
 
#define MAX_NUM_SEGMENTS   (2400)
 
#define NUM_RX_SEGS_BITMASK   (MAX_NUM_SEGMENTS / 32)
 

Typedefs

typedef ll_ftp_return_code_t(* ll_ftp_apply_t) (uint32_t file_id, uint32_t file_version, uint32_t file_size)
 File apply callback, this is called after all segments have been received, the file has been closed, and the server is ready to proceed with the final step of the process, if any. More...
 
typedef struct ll_ftp_callbacks ll_ftp_callbacks_t
 
typedef ll_ftp_return_code_t(* ll_ftp_close_t) (uint32_t file_id, uint32_t file_version)
 File close callback, this is called once all segments have been received, when a file transfer is interrupted, or a file transfer is canceled. More...
 
typedef ll_ftp_return_code_t(* ll_ftp_dl_config_t) (bool downlink_on)
 downlink config callback, this is called to toggle between the default downlink state and the downlink always on state to support the different phases of the file transfer. More...
 
typedef ll_ftp_return_code_t(* ll_ftp_open_t) (uint32_t file_id, uint32_t file_version, uint32_t file_size)
 File open callback, this is called at the beginning of the file transfer. More...
 
typedef ll_ftp_return_code_t(* ll_ftp_read_t) (uint32_t file_id, uint32_t file_version, uint32_t offset, uint8_t *payload, uint16_t len)
 File read callback, this is called at the end of the file transfer to compute the file CRC integrity check. More...
 
typedef enum ll_ftp_return_code ll_ftp_return_code_t
 Symphonty FTP return codes. More...
 
typedef ll_ftp_return_code_t(* ll_ftp_send_uplink_t) (const uint8_t *buf, uint8_t len, bool acked, uint8_t port)
 Send uplink callback, the user of this library must send responses to the server over Symphony Link on behalf of the Symphony FTP protocol. More...
 
typedef enum ll_ftp_state ll_ftp_state_t
 
typedef struct ll_ftp ll_ftp_t
 
typedef ll_ftp_return_code_t(* ll_ftp_write_t) (uint32_t file_id, uint32_t file_version, uint32_t offset, uint8_t *payload, uint16_t len)
 File write callback, this is called each time a segment is received to store the received segment to storage. More...
 

Enumerations

enum  ll_ftp_return_code {
  LL_FTP_OK, LL_FTP_OOR, LL_FTP_INVALID_VALUE, LL_FTP_NO_ACTION,
  LL_FTP_ERROR
}
 Symphonty FTP return codes. More...
 
enum  ll_ftp_state { IDLE, SEGMENT, APPLY }
 

Functions

int32_t ll_ftp_init (ll_ftp_t *f, ll_ftp_callbacks_t *cb)
 Initializes an ll_ftp_t object and registers application-specific callbacks. More...
 
int32_t ll_ftp_msg_process (ll_ftp_t *f, uint8_t *msg, uint8_t len)
 Signal Symphony FTP entry point. Processes a received downlink message for Symphony FTP or a timeout. This code expects this function to be called at least once per second. More...
 
int32_t ll_ftp_num_missing_segs_get (ll_ftp_t *f)
 Determines the number of outstanding file segments still to be downloaded. More...
 

Macro Definition Documentation

#define BASE_UL_MSG_LEN   (14)
#define LL_FTP_HDR_LEN   (16)
#define LL_FTP_HDR_OFFSET_CRC   (0)
#define LL_FTP_HDR_OFFSET_ID   (8)
#define LL_FTP_HDR_OFFSET_SIZE   (4)
#define LL_FTP_HDR_OFFSET_VERSION   (12)
#define LL_FTP_TX_BUF_SIZE   (BASE_UL_MSG_LEN + MAX_NUM_RETRY_SEGS * 2)
#define MAX_FILE_SEGMENT_BYTES   (107)
#define MAX_NUM_RETRY_SEGS   (16)
#define MAX_NUM_SEGMENTS   (2400)
#define NUM_RX_SEGS_BITMASK   (MAX_NUM_SEGMENTS / 32)

Typedef Documentation

typedef ll_ftp_return_code_t(* ll_ftp_apply_t) (uint32_t file_id, uint32_t file_version, uint32_t file_size)

File apply callback, this is called after all segments have been received, the file has been closed, and the server is ready to proceed with the final step of the process, if any.

Parameters
[in]file_idThe 32-bit unique ID of the file.
[in]file_versionThe 32-bit unique file version.
[in]file_sizeFile size in bytes.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.

Symphony FTP required callbacks

typedef ll_ftp_return_code_t(* ll_ftp_close_t) (uint32_t file_id, uint32_t file_version)

File close callback, this is called once all segments have been received, when a file transfer is interrupted, or a file transfer is canceled.

Parameters
[in]file_idThe 32-bit unique ID of the file.
[in]file_versionThe 32-bit unique file version.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.
typedef ll_ftp_return_code_t(* ll_ftp_dl_config_t) (bool downlink_on)

downlink config callback, this is called to toggle between the default downlink state and the downlink always on state to support the different phases of the file transfer.

Note
If the default mode is downlink always on, then this function has nothing to do.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.
typedef ll_ftp_return_code_t(* ll_ftp_open_t) (uint32_t file_id, uint32_t file_version, uint32_t file_size)

File open callback, this is called at the beginning of the file transfer.

Parameters
[in]file_idThe 32-bit unique ID of the file.
[in]file_versionThe 32-bit unique file version.
[in]file_sizeFile size in bytes.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.
typedef ll_ftp_return_code_t(* ll_ftp_read_t) (uint32_t file_id, uint32_t file_version, uint32_t offset, uint8_t *payload, uint16_t len)

File read callback, this is called at the end of the file transfer to compute the file CRC integrity check.

Parameters
[in]file_idThe 32-bit unique ID of the file.
[in]file_versionThe 32-bit unique file version.
[in]offsetoffset of first byte to be read.
[out]payloadpointer to the buffer where the bytes will be stored.
[in]lenNumber of bytes to read.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.

Symphonty FTP return codes.

typedef ll_ftp_return_code_t(* ll_ftp_send_uplink_t) (const uint8_t *buf, uint8_t len, bool acked, uint8_t port)

Send uplink callback, the user of this library must send responses to the server over Symphony Link on behalf of the Symphony FTP protocol.

Parameters
[in]bufbyte array containing the data payload.
[in]lenlength of the input buffer.
[in]ackedWhether or not to request an ACK from the gateway.
[in]portThe port number to send to.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.

Symphony FTP Download state

typedef struct ll_ftp ll_ftp_t

Symphony FTP object. A reference to an ll_ftp_t object is used as the context pointer.

typedef ll_ftp_return_code_t(* ll_ftp_write_t) (uint32_t file_id, uint32_t file_version, uint32_t offset, uint8_t *payload, uint16_t len)

File write callback, this is called each time a segment is received to store the received segment to storage.

Parameters
[in]file_idThe 32-bit unique ID of the file.
[in]file_versionThe 32-bit unique file version.
[in]offsetoffset of first byte to be written.
[in]payloadpointer to the buffer of bytes.
[in]lenNumber of bytes to write.
Returns
LL_FTP_OK - success, see ll_ftp_return_code.

Enumeration Type Documentation

Symphonty FTP return codes.

Enumerator
LL_FTP_OK 

Success.

LL_FTP_OOR 

Out of range.

LL_FTP_INVALID_VALUE 

Invalid input value.

LL_FTP_NO_ACTION 

No action.

LL_FTP_ERROR 

Error.

Symphony FTP Download state

Enumerator
IDLE 

Idle.

SEGMENT 

File Transfer.

APPLY 

Wait for Apply.

Function Documentation

int32_t ll_ftp_init ( ll_ftp_t f,
ll_ftp_callbacks_t cb 
)

Initializes an ll_ftp_t object and registers application-specific callbacks.

Parameters
int32_t ll_ftp_msg_process ( ll_ftp_t f,
uint8_t *  msg,
uint8_t  len 
)

Signal Symphony FTP entry point. Processes a received downlink message for Symphony FTP or a timeout. This code expects this function to be called at least once per second.

Parameters
int32_t ll_ftp_num_missing_segs_get ( ll_ftp_t f)

Determines the number of outstanding file segments still to be downloaded.

Parameters