BOTA Sender API

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  BOTA_PACKED
 Structure defining the TRANSFER.request packet. More...
 
struct  BotaTransfer
 Structure describing a single BOTA transfer. More...
 
struct  BotaSender
 Structure describing BOTA Sender instance. More...
 

Macro Definition Documentation

◆ BOTA_MAX_TRANSFERS

#define BOTA_MAX_TRANSFERS   10

Maximum number of simultaneous transfers that is supported.

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

◆ BotaRecipientState

Type describing the state of the recipient.

◆ BotaTransferRecipient

Structure describing the status of the recipient.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
BOTA_CONFIG_TRANSFER_REQUEST_SENDING_DELAY_MS 

TRANSFER.request sending delay.

BOTA_CONFIG_TRANSFER_DATA_SENDING_DELAY_MS 

BULK_WRITE.request sending delay, limits the overall data transfer.

BOTA_CONFIG_TRANSFER_VALIDATE_REQUEST_SENDING_DELAY_MS 

VALIDATE.request sending delay.

◆ BOTA_PACKED

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_SUCCESS 

Recipient successfully received the transfer.

BOTA_RECIPIENT_STATE_FAILED 

Recipient received the transfer but CRC validation failed.

Function Documentation

◆ BOTA_STATIC_ASSERT()

BOTA_STATIC_ASSERT ( sizeof(BotaTransferRecipient = =9,
"sizeof(BotaTransferRecipient) should be 9"   
)

◆ 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.
[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,
const void *  transferInfo,
size_t  transferInfoSize,
void *  transferSpace,
size_t  transferSpaceSize,
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]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()

BotaTransferStatus 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 BotaTransferStatus::transferState field is set to BOTA_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 BotaTransferStatus::totalBytes and BotaTransferStatus::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

◆ 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()

void 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_TRANSFER_STATE_FINISHED) or an error occurred (BOTA_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
Go to Top