# Methods and Callbacks

### **Methods:** 

1. <mark style="color:blue;">**trill\_data\_link\_cb\_t :**</mark> Function for datalink callback event

eg- (*trill\_data\_link\_cb\_t)(const trill\_data\_link\_event\_params\_t* params);

*<mark style="color:blue;">**trill\_data\_link\_event\_params\_t**</mark>* <mark style="color:blue;">:</mark> <mark style="color:blue;"></mark><mark style="color:blue;">**Data Link layer callback parameters containing:**</mark>&#x20;

1. **event :**&#x45;vent code. Refer to trill\_data\_link\_event\_t&#x20;
2. **payload:** Payload data. Pointer should not be used after returning from this callback.
3. **payload\_len:** Length of the payload in bytes.&#x20;
4. **ssi:** Security scheme that was used for this packet.&#x20;
5. **data\_cfg\_range:** Range Config of received data.&#x20;
6. **user\_data:** User provided data.&#x20;
7. **channel:** which channel the data was received from.&#x20;

2\. <mark style="color:blue;">**trill\_init**</mark> <mark style="color:blue;"></mark><mark style="color:blue;">:</mark> This method should be called to Initialise the SDK.

&#x20; **This is also the first function to be called before SDK can be used.**

* @param init\_opt Initialization options. Refer to trill\_init\_opts\_t
* @param handle SDK Handle. Preserve it to pass with other calls.

**Return:** int 0 on success else negative error code.

3\. *<mark style="color:blue;">**int trill\_process(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle)**</mark>: Rx path processing function. Call from a separate task/thread in a loop. Refer to example code.

Processing state:

* TRILL\_PROC\_CTS\_SEARCH = CTS Hunting mode.
* TRILL\_PROC\_DEMOD\_PROGRESS = Demodulation in progress.
* TRILL\_PROC\_MOD\_PACKET\_SENT = Modulated packet was sent.
* Negative error code.&#x20;

**Return:** int&#x20;

4\. *<mark style="color:blue;">**int trill\_add\_audio\_block(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle, const void\* block):**</mark> Call when next Rx audio block is available. The block size should be same as given in the SDK initialization options. This function can be called from ISR.

* @param block Block data address. Block can be reused after call returns.

**Return:** int 0 on success else negative error code.&#x20;

5\.  *<mark style="color:blue;">**int trill\_acquire\_audio\_block(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle, short\*\* addr, int en\_blocking)**</mark>: Call when next Tx audio block can be sent This function will not block even when no Tx block is available from audio buffer, when this scenario occurs it will lead to Tx underrun.

This function can be called from ISR.&#x20;

The size of the acquired block is same as given in the SDK initialization options.

* @param addr Address of the block inside the audio buffer.\
  Caller should copy the data and call trill\_release\_audio\_block.
* @param en\_blocking If non-zero, call will block until audio block is available.\
  Set to zero if calling from ISR. Set to non-zero if calling from task/thread.

**Return:**  int 0 on success else TRILL\_ERR\_AUDIO\_TX\_BLOCK\_NOT\_AVAILABLE when no Tx block is available.&#x20;

6\. *<mark style="color:blue;">**int trill\_release\_audio\_block(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle)**</mark>: Call after successfully acquiring a Tx audio block to return it to Tx audio buffer.

**Return:** int&#x20;

7\. *<mark style="color:blue;">**int trill\_tx\_data(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle, trill\_tx\_params\_t\* security\_params, unsigned char\* data, unsigned int data\_len)**</mark> <mark style="color:blue;"></mark><mark style="color:blue;">:</mark>&#x20;

Send Tx Packet. Call it from a task/thread other than the one being used to call trill\_process\_input / trill\_process\_output functions.

When this function returns success, packet is prepared but not yet sent. When sent successfully data link layer will send notification callback

* @param security\_params Refer to trill\_tx\_params\_t
* @param data Payload data to be sent. data pointer can be reused after the function returns.
* @param data\_len Payload size in bytes.

**Return**: int 0 on packet accepted to be sent else negative error code.&#x20;

8\. *<mark style="color:blue;">**trill\_tx\_abort(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle)**</mark>: Abort Tx data if in progress or about to be sent. Even after successful abort there might be unread audio blocks in audio buffer. These need to be flushed out by application.

* @param handle

**Return:** int 0 on success else negative error code.&#x20;

9\. *<mark style="color:blue;">**int trill\_get\_device\_id(const char**</mark>*<mark style="color:blue;">**\* buf)**</mark> : Retrieve the device ID of this MCU as represented by SDK internally. Use the retrieved device id for data exchange with server APIs.

* @param buf Address of the buffer to receive null terminated device id string.

**Return:** int 0 on success else negative error code.&#x20;

10\. *int trill\_is\_device\_verified(void* handle): brief Can be used to verify whether device License is valid.

**Return:** int Positive number if License is valid else 0. */*&#x20;

11\. <mark style="color:blue;">**t**</mark>*<mark style="color:blue;">**rill\_deinit(void**</mark>*<mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**handle)**</mark><mark style="color:blue;">:</mark> DeInitialize the SDK and release all memories.

* @param handle

**Return:** int error code&#x20;

Please refer to [troubleshooting guide](https://trillbit.gitbook.io/trillbit-sdk/esp-32-support/trill-sdk-for-esp-32/troubleshooting) for the errors that can be returned by the above methods.