Working with IoTC Agent CLI

The IoTC Agent CLI tool is a wrapper around the IoTC Agent's default client binary DefaultClient.

This tool provides a command-line interface (CLI) to perform IoTC Agent SDK operations. With the IoTC Agent CLI tool, you can build a client that operates with VMware Pulse IoT Center using the IoTC Agent SDK. You can use the DefaultClient binary as a reference for building your client.

The IoTC Agent CLI tool provides the following CLI options:

/opt/vmware/iotc-agent/bin# ./iotc-agent-cli help
Usage:
DefaultClient <command> <params>
 
Available commands and parameters:
enroll
        --auth-type=REGISTERED --token=<authentication token>
enroll
        --auth-type=PROPERTY --key=<property key> --value=<property value>
enroll
        --auth-type=BASIC --template=<template name> --name=<gateway name>
        --username=<user name> [ --password=<prompt|file:<path>> ]
enroll-device
        --device-id=<device Id> --parent-id=<parent Id>
enroll-device
        --template=<template name> --name=<device name>
        --parent-id=<parent Id>
unenroll
        --device-id=<device Id>
schedule
        --type=<download|execution|activation>
        --campaign-id=<campaign Id>
        [ --start-time=<start time window> --end-time=<end time window> ]
get-commands
send-notification
        --entity-id=<entity Id> --definition-id=<definition Id>
        --key=<key> --value=<value>
send-metric
        --device-id=<device Id> --name=<metric name>
        --type=<string|integer|double|boolean> --value=<value>
        [ --device-id=<device2 Id> ... ]
set-progress
        --campaign-id=<campaign Id> --progress=<progress string>
send-properties
        --device-id=<device Id> --key=<key> --value=<value>
        [ --key=<key2> --value=<value2> ... ]
get-properties
        --device-id=<device Id> --type=<system|custom>
start-daemon
        [ --config=<config file> ]
        [ --interval=<overriding metric interval> ]
stop-daemon
        [ --config=<config file> ]
sync
get-devices
        [ --parent-id=<Parent Id> ]
 
Note: Parameter names can be shortened as long as they are unique.

Use the IoTC Agent CLI tool to perform operations such as enrolling a device and setting properties for a device quickly.

Note:

Declare the library path explicitly if you see error messages such as: “ error while loading shared libraries: libiotc-agent-sdk.so: cannot open shared object file: No such file or directory”. Run the following command:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/vmware/iotc-agent/lib/

The IoTC Agent CLI tool is available in the bin directory of IoTC Agent: /opt/vmware/iotc-agent/bin/iotc-agent-cli.

DefaultClient in the IoTC Agent Package

The IoTC Agent package consists of a directory that contains the source code of the DefaultClient binary file and a makefile to build your client. You can modify this source code according to your requirement. The IoTC Agent package also contains a wrapper script to run DefaultClient. The iotc-agent/example/ directory contains the following files:

client
DefaultClient.c
DefaultClient.h
DefaultClientDaemon.c
base64.c
Makefile

Using the DefaultClient Daemon

You can run the DefaultClient binary file as a daemon process in the background. In the daemon mode, DefaultClient connects to the IoTC Agent daemon and authorizes campaign call-backs automatically. It also fetches commands from the server at regular intervals. When additional options are specified, DefaultClient gathers the default CPU and Memory Usage metrics from the Gateway device and sends them periodically. You can perform the following operations using the DefaultClient daemon:

Start the DefaultClient daemon without sending the default metrics:
```
$ DefaultClient start-daemon
```

Start the DefaultClient daemon with default metrics every 10 minutes:

$ DefaultClient start-daemon --device-id=<device_id> --interval=600

Stop the DefaultClient daemon.
```
$ DefaultClient stop-daemon
```

Using the IoTC Agent connection, the DefaultClient daemon accepts requests from the following pipe files if necessary:

/tmp/iotc-defclient/input for an input request.
/tmp/iotc-defclient/output for an output request.

