Trivial File Transfer Protocol (TFTP) Client (Alpha)#

The TFTP Client facilitates file exchange between a client and any remote host over UDP. This component provides an easy-to-use solution for downloading and uploading files from a remote host. The TFTP client can be initialized with sl_tftp_clnt_init(), and the functions sl_tftp_clnt_get() and sl_tftp_clnt_put() can be used to download and upload files, respectively. Additionally, the block size and timeout options can be configured to negotiate between the server and the client, optimizing the transmission. The component implements the TFTP protocol as specified in RFC 1350.

To ensure proper functionality, a TFTP server, such as tftpd-hpa, must be prepared on the remote host.

The following code example shows how to download a file with TFTP Client:

#include "sl_tftp_clnt.h"

// TFTP data callback
// In this callback you can implement storing data chunks to flash, heap or any other memory.
static void tftp_data_hnd(sl_tftp_clnt_t * const clnt,
                          const uint8_t * const data_ptr,
                          const uint16_t data_size) {
  (void)data_ptr;
  (void)data_size;
  printf("Data received chunk %u (%u bytes)\n",
         clnt->packet.content.data.block_num,
         clnt->packet.content.data.data_size);
}

// TFTP error callback
// You can implement error handling in this callback.
static void tftp_error_hnd(sl_tftp_clnt_t * const clnt,
                           const uint16_t error_code,
                           const char *error_msg) {
  (void)clnt;
  printf("Error (%u): %s\n", error_code, error_msg);
}

