Client SDK Documentation

Enumerations

KaltiotSmartState

KS_STATE_OFFLINE
KS_STATE_DISCONNECTING
KS_STATE_CONNECTING
KS_STATE_ONLINE

KaltiotSmartError

KS_ERROR_NO_ERROR
KS_ERROR_CONNECT_ERROR
KS_ERROR_GATEWAY_DISCONNECT
KS_ERROR_UNKNOWN
KS_ERROR_CLIENT_DISCONNECT

payload_type_t

KS_GW_CLIENT_PAYLOAD_BINARY
KS_GW_CLIENT_PAYLOAD_INT
KS_GW_CLIENT_PAYLOAD_STRING
KS_GW_CLIENT_PAYLOAD_PING
KS_GW_CLIENT_PAYLOAD_PONG

network_state_e

NETWORK_STATE_DISABLED
NETWORK_STATE_MOBILE_2G
NETWORK_STATE_MOBILE_3G
NETWORK_STATE_MOBILE_4G
NETWORK_STATE_MOBILE_5G
NETWORK_STATE_WIFI
NETWORK_STATE_COUNT

Functions

void ks_gw_client_notification_cb(const char *address, const char *payload, 

const uint16_t payload_length, const payload_type_t payload_type);

Callback function that is called when a notification is received. You should implement this.

ArgumentDescription
addressNull-terminated string.
payloadByte data.
payload_lengthLength of the payload.
payload_typeType of the payload.

 

void ks_gw_client_rid_cb(const char *address, const char *rid, const char *secret);

Callback function that is called when a rid is received. You should implement this.

ArgumentDescription
addressNull-terminated string.
rid

Null-terminated string.

Unique resource identifier for every iot application registered to Kaltiot Smart IoT. Using this

identifier you are able to send notifications to the iot application from Kaltiot Smart Rest api.

secretNull-terminated string.

 

void ks_gw_client_state_changed_cb(KaltiotSmartState state, KaltiotSmartError error);

Callback function that is called when the state of the daemon changes. You should implement this.

ArgumentDescription
statusStatus code that tells the new state.
errorPossible error code associated with the state.

 

extern bool ks_gw_client_connect(const char *path);

Connects to the daemon. Call this before registering. Returns true if the connection has been successfully established.

ArgumentDescription
path

The path or address to connect to. It is treated as a unix domain socket path

unless it has a colon in it, in which case the IPC will use local TCP on ip:port.

You can also leave it NULL, then the default path (/tmp/ks_client_socket)

will be used.

 

extern void ks_gw_client_disconnect();

Disconnects from the daemon.

extern void ks_gw_client_register_iot(const char *address, const char *version, 

const char *customer_id, const char **channels, uint16_t num_channels);

Registers with the daemon. App will start receiving notifications and other events.

NOTE: If you need to update the groups, you have to first unregister and then register again, with the different groups.

ArgumentDescription
addressAlphanumeric, null-terminated string.
version Alphanumeric, null-terminated string.
customer_id

Alphanumeric, null-terminated string. Identifier given by customer to the

IoT application registering to Kaltiot Smart IoT. Use this field to identify your IoT application

on gateway. It has to be unique for a given gateway. For example "sensor1".

channels

Array of alphanumeric, null-terminated strings that represent the

channels such as "temperature" or "motion".

num_channelsThe number of channels in the array.

 

extern void ks_gw_client_unregister_iot(const char *address, const char *version, const char *customer_id);

Unregisters from the daemon.

ArgumentDescription
address Alphanumeric, null-terminated string.
version Alphanumeric, null-terminated string.
customer_id Alphanumeric, null-terminated string.

extern void ks_gw_client_publish_message(const uint8_t *payload, const uint16_t payload_len, 

const payload_type_t payload_type);

Publishes a message to the server. 

If payload_type is KS_GW_CLIENT_PAYLOAD_STRING, payload and length should include the null terminator of the string.

ArgumentDescription
payloadByte data.
payload_lenLength of the payload.
payload_typeType of the payload.

 

extern void ks_gw_client_task();

Should be called periodically. It checks whether there is any data waiting to be read in the buffer, and based on said data calls the above callbacks.

extern void ks_gw_client_request_state();

Forces state_changed_cb to be called with the current state.

extern void ks_gw_client_request_rid();

Forces rid_cb to be called with the current rid info.

typedef void (*ks_app_id_callback) (const char *app_id, void *arg);

extern void ks_gw_client_request_app_id(ks_app_id_callback callback, void *arg);

Requests the application id from the daemon. The callback is called with the application id and an optional argument that the user can specify.

ArgumentDescription
callbackCallback function.
argOptional argument passed to the callback.

 

extern void ks_gw_client_set_engine_enabled(bool enabled);

Enables or disables the entire engine. Equivalent to closing the daemon.

ArgumentDescription
enabled 

 

extern void ks_gw_client_set_network_available(network_state_e state, const char *mcc, const char *mnc);

Sets the network status. MCC and MNC can be included with a mobile network state.

ArgumentDescription
stateThe new state.
mccCan be an empty null-terminated string, not NULL.
mncCan be an empty null-terminated string, not NULL.

 

Sample application

This can also be found in the client SDK package, in the sample_notification directory.

main.c
/**
 * This will connect to the daemon and register the application, then wait
 * for a notification to be received. After a notification is received, it
 * unregisters, disconnects and exits.
 */

#include "ks_gw_client.h"
#include <stdio.h>
#include <unistd.h>

static bool notification_received = false;

/* Callback receiving all incoming notifications. */
void ks_gw_client_notification_cb(const char *address, const char *payload,
                                const uint16_t payload_length,
                                const payload_type_t payload_type,
                                const char *msg_id,
                                const uint16_t msg_id_length) {
  notification_received = true;

  printf("notification received\n");
  printf("  type:    %d\n", payload_type);
  printf("  address: %s\n", address);
  printf("  payload: %.*s\n", payload_length, (const char *) payload);
}

/* Callback receiving all ks_gw_client connection state changes. */
void ks_gw_client_state_changed_cb(KaltiotSmartState state, KaltiotSmartError error) {
  printf("state changed\n");
  printf("  state: %d\n", state);
  printf("  error: %d\n", error);
}

/* Callback receiving unique RID for this device. */
void ks_gw_client_rid_cb(const char *address, const char *rid, 
                       const char *secret) {
  if (!address) address = "null";
  if (!rid) rid = "null";
  if (!secret) secret = "null";

  printf("rid received\n");
  printf("  address: %s\n", address);
  printf("  rid:     %s\n", rid);
  printf("  secret:  %s\n", secret);
}

/* Connect and run until a notification is received. */
int main(int argc, char const *argv[]) {
  char address[] = "sample_notification_address";
  char version[] = "1.2.3";
  char customer_id[] = "sample_notification_customer_id";

  char const *channels[] = { "sample_notification_channels" };
  uint16_t num_channels = 1;

  if (!ks_gw_client_connect(NULL)) {
    printf("failed to connect\n");
    return 1;
  }

  printf("  customer_id: %s\n", customer_id);
  ks_gw_client_set_engine_enabled(true);
  ks_gw_client_set_network_available(NETWORK_STATE_MOBILE_2G, "123", "45");
  ks_gw_client_register_iot(address, version, customer_id, 
                          channels, num_channels);
  ks_gw_client_request_rid();

  while (!notification_received) {
    ks_gw_client_task();
    sleep(1);
  }

  ks_gw_client_unregister_iot(address, version, customer_id);
  ks_gw_client_disconnect();
  printf("exiting application\n");
  return 0;
}