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.

Argument	Description
address	Null-terminated string.
payload	Byte data.
payload_length	Length of the payload.
payload_type	Type 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.

Argument

Description

address

Null-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.

secret

Null-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.

Argument	Description
status	Status code that tells the new state.
error	Possible 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.

Argument	Description
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.

Argument	Description
address	Alphanumeric, 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_channels	The 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.

Argument	Description
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.

Argument	Description
payload	Byte data.
payload_len	Length of the payload.
payload_type	Type 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.

Argument	Description
callback	Callback function.
arg	Optional 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.

Argument	Description
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.

Argument	Description
state	The new state.
mcc	Can be an empty null-terminated string, not NULL.
mnc	Can 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;
}