static void tftp_get_file(void) {
  static sl_tftp_clnt_t tftp_clnt = { 0 };

  // Initialize Client instance
  if (sl_tftp_clnt_init(&tftp_clnt,
                        "2001:db8::1",
                        SL_TFTP_DEFAULT_HOST_PORT,
                        tftp_data_hnd,
                        tftp_error_hnd) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Set blocksize option
  if (sl_tftp_clnt_set_option(&tftp_clnt,
                              SL_TFTP_OPT_EXT_BLOCKSIZE,
                              1228) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Start to download a file
  if (sl_tftp_clnt_get(&tftp_clnt,
                       "test.txt") != SL_STATUS_OK) {
    // Error handling
    return;
  }

  while (1) {
    if (sl_tftp_clnt_is_op_finished(&tftp_clnt)) {
      printf("File download finished\n");
      break;
    }
    osDelay(1);
  }
}
#include "sl_tftp_clnt.h"

// TFTP data callback
// In this callback you can implement storing data chunks to flash, heap or any other memory.
static void tftp_data_hnd(sl_tftp_clnt_t * const clnt,
                          const uint8_t * const data_ptr,
                          const uint16_t data_size) {
  (void)data_ptr;
  (void)data_size;
  printf("Data received chunk %u (%u bytes)\n",
         clnt->packet.content.data.block_num,
         clnt->packet.content.data.data_size);
}

// TFTP error callback
// You can implement error handling in this callback.
static void tftp_error_hnd(sl_tftp_clnt_t * const clnt,
                           const uint16_t error_code,
                           const char *error_msg) {
  (void)clnt;
  printf("Error (%u): %s\n", error_code, error_msg);
}

static void tftp_get_file(void) {
  static sl_tftp_clnt_t tftp_clnt = { 0 };

  // Initialize Client instance
  if (sl_tftp_clnt_init(&tftp_clnt,
                        "2001:db8::1",
                        SL_TFTP_DEFAULT_HOST_PORT,
                        tftp_data_hnd,
                        tftp_error_hnd) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Set blocksize option
  if (sl_tftp_clnt_set_option(&tftp_clnt,
                              SL_TFTP_OPT_EXT_BLOCKSIZE,
                              1228) != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Start to download a file
  if (sl_tftp_clnt_get(&tftp_clnt,
                       "test.txt") != SL_STATUS_OK) {
    // Error handling
    return;
  }

  while (1) {
    if (sl_tftp_clnt_is_op_finished(&tftp_clnt)) {
      printf("File download finished\n");
      break;
    }
    osDelay(1);
  }
}

Modules#

Configurations

Type definitions

Portable interface

Typedefs#

typedef void(*

sl_tftp_clnt_data_hnd_t)(sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size)

Data handler callback definition.

typedef void(*

sl_tftp_clnt_error_hnd_t)(sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg)

Error handler callback defintion.

Functions#

__STATIC_INLINE sl_status_t

sl_tftp_clnt_default_init(sl_tftp_clnt_t *const clnt)

Init TFTP Client default.

__STATIC_INLINE sl_status_t

sl_tftp_clnt_get(sl_tftp_clnt_t *const clnt, const char *file)

TFT Client Get.

sl_status_t

sl_tftp_clnt_init(sl_tftp_clnt_t *const clnt, const char *host, const uint16_t port, sl_tftp_clnt_data_hnd_t data_hnd, sl_tftp_clnt_error_hnd_t error_hnd)

Init TFTP Client.

bool

sl_tftp_clnt_is_op_finished(const sl_tftp_clnt_t *const clnt)

TFTP Client is finished operation.

bool

sl_tftp_clnt_is_op_get(const sl_tftp_clnt_t *const clnt)

TFTP Client is Get operation.

bool

sl_tftp_clnt_is_op_put(const sl_tftp_clnt_t *const clnt)

TFTP Client is Put operation.

bool

sl_tftp_clnt_is_op_rrq_wrq_failed(const sl_tftp_clnt_t *const clnt)

TFTP Client is RRQ or WRQ failed.

void

sl_tftp_clnt_print_pkt(const sl_tftp_pkt_t *const pkt)

Print packet.

__STATIC_INLINE sl_status_t

sl_tftp_clnt_put(sl_tftp_clnt_t *const clnt, const char *file)

TFT Client Put.

sl_status_t

sl_tftp_clnt_request(sl_tftp_clnt_t *const clnt, const uint16_t opcode, const char *file, const char *mode)

TFTP Client request.

void

sl_tftp_clnt_service_init(void)

Init TFTP Client service.

sl_status_t

sl_tftp_clnt_set_option(sl_tftp_clnt_t *const clnt, const char *opt, const uint32_t value)

Set TFTP Client option.

sl_status_t

sl_tftp_clnt_terminate_session(sl_tftp_clnt_t *const clnt)

TFTP Client terminate session.

sl_status_t

sl_tftp_clnt_wait_op_finished(const sl_tftp_clnt_t *const clnt)

TFTP Client wait operation finished.

Macros#

#define

SL_TFTP_DEFAULT_DATA_BLOCK_SIZE 512U

TFTP Default data block size.

#define

SL_TFTP_DEFAULT_HOST_PORT 69U

Default TFTP host port.

#define

SL_TFTP_DEFAULT_SRV_RET_TIMEOUT_SEC 1U

TFTP Default server retransmit timeout interval in seconds.

#define

SL_TFTP_ERRORCODE_ACCVIOL 2U

Access violation.

#define

SL_TFTP_ERRORCODE_DISKFULL 3U

Disk full or allocation exceeded.

#define

SL_TFTP_ERRORCODE_FEXIST 6U

File already exists.

#define

SL_TFTP_ERRORCODE_FNOTFOUND 1U

File not found.

#define

SL_TFTP_ERRORCODE_ILLEGALOP 4U

Illegal TFTP operation.

#define

SL_TFTP_ERRORCODE_NOTDEF 0U

Not defined, see error message (if any).

#define

SL_TFTP_ERRORCODE_NOUSR 7U

No such user.

#define

SL_TFTP_ERRORCODE_OPTNEGOTFAIL 8U

Terminate transfer due to option negotiation.

#define

SL_TFTP_ERRORCODE_UNKNTID 5U

Unknown transfer ID.

#define

SL_TFTP_MODE_NETASCII_STR "netascii"

Netascii mode string.

#define

SL_TFTP_MODE_NETASCII_STR_LEN 8U

Netascii mode string length.

#define

SL_TFTP_MODE_OCTET_STR "octet"

Octet mode string.

#define

SL_TFTP_MODE_OCTET_STR_LEN 5U

Octet mode string length.

#define

SL_TFTP_OPCODE_ACK 4U

TFTP Acknowledgement operation code.

#define

SL_TFTP_OPCODE_DATA 3U

TFTP Data operation code.

#define

SL_TFTP_OPCODE_ERROR 5U

TFTP Error operation code.

#define

SL_TFTP_OPCODE_OACK 6U

TFTP Option Acknowledgement operation code.

#define

SL_TFTP_OPCODE_RRQ 1U

TFTP Read Request operation code.

#define

SL_TFTP_OPCODE_WRQ 2U

TFTP Write Request operation code.

#define

SL_TFTP_OPT_EXT_BLOCKSIZE "blksize"

TFTP Blocksize Option.

#define

SL_TFTP_OPT_EXT_BLOCKSIZE_LEN 7U

TFTP Blocksize Option length.

#define

SL_TFTP_OPT_EXT_MULTICAST "multicast"

TFTP Multicast Option.

#define

SL_TFTP_OPT_EXT_MULTICAST_LEN 9U

TFTP Multicast Option length.

#define

SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL "timeout"

TFTP Timeout Interval Option.

#define

SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL_LEN 7U

TFTP Timeout Interval Option length.

#define

SL_TFTP_OPT_EXT_TRANSFER_SIZE "tsize"

TFTP Transfer Size Option.

#define

SL_TFTP_OPT_EXT_TRANSFER_SIZE_LEN 5U

TFTP Transfer Size Option length.

#define

SL_TFTP_OPT_EXT_WINDOWSIZE "windowsize"

TFTP Windowsize Option.

#define

SL_TFTP_OPT_EXT_WINDOWSIZE_LEN 10U

TFTP Windowsize Option length.

#define

SL_TFTP_SERVICE_LOOP while (1)

TFTP Service loop definition.

#define

SL_TFTP_STR_MAX_LEN 256UL

TFTP string max length (filename, mode)

Typedef Documentation#

sl_tftp_clnt_data_hnd_t#

typedef void(* sl_tftp_clnt_data_hnd_t) (sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size) )(sl_tftp_clnt_t *const clnt, const uint8_t *const data_ptr, const uint16_t data_size)

Data handler callback definition.

sl_tftp_clnt_error_hnd_t#

typedef void(* sl_tftp_clnt_error_hnd_t) (sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg) )(sl_tftp_clnt_t *const clnt, const uint16_t error_code, const char *error_msg)

Error handler callback defintion.

Function Documentation#

sl_tftp_clnt_default_init#

__STATIC_INLINE sl_status_t sl_tftp_clnt_default_init (sl_tftp_clnt_t *const clnt)

Init TFTP Client default.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client to initialize

Initialize Client with default values from config file parameters: host: SL_TFTP_CLNT_DEFAULT_HOST port: SL_TFTP_DEFAULT_HOST_PORT data_hnd: simple hex dump callback error_hnd: error code and message printer Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

References SL_TFTP_CLNT_DEFAULT_HOST , sl_tftp_clnt_init , and SL_TFTP_DEFAULT_HOST_PORT

sl_tftp_clnt_get#

__STATIC_INLINE sl_status_t sl_tftp_clnt_get (sl_tftp_clnt_t *const clnt, const char * file)

TFT Client Get.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client
const char *	[in]	file	File name

Get file from server in octet mode Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

References sl_tftp_clnt_request , SL_TFTP_MODE_OCTET_STR , and SL_TFTP_OPCODE_RRQ

sl_tftp_clnt_init#

sl_status_t sl_tftp_clnt_init (sl_tftp_clnt_t *const clnt, const char * host, const uint16_t port, sl_tftp_clnt_data_hnd_t data_hnd, sl_tftp_clnt_error_hnd_t error_hnd)

Init TFTP Client.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client to initialize
const char *	[in]	host	Host address string
const uint16_t	[in]	port	Port number
sl_tftp_clnt_data_hnd_t	[in]	data_hnd	Data handler callback
sl_tftp_clnt_error_hnd_t	[in]	error_hnd	Error handler callback

Initialize TFTP Client context Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

sl_tftp_clnt_is_op_finished#

bool sl_tftp_clnt_is_op_finished (const sl_tftp_clnt_t *const clnt)

TFTP Client is finished operation.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_clnt_t *const	[in]	clnt	Client

Check read or write operations whether is in progress Returns

true Is finished
false Is in progress

sl_tftp_clnt_is_op_get#

bool sl_tftp_clnt_is_op_get (const sl_tftp_clnt_t *const clnt)

TFTP Client is Get operation.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_clnt_t *const	[in]	clnt	Client

Check Read operation is in progress Returns

true Is in progress otherwise false

sl_tftp_clnt_is_op_put#

bool sl_tftp_clnt_is_op_put (const sl_tftp_clnt_t *const clnt)

TFTP Client is Put operation.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_clnt_t *const	[in]	clnt	Client

Check Write operation is in progress Returns

true Is in progress otherwise false

sl_tftp_clnt_is_op_rrq_wrq_failed#

bool sl_tftp_clnt_is_op_rrq_wrq_failed (const sl_tftp_clnt_t *const clnt)

TFTP Client is RRQ or WRQ failed.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_clnt_t *const	[in]	clnt	Client

Check Read or Write Request operation is failed Returns

true Is failed otherwise false

sl_tftp_clnt_print_pkt#

void sl_tftp_clnt_print_pkt (const sl_tftp_pkt_t *const pkt)

Print packet.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_pkt_t *const	[in]	pkt	Packet to print

Print packet info in json format

sl_tftp_clnt_put#

__STATIC_INLINE sl_status_t sl_tftp_clnt_put (sl_tftp_clnt_t *const clnt, const char * file)

TFT Client Put.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client
const char *	[in]	file	File name to store data

Send buffer content to file on remote server Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

References sl_tftp_clnt_request , SL_TFTP_MODE_OCTET_STR , and SL_TFTP_OPCODE_WRQ

sl_tftp_clnt_request#

sl_status_t sl_tftp_clnt_request (sl_tftp_clnt_t *const clnt, const uint16_t opcode, const char * file, const char * mode)

TFTP Client request.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client
const uint16_t	[in]	opcode	Operation code: SL_TFTP_OPCODE_RRQ or SL_TFTP_OPCODE_WRQ
const char *	[in]	file	File name to put or get
const char *	[in]	mode	Mode string

Send request for Server (RRQ or WRQ) Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

Referenced by sl_tftp_clnt_get , and sl_tftp_clnt_put

sl_tftp_clnt_service_init#

void sl_tftp_clnt_service_init (void )

Init TFTP Client service.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Initialize TFTP client OS objects

sl_tftp_clnt_set_option#

sl_status_t sl_tftp_clnt_set_option (sl_tftp_clnt_t *const clnt, const char * opt, const uint32_t value)

Set TFTP Client option.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client
const char *	[in]	opt	Option string
const uint32_t	[in]	value	Option value

Set TFTP Client option in the TFTP client instance. The supported options are:

SL_TFTP_OPT_EXT_BLOCKSIZE: Blocksize option (8 - 1228 for Wi-SUN)
SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL: Timeout interval option (1 - 255) Returns
- sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

sl_tftp_clnt_terminate_session#

sl_status_t sl_tftp_clnt_terminate_session (sl_tftp_clnt_t *const clnt)

TFTP Client terminate session.

Parameters

Type	Direction	Argument Name	Description
sl_tftp_clnt_t *const	[inout]	clnt	Client

Terminate TFTP session Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

sl_tftp_clnt_wait_op_finished#

sl_status_t sl_tftp_clnt_wait_op_finished (const sl_tftp_clnt_t *const clnt)

TFTP Client wait operation finished.

Parameters

Type	Direction	Argument Name	Description
const sl_tftp_clnt_t *const	[in]	clnt	Client

Wait for operation to finish Returns

sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL

Macro Definition Documentation#

SL_TFTP_DEFAULT_DATA_BLOCK_SIZE#

#define SL_TFTP_DEFAULT_DATA_BLOCK_SIZE

Value:

512U

TFTP Default data block size.

SL_TFTP_DEFAULT_HOST_PORT#

#define SL_TFTP_DEFAULT_HOST_PORT

Value:

69U

Default TFTP host port.

SL_TFTP_DEFAULT_SRV_RET_TIMEOUT_SEC#

#define SL_TFTP_DEFAULT_SRV_RET_TIMEOUT_SEC

Value:

1U

TFTP Default server retransmit timeout interval in seconds.

SL_TFTP_ERRORCODE_ACCVIOL#

#define SL_TFTP_ERRORCODE_ACCVIOL

Value:

2U

Access violation.

SL_TFTP_ERRORCODE_DISKFULL#

#define SL_TFTP_ERRORCODE_DISKFULL

Value:

3U

Disk full or allocation exceeded.

SL_TFTP_ERRORCODE_FEXIST#

#define SL_TFTP_ERRORCODE_FEXIST

Value:

6U

File already exists.

SL_TFTP_ERRORCODE_FNOTFOUND#

#define SL_TFTP_ERRORCODE_FNOTFOUND

Value:

1U

File not found.

SL_TFTP_ERRORCODE_ILLEGALOP#

#define SL_TFTP_ERRORCODE_ILLEGALOP

Value:

4U

Illegal TFTP operation.

SL_TFTP_ERRORCODE_NOTDEF#

#define SL_TFTP_ERRORCODE_NOTDEF

Value:

0U

Not defined, see error message (if any).

SL_TFTP_ERRORCODE_NOUSR#

#define SL_TFTP_ERRORCODE_NOUSR

Value:

7U

No such user.

SL_TFTP_ERRORCODE_OPTNEGOTFAIL#

#define SL_TFTP_ERRORCODE_OPTNEGOTFAIL

Value:

8U

Terminate transfer due to option negotiation.

SL_TFTP_ERRORCODE_UNKNTID#

#define SL_TFTP_ERRORCODE_UNKNTID

Value:

5U

Unknown transfer ID.

SL_TFTP_MODE_NETASCII_STR#

#define SL_TFTP_MODE_NETASCII_STR

Value:

"netascii"

Netascii mode string.

SL_TFTP_MODE_NETASCII_STR_LEN#

#define SL_TFTP_MODE_NETASCII_STR_LEN

Value:

8U

Netascii mode string length.

SL_TFTP_MODE_OCTET_STR#

#define SL_TFTP_MODE_OCTET_STR

Value:

"octet"

Octet mode string.

SL_TFTP_MODE_OCTET_STR_LEN#

#define SL_TFTP_MODE_OCTET_STR_LEN

Value:

5U

Octet mode string length.

SL_TFTP_OPCODE_ACK#

#define SL_TFTP_OPCODE_ACK

Value:

4U

TFTP Acknowledgement operation code.

SL_TFTP_OPCODE_DATA#

#define SL_TFTP_OPCODE_DATA

Value:

3U

TFTP Data operation code.

SL_TFTP_OPCODE_ERROR#

#define SL_TFTP_OPCODE_ERROR

Value:

5U

TFTP Error operation code.

SL_TFTP_OPCODE_OACK#

#define SL_TFTP_OPCODE_OACK

Value:

6U

TFTP Option Acknowledgement operation code.

SL_TFTP_OPCODE_RRQ#

#define SL_TFTP_OPCODE_RRQ

Value:

1U

TFTP Read Request operation code.

SL_TFTP_OPCODE_WRQ#

#define SL_TFTP_OPCODE_WRQ

Value:

2U

TFTP Write Request operation code.

SL_TFTP_OPT_EXT_BLOCKSIZE#

#define SL_TFTP_OPT_EXT_BLOCKSIZE

Value:

"blksize"

TFTP Blocksize Option.

SL_TFTP_OPT_EXT_BLOCKSIZE_LEN#

#define SL_TFTP_OPT_EXT_BLOCKSIZE_LEN

Value:

7U

TFTP Blocksize Option length.

SL_TFTP_OPT_EXT_MULTICAST#

#define SL_TFTP_OPT_EXT_MULTICAST

Value:

"multicast"

TFTP Multicast Option.

SL_TFTP_OPT_EXT_MULTICAST_LEN#

#define SL_TFTP_OPT_EXT_MULTICAST_LEN

Value:

9U

TFTP Multicast Option length.

SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL#

#define SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL

Value:

"timeout"

TFTP Timeout Interval Option.

SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL_LEN#

#define SL_TFTP_OPT_EXT_TIMEOUT_INTERVAL_LEN

Value:

7U

TFTP Timeout Interval Option length.

SL_TFTP_OPT_EXT_TRANSFER_SIZE#

#define SL_TFTP_OPT_EXT_TRANSFER_SIZE

Value:

"tsize"

TFTP Transfer Size Option.

SL_TFTP_OPT_EXT_TRANSFER_SIZE_LEN#

#define SL_TFTP_OPT_EXT_TRANSFER_SIZE_LEN

Value:

5U

TFTP Transfer Size Option length.

SL_TFTP_OPT_EXT_WINDOWSIZE#

#define SL_TFTP_OPT_EXT_WINDOWSIZE

Value:

"windowsize"

TFTP Windowsize Option.

SL_TFTP_OPT_EXT_WINDOWSIZE_LEN#

#define SL_TFTP_OPT_EXT_WINDOWSIZE_LEN

Value:

10U

TFTP Windowsize Option length.

SL_TFTP_SERVICE_LOOP#

#define SL_TFTP_SERVICE_LOOP

Value:

while (1)

TFTP Service loop definition.

SL_TFTP_STR_MAX_LEN#

#define SL_TFTP_STR_MAX_LEN

Value:

256UL

TFTP string max length (filename, mode)