BOTA Sender API

Table of contents Table of contents

Detailed Description

This page documents the BOTA Sender service API in C language. The BOTA Sender is a service that allows to transfer large portions of data to multpile recipients. Each of the recipients is expected to run the BOTA Recipient service (see BOTA Recipient API).

Data Structures

struct  BotaSenderTransferStatus
 Structure describing the status of the transfer. More...
 
struct  BotaTransferRecipient
 Structure describing the status of the recipient. More...
 
struct  BotaSenderMissingChunk
 Structure describing a data chunk that was reported missing by at least one recipient. More...
 
struct  BotaSenderTransferPolicy
 Structure describing transfer policy. More...
 
struct  BotaTransfer
 Structure describing a single BOTA transfer. More...
 
struct  BotaSender
 Structure describing BOTA Sender instance. More...
 

Typedef Documentation

◆ BotaOnTransferAcceptedCallback

typedef void(* BotaOnTransferAcceptedCallback) (BotaTransferId transferId, const EMBENET_IPV6 *recipientAddr)

Function that will be called when the transfer is accepted by a recipient (callback).

Parameters
[in]transferIdtransfer identifier
[in]recipientAddrIPv6 address of the recipient that accepted the transfer

◆ BotaOnTransferFinishedCallback

typedef void(* BotaOnTransferFinishedCallback) (BotaTransferId transferId)

Function that will be called when the transfer is finished (callback).

Parameters
[in]transferIdtransfer identifier

Enumeration Type Documentation

◆ BotaRecipientState

Type describing the state of the recipient.

Enumerator
BOTA_RECIPIENT_STATE_ACCEPTED 

Recipient has accepted the transfer and the transfer is now ongoing.

BOTA_RECIPIENT_STATE_REJECTED 

Recipient has rejected the transfer.

BOTA_RECIPIENT_STATE_SUCCESS 

Recipient successfully received the transfer.

BOTA_RECIPIENT_STATE_FAILED 

Recipient received the transfer but CRC validation failed.

◆ BotaSenderTransferState

Possible states of a single transfer.

Enumerator
BOTA_SENDER_TRANSFER_STATE_UNKNOWN 

The state of the transfer is unknown.

BOTA_SENDER_TRANSFER_STATE_REGISTERED 

The transfer has been registered but haven't started yet.

BOTA_SENDER_TRANSFER_STATE_SENDING_TRANSFER_REQUEST 

The transfer is in the process of sending request packets.

BOTA_SENDER_TRANSFER_STATE_SENDING_DATA 

The transfer is in the process of sending data packets.

BOTA_SENDER_TRANSFER_STATE_VALIDATING 

The transfer is in the process of validation.

BOTA_SENDER_TRANSFER_STATE_FINISHED 

The transfer is finished.

BOTA_SENDER_TRANSFER_STATE_ERROR 

The transfer is aborted due to error.

Function Documentation

◆ BOTA_SENDER_Init()

BotaResult BOTA_SENDER_Init ( BotaSender * botaSender,
uint16_t port,
BotaTimeFunc timeFunc )

Initializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.

Parameters
[in]botaSenderBOTA Sender instance
[in]portUDP port number used for BOTA transfers. This number should be the same in all BOTA-enabled devices. Consider using BOTA_DEFAULT_PORT value.
[in]timeFuncmandatory callback function that will provide time for the BOTA protocol instance
Return values
BOTA_RESULT_OKif Bota was initialized successfully
BOTA_RESULT_FAILED_TO_REGISTER_UDP_SOCKETif Bota was not initialized due to problem with UDP socket registration

◆ BOTA_SENDER_Deinit()

void BOTA_SENDER_Deinit ( BotaSender * botaSender)

Deinitializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.

◆ BOTA_SENDER_Proc()

void BOTA_SENDER_Proc ( BotaSender * botaSender)

Runs the Bulk-Over-The-Air (BOTA) protocol instance for the sender.

Parameters
[in]botaSenderBOTA Sender instance

◆ BOTA_SENDER_GetRequiredTransferSpaceSize()

size_t BOTA_SENDER_GetRequiredTransferSpaceSize ( size_t maxNumberOfRecipients)

Determines how much user memory is needed to handle the transfer to the given recipient/recipients.

In order to handle parallel transmissions to multiple recipients the BOTA protocol needs some temporary memory storage. This memory is called 'transfer space' and it is required for the user to provide such memory in order to run the BOTA transfer. This function returns the size of the transfer space that the user must provide in order to handle transfer to a given maximum number of recipients.

Parameters
[in]maxNumberOfRecipientsmaximum number of expected recipients
Returns
size (in number of bytes) of the required transfer space

◆ BOTA_SENDER_StartTransfer()

