Agent Variables

---

Introduction

To aid platform and algorithm developers with agent-specific knowledge tracking, GAMS provides interfaces to track common agent/agent variables like battery, location in a 3D coordinate plane, commands, and movement vector information. In this wiki page, we cover the agent-specific variables, what they are meant to track and where to find them in the Knowledge Base, a platform or an algorithm.

---

Command Variables (Algorithms)

Algorithms in GAMS can be instantiated in one of two ways: 1) by directly initializing an algorithm in a program or 2) changing MADARA variables from a remote application over a network. The first option is the most likely for custom algorithms and platforms. However, the second option, via command variables on the agent, is a very effective and versatile option for starting GAMS provided algorithms.

There are two components to command variables: 1) the command and 2) the arguments to the command. In GAMS, this message to a agent is done via variables in the Knowledge Base prefixed by agent.{.id}.command. The command itself is agent.{.id}.command. The number of arguments to this command is specified in agent.{.id}.command.size, and the arguments to the command are specified in agent.{.id}.command.0 -> agent.{.id}.command.{agent.{.id}.command.size-1}.

Example of Setting Command Variables via Command Line Using Multicast

%MADARA_ROOT%\bin\karl -m 239.255.0.1:4150 "agent.1.command='cover';agent.1.command.size=2;agent.1.command.0='urac';agent.1.command.1='region.0'"

The above assumes region.0 has been set. See Regions wiki for more information on defining regions.

C++ Example of Setting Command Variables Remotely Using Multicast

// include relevant GAMS and MADARA headers
#include "gams/controllers/Base_Controller.h"
#include "madara/utility/utility.h"

// create shortcuts to MADARA classes and namespaces
namespace engine = madara::knowledge;
namespace transport = madara::transport;
namespace controllers = gams::controllers;
namespace utility = madara::utility;

// perform main logic of program
int main (int argc, char ** argv)
{
  // Define network transport settings for multicast
  transport::QoS_transport_Settings settings;
  settings.hosts.push_back ("239.255.0.1:4150");
  settings.type = madara::transport::MULTICAST;

  // create knowledge base and a control loop
  engine::Knowledge_Base knowledge ("", settings);

  // send a command for random area coverage to agent 1
  knowledge.evaluate (

    // the algorithm command is specified via .command
    "agent.1.command='cover';"

    // the number of arguments to the command is specified via .size
    "agent.1.command.size=2;"

    // coverage requires a type of coverage and the region to cover
    "agent.1.command.0='urac';"
    "agent.1.command.1='region.0';"

    // define region.0
"
region.0.type=0;            // type 0 is a polygon, currently the only defined type
region.0.size=4;            // four vertices define this polygon
region.0.0[0]=40.443237;    // latitude of point 0
region.0.0[1]=-79.940570;   // longitude of point 0
region.0.1[0]=40.443387;
region.0.1[1]=-79.940270;
region.0.2[0]=40.443187;
region.0.2[1]=-79.940098;
region.0.3[0]=40.443077;
region.0.3[1]=-79.940398"

  );

  // sleep for 1s
  utility::Sleep (1.0);

  return 0;
}

The above assumes region.0 has been set. See Regions wiki for more information on defining regions.

---

Status Variables

1. Battery life is stored in agent.{.id}.battery as an integer
2. Location is stored in agent.{.id}.location as an array of 3 doubles [x, y, z]
3. Home location (where to return to if instructed to return home) is stored in agent.{.id}.home as an array of 3 doubles [x, y, z]
4. The source of the current movement is stored in agent.{.id}.source as an array of 3 doubles [x, y, z]
5. The destination of the current movement is stored in agent.{.id}.dest as an array of 3 doubles [x, y, z]
6. A mobility flag for the agent is stored in agent.{.id}.mobile. If non-zero, the agent is capable of moving. If zero, the agent is incapable of moving.
7. A business flag for the agent is stored in agent.{.id}.busy. If non-zero, the agent is busy and not accepting new commands.

---

Feedback Variables

Several variables within agent.{.id} are special and are mini-commands for managing what the agent does. The following table details the feedback variables for changing specific agent characteristics at runtime (i.e., after they are running).

Key	Value
loop_hz	The controller loop hertz for executing algorithms
send_hz	The controller send hertz for aggregating knowledge updates and sending them over the transports
madara_debug_level	The logging level (0-7) for logging MADARA messages
gams_debug_level	The logging level (0-7) for logging GAMS messages