Table of Contents
This short tutorial shows how to use the BOTA Sender API in order to start and manage a BOTA transfer. For the purpose of this tutorial we will assume that we want to write a functional OS thread, that initializes and handles the BOTA Sender service. It will also start and manage a single transfer.
BOTA API follows an object-oriented style of programming. In order to use the BOTA Sender service we need its instance: BotaSender. First, the instance needs to be initialized through a call to BOTA_SENDER_Init. Next, the service is handled through a repeating call to BOTA_SENDER_Proc. Once the service is not needed, it can be deinitialized by a call to BOTA_SENDER_Deinit.
Let's start to write some thread code. In general the BOTA service thread will look like this:
The above code initializes and runs the service, but since there are no transfers defined it will mostly be IDLE code.
In order to start a BOTA transfer a call to BOTA_SENDER_StartTransfer is needed. But this call requires couple of things. We will discuss them one by one below:
BOTA Sender accesses the data to send through a callback 'read' function. The user is expected to provide an implementation of such function, allowing to access the data that should be send. Let's look at a simple example:
In the above example the 'botaSenderReadFunc' is the read function that reads from a static memory buffer 'bulkToSend'.
In order to define the Bulk Memory during the start of the transfer, the user code is expected to provide:
- 'readFunc' (as shown above)
- 'readAddr' - additional read offset in the bulk memory (for the above read function this address should be 0)
- 'size' - total size (in number of bytes) of the data to be sent
The recipient(s) of the transfer are defined using IPv6 address. This can be an unicast address or group address. If unicast addressing is used, then there is only one expected recipient. In case of group addressing there might potentially be many recipients. The recipient address is provided as 'recipientAddr' in the call to BOTA_SENDER_StartTransfer.
When the transfer is started we can pass additional information describing it. This information is user-defined and can contain up to 32 bytes. In the above example we've used a simple string containing "testTransfer".
In order to handle multiple recipients the BOTA Sender instance needs additional operational memory called 'transfer space'. This memory is provided through the following arguments of the BOTA_SENDER_StartTransfer call:
- transferSpace - pointer to the transfer space size
- transferSpaceSize - size (in number of bytes) of the transfer space
You can use the BOTA_SENDER_GetRequiredTransferSpaceSize call to determine how much memory is needed in order to handle a given number of recipients. The code below illustrates this idea:
As an option we can define two additional callbacks, that will inform about some important events during the BOTA transfer:
- onTransferAccepted - is a callback that will be called each time a new recipient accepts an incoming transfer
- onTransferFinished - is a callback that will be called once the transfer is done
Some exemplary callback implementation is shown below:
Note that we must explicitly end the transfer by a call to BOTA_SENDER_EndTransfer. In the above example this is done in the onTransferFinished callback.
The BOTA_SENDER_EndTransfer can also be called to end and ongoing transfer.
The example below merges all the above code into a thread that runs the BOTA Sender service and starts a single transfer.
At any point after starting the transfer it is possible to poll the transfer status using BOTA_SENDER_GetTransferStatus function. Also it is possible to retrieve the current number of transfer recipients and basic information about each recipient using BOTA_SENDER_GetRecipientCount and BOTA_SENDER_GetRecipient functions. The example below illustrates the usage.
Note that once we end the transfer through a call to BOTA_SENDER_EndTransfer we no longer can poll its status.
Generated on Tue Nov 23 2021 17:06:01 for BOTA Bulk-Over-The-Air service by 1.9.1