BotaResult BOTA_SENDER_StartTransfer ( BotaSender * botaSender,
BotaReadFunc readFunc,
BotaMemoryAddr readAddr,
size_t size,
const EMBENET_IPV6 * recipientAddr,
uint16_t recipientPort,
void const * transferInfo,
size_t transferInfoSize,
void * transferSpace,
size_t transferSpaceSize,
BotaSenderTransferPolicy * transferPolicy,
BotaOnTransferAcceptedCallback onTransferAccepted,
BotaOnTransferFinishedCallback onTransferFinished,
BotaTransferId * transferId )

Starts a new BOTA transfer.

This function starts a new Bulk-Over-The-Air (BOTA) transfer.

Parameters
[in]botaSenderBOTA Sender instance
[in]readFuncfunction to read the source bulk memory
[in]readAddraddress in the bulk memory where the source data starts
[in]sizesize of the bulk data to send (number of bytes)
[in]recipientAddrrecipient address - group addressing is allowed
[in]recipientPortrecipient port number
[in]transferInfouser-defined data that should describe the transfer contents to the recipient
[in]transferInfoSizesize of the transfer information (number of bytes)
[in]transferSpacepointer to a operational memory space required to handle the transfer
[in]transferSpaceSizesize of the provided transfer memory (number of bytes)
[in]transferPolicyoptional structure defining policies for the transfer (see BotaSenderTransferPolicy)
[in]onTransferAcceptedoptional callback function that will be called when the transfer is accepted by a node
[in]onTransferFinishedoptional callback function that will be called when the transfer is finished
[out]transferIdoptional place to store transfer identifier
Return values
BOTA_RESULT_OK- if the transfer was started successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT- if at least one of the input arguments was invalid
BOTA_RESULT_FAILED_TO_REGISTER_NEW_TRANSFER- if the transfer was not started because new transfer could not be registered (possibly too many transfers are ongoing)

◆ BOTA_SENDER_GetTransferStatus()

BotaSenderTransferStatus BOTA_SENDER_GetTransferStatus ( BotaSender * botaSender,
BotaTransferId transferId )

Gets BOTA transfer status.

This function retrieves the status of an ongoing BOTA transfer. The returned structure describes the current status of the transfer.

Note, that if the BotaSenderTransferStatus::transferState field is set to BOTA_SENDER_TRANSFER_STATE_UNKNOWN then the transfer was not found in the senders transfer list. Perhaps it was ended or the provided transferId was invalid. In such case BotaSenderTransferStatus::totalBytes and BotaSenderTransferStatus::transferredBytes are set to 0.

Parameters
[in]botaSenderBOTA Sender instance
[in]transferIdtransfer identifier, as returned by BOTA_SENDER_StartTransfer
Returns
structure describing the transfer status at the sender

◆ BOTA_SENDER_GetRecipientCount()

size_t BOTA_SENDER_GetRecipientCount ( BotaSender * botaSender,
BotaTransferId transferId )

Gets the number of recipients for an ongoing BOTA transfer.

This function gets the number of nodes that participate as recipients in the ongoing BOTA transfer.

Parameters
[in]botaSenderBOTA Sender instance
[in]transferIdtransfer identifier, as returned by BOTA_SENDER_StartTransfer
Returns
number of recipients

◆ BOTA_SENDER_GetRecipient()

BotaTransferRecipient * BOTA_SENDER_GetRecipient ( BotaSender * botaSender,
BotaTransferId transferId,
size_t index )

Gets the status of a single BOTA transfer recipient.

Parameters
[in]botaSenderBOTA Sender instance
[in]transferIdtransfer identifier, as returned by BOTA_SENDER_StartTransfer
[in]indexrecipient index (must be less than the value returned by BOTA_SENDER_GetRecipientCount)
Returns
pointer to a structure describing the status of the transfer recipient or NULL if there was no such recipient

◆ BOTA_SENDER_EndTransfer()

BotaResult BOTA_SENDER_EndTransfer ( BotaSender * botaSender,
BotaTransferId transferId )

Ends a BOTA transfer.

This function causes the given BOTA transfer to end.

If the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) or an error occurred (BOTA_SENDER_TRANSFER_STATE_ERROR) then this call removes the transfer from the BOTA transfer list, making space for other transfers.

If the transfer is ongoing then it is canceled.

Parameters
[in]botaSenderBOTA Sender instance
[in]transferIdtransfer identifier, as returned by BOTA_SENDER_StartTransfer
Return values
BOTA_RESULT_OK- if the transfer was ended successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT- if at least one of the input arguments was invalid

◆ BOTA_SENDER_RetryTransfer()

BotaResult BOTA_SENDER_RetryTransfer ( BotaSender * botaSender,
BotaTransferId transferId )

Restarts a BOTA transfer.

This function causes the given BOTA transfer to be restarted.

When the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) but (for example) not all recipients received the data, then the transfer can be retried.

Parameters
[in]botaSenderBOTA Sender instance
[in]transferIdtransfer identifier, as returned by BOTA_SENDER_StartTransfer
Return values
BOTA_RESULT_OK- if the transfer was retried successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT- if at least one of the input arguments was invalid

Contact us

Any question or remarks? Just write us a message!

Contact Information

Feel free to get in touch