The following sample illustrates how to get system properties using the DefaultClient daemon:

$ echo "get-properties --device-id=13c425e1-873a-43f0-a529-cb05289a8a40 --type=system" > /tmp/iotc-defclient/input
$ cat /tmp/iotc-defclient/output

Send Metrics API Example

The following client program demonstrates the use of the Send Metrics API:

/* ****************************************************
 * Copyright (C) 2019 VMware, Inc. All rights reserved.
 * -- VMware Confidential
 * ***************************************************/
 
/**
 * @file ExampleMetric.c
 * @brief This file contains simple example code to demonstrate use of
 * iotc-agent-sdk send metrics API.
 *
 */
 
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/time.h>
#include <unistd.h>
#include <sys/sysinfo.h>
 
#include "iotcAgent.h"
 
/* This sample client's application id */
#define TEST_CLIENT_ID "com.agent.test.metric"
#define MEM_USAGE "Memory-Usage"
/* timeout for waiting response from agent (in milliseconds) */
#define CLIENT_TIMEOUT  30000
 
 
/**
 * Return the current time in number of milliseconds since UNIX
 * epoch time.
 * @return A uint64_t that represents the current time.
 */
static uint64_t GetTimeStampMs(void)
{
   struct timeval timeVal = {.tv_sec = 0, .tv_usec = 0};
   uint64_t timeStamp;
 
   gettimeofday(&timeVal, NULL);
   //use milliseconds. Make sure the constants are unsigned long
   //long so that the computation does not overflow.
   timeStamp = (timeVal.tv_sec * 1000ULL) + (timeVal.tv_usec / 1000ULL);
 
   return timeStamp;
}
 
 
int main(int argc, char *argv[])
{
   IotcSession *session;
   IotcApplicationId clientAppId;
   struct sysinfo si;
   double memUsage;
   IotcMetric *memMetric;
   IotcGetResponse getResponse;
   int status;
 
   if (argc != 2) {
      printf("Usage: %s <deviceId>\n", argv[0]);
      return 1;
   }
 
   strncpy(clientAppId.id, TEST_CLIENT_ID, sizeof clientAppId.id);
 
   /* Initialize a session with the iotc-agent sdk */
   session = Iotc_Init(&clientAppId);
   if (session == NULL) {
      printf("Iotc_Init() failed");
      return -1;
   }
 
   /* Create a memory metric object */
   memMetric = malloc(sizeof (*memMetric) + sizeof (IotcDoubleValue));
   strncpy(memMetric->deviceId.id, argv[1],
           sizeof memMetric->deviceId.id);
   memMetric->deviceId.id[sizeof memMetric->deviceId.id - 1] = '\0';
   strncpy(memMetric->name, MEM_USAGE, sizeof memMetric->name);
   memMetric->name[sizeof memMetric->name - 1] = '\0';
   memMetric->type = IOTC_METRIC_DOUBLE;
 
   while (1) {
      if (sysinfo(&si) < 0) {
         printf("Error reading sysinfo\n");
         break;
      }
 
      /* Get the memory metric data */
      memUsage = (double) (si.totalram - si.freeram) * (double) 100 / (double) si.totalram;
      printf("mem: total=%ld free=%ld\n", si.totalram, si.freeram);
      memMetric->doubles[0].ts = GetTimeStampMs();
      memMetric->doubles[0].value = memUsage;
      /* Send the collected metric data */
      Iotc_SendMetric(session, memMetric);
      /* Get response for the send metric data */
      status = Iotc_GetResponseByType(session, IOTC_SEND_METRIC, CLIENT_TIMEOUT, &getResponse);
      if (status == -1) {
         fprintf(stderr, "Failed receiving send metric response\n");
      }
 
      Iotc_FreeGetResponse(&getResponse);
      sleep(5); // for 5 seconds
   }
 
   free(memMetric);
   /* Close the session with the agent */
   Iotc_Close(session);
   return 0;
}