Please Wait

Loading..

ESP32 SDK 1.2.0

Create amazing realtime applications easily with Yalgaar ESP32 SDK

1 Connect To Yalgaar

Note:

There is no support for AES Encryption feature.

Pre configuration required

Pre configurations will be required as per user’s need before implementing application with MQTT. These configuration can be done with “make menuconfig”. These will include changing MQTT task priority, task size and secure connection selection option.

   make menuconfig → Component config → Yalgaar

Structures are used in Get user list, Get channel list and presence message callback

  • Structure for get channel list and user list.
     typedef struct sll
    {
    	char **list;
    	uint8_t low_range;
    	uint8_t high_range;
    }sll;
  • Presence information structure
     typedef struct presence_t
    {
    	char uuid[50];
    	bool action;
    	char channel[50];
    }presence_t;


Download package and include "yalgaar_api.h" in your code.

#include "yalgaar_api.h"

To connect to a Yalgaar client, use following method, it must have valid Client Key.

int yalgaar_connect(char* clientKey,char* uuid, void(*connection_callback)(char*), bool isHexString);

Parameter:

  • clientKey
    • Description: Yalgaar provided authentic client key for project.
    • DataType: char*
  • uuid
    • Description: Any unique user name for user to enable presence feature for client. UUID is CASE SENSITIVE and only alpha numeric, hyphens,@,underscore allowed and maximum length must be 50.
    • DataType: char*
  • connectionCallback
    • Description: Called when successfully connected to server or any error during connection.
    • DataType: void
  • IsHexString
    • Description: 1 if data will transfered as a Hex data, This will convert string data as Hex while publishing. If 0, data will be send as string.
    • DataType: bool
  • Note: Connection successful status string will be provided in callback function.


2 Publish Message

Use following method to publish data on given channel.

int yalgaar_publish(char *channel, char *data, int len);

Parameter:

  • Channel
    • Description: Channel name on which message will be published. Channel name is CASE SENSITIVE. Only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • data
    • Description: Data to be send on given channel.
    • DataType: char *
  • len
    • Description: Data length on given channel.
    • DataType: int
  • Note: Publish error string will be provided in connectionCallback.


3 Subscribe Message

To subscribe message on channel, use following method.

int yalgaar_subscribe(char *channel, void (*sub_msg_callback)(char*,int,char*), void (*presence_msg_callback)(presence_t*));
int yalgaar_subscribes(char **channels,uint8_t channels_number,void (*sub_msg_callback)(char*,int,char*),void (*presence_msg_call)(presence_t*));

Parameter:

  • channel
    • Description: channel name on which message will be subscribed. Channel name is CASE SENSITIVE. For multiple channel names use "yalgaar_subscribes" function with array. Only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • channels_number
    • Description: number of channels to be subscribe.
    • DataType: uint8_t
  • sub_msg_callback
    • Description: Callback function to consume received message. sub_msg_callback(char * data, int len, char* channel) where, data: Subscribed channel data, Len : data length and channel: channel name
    • DataType: void
  • presence_msg_callback
    • Description: Callback function to consume presence events such as join or leave. presence_msg_callback(presence_t *data) where, data will be presence_t type structure.
    • DataType: void
  • Note: subscribe error string will be provided in connection Callback. Number of maximum subscribe channels is 10 as of now.


4 Unsubscribe Message

To unsubscribe channel, use following method.

void yalgaar_unsubscribe(char *channel);
  • channel
    • Description: Channel name to be unsubscribe. Only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • Note: Unsubscribe error string will be provided in connection Callback


5 History Message

To get message history from specified channel name, use following method.

int yalgaar_GetHistoryMessage(char *channelName,int messageCount, void(*history_msg_callback)(char**,int));
  • channelName
    • Description: Valid channel name. Channel name is CASE SENSITIVE and only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • messageCount
    • Description: How many messages that you want to fetch. Maximum 100 messages allow at a time.
    • DataType: int
  • history_msg_callback
    • Description: Callback is called when successfully get history message list. history_msg_callback(char ** data, int messageCount); where, data: list of history messages and messageCount: number of history messages.
    • DataType: void
  • Note: User may need to provide higher Network buffer size for MQTT in make menuconfig get this feature working properly.


6 Get User List

To get list of all user subscribe with specified channel name, use following method.

int yalgaar_GetUserList(char *channelName,void (*userlist_callback)(sll*));
  • channelName
    • Description: Valid channel name. Channel name is CASE SENSITIVE and only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • userlist_callback
    • Description: Callback is called when successfully get user list. userlist_callback (sll * data); where, data will be structure pointer type sll
    • DataType: void
  • Note: User list provided in chunk of 10 users. e.g if total numbers of user associated with given channel is 25, then first 10 numbers of user list will be provided in callback with low_range=1 and high_range=10, then another 10 users with low_range=11 and high_range=20 and then remaining 5 users uuid list with low_range=21 and high_range=25 will be provided in the callback.


7 Get Channel List

To get list of all channels subscribed by specified user, use following method.

int yalgaar_GetChannelList(char *uuid,void(*channel_list_callback)(sll*));
  • uuid
    • Description: Description: Any unique user name or user id. UUID is CASE SENSITIVE and only alpha numeric, hyphens, @, underscore allowed and maximum length must be 50.
    • DataType: char *
  • channel_list_callback
    • Description: Callback is called when successfully get channel list. channelListCallback(sll* data); where, data will be structure pointer type sll
    • DataType: void
  • Note: Same as mentioned in Get User List, channel list will be also provided in chunk of 10 channels at a time.


8 Disconnect

To disconnect connection with YalgaarClient, use following method.

void yalgaar_disconnect();
  • Note: Please ensure that all this APIs are not called without sufficient delay between them, otherwise there may be possible that unwanted scheduling issues created.


You can publish/subscribe message like so :

#include "yalgaar_api.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_system.h"

#define TAG "Yalgaar_sdk"

void sub_msg_fun (char *data,int len, char* channel);
void presence_fun(presence_t * data)
{
	ESP_LOGI(TAG,"Presence uuid : %s",data->uuid);
	ESP_LOGI(TAG,"Presence channel : %s",data->channel);
	ESP_LOGI(TAG,"Presence action : %d",data->action);
	ESP_LOGI(TAG,"heap: %d",esp_get_free_heap_size());
}
void connect_done(char* arg)
{
	char test_data[]="This is Yalgaar ESP32 SDK Example.";
	if(strcmp(arg,"Connection Successful") == 0)
	{
		ESP_LOGI(TAG,"connection successful arg : %s",arg);
		/* subscribe channel	*/
		if(yalgaar_subscribe("YourChannel", sub_msg_fun, presence_fun)== ESP_FAIL)
		{
			ESP_LOGE(TAG,"chaneel test not subscribed");
		}
		/*	publish on channel	*/
		if(yalgaar_publish("YourChannel",&test_data,strlen(test_data))== ESP_FAIL)
		{
			ESP_LOGE(TAG,"Yalgaar Publish fail");
		}
	}
	ESP_LOGE(TAG,"Yalgaar ERROR : %s",arg);	
 }
 
void sub_msg_fun (char *data,int len, char* channel)
{
	ESP_LOGI(TAG,”Data Received from channel : %s”,channel);
	ESP_LOGI(TAG,”Data : %s",(char*)data);			
}

void yalgaar_demo_task(void *p)
{
	/*	connect yalgaar client	*/
	int c=yalgaar_connect("YourClientKey","UUID",connect_done,0);
	if(c == ESP_FAIL)
	{
		ESP_LOGE(TAG,"Yalgaar Connection failed");
	}
	vTaskDelete(NULL);
}