DashboardClient

For CB3 robots and PolyScope 5 the DashboardClient wraps the calls on the Dashboard server directly into C++ functions.

For PolyScope X the so-called Robot API released with PolyScope X 10.11.0 is used. It offers a subset of the Dashboard Server from previous software versions.

After connecting to the dashboard server by using the connect() function, dashboard calls can be done using the command...() functions such as commandCloseSafetyPopup(). These functions are blocking and will wait for the necessary action being done. This can involve querying another call to the dashboard server until the action is done. For example, commandPowerOn() will block until the robot reports “Robotmode: RUNNING” or the given timeout is reached.

The return value of those functions indicate whether or not the call was successful. If you want to get the call’s full response, use the command...WithResponse() calls, instead. They will return a response struct

Listing 3 urcl::DashboardResponse

struct DashboardResponse
{
  bool ok = false;
  std::string message;
  std::unordered_map<std::string, std::variant<std::string, int, bool, std::vector<ProgramInformation>>> data;
};

The data dictionary of that response struct is populated by each command individually. See the commands’ docstrings for details.

The dashboard_example.cpp shows how to use the dashboard client:

Listing 4 examples/dashboard_example.cpp

  auto my_dashboard = std::make_unique<DashboardClient>(robot_ip, policy);
  if (!my_dashboard->connect())
  {
    URCL_LOG_ERROR("Could not connect to dashboard");
    return 1;
  }

  bool robot_in_remote_control = false;
  // CB3 doesn't have remote control
  if (version_information->major >= 5)
  {
    robot_in_remote_control = my_dashboard->commandIsInRemoteControl();
  }

  // Bring the robot to a defined state being powered off.
  if (version_information->major < 10)
  {
    if (!my_dashboard->commandPowerOff())
    {
      URCL_LOG_ERROR("Could not send power off");
      return 1;
    }
    // Get the PolyScope version
    std::string version;
    my_dashboard->commandPolyscopeVersion(version);
    URCL_LOG_INFO(version.c_str());

    my_dashboard->commandCloseSafetyPopup();
  }
  else if (robot_in_remote_control)
  {
    // We're ignoring errors here since
    // powering off an already powered off robot will return an error.
    my_dashboard->commandPowerOff();
  }

  // Power it on
  if (version_information->major < 10 || robot_in_remote_control)
  {
    if (!my_dashboard->commandPowerOn())
    {
      URCL_LOG_ERROR("Could not send Power on command");
      return 1;
    }

    // Release the brakes
    if (!my_dashboard->commandBrakeRelease())
    {
      URCL_LOG_ERROR("Could not send BrakeRelease command");
      return 1;
    }

    // Load existing program
    std::string program_file_name_to_be_loaded("wait_program.urp");
    if (version_information->major >= 10)
    {
      // For PolyScope X, the program doesn't have an ending
      program_file_name_to_be_loaded = "wait_program";
    }
    if (!my_dashboard->commandLoadProgram(program_file_name_to_be_loaded))
    {
      URCL_LOG_ERROR("Could not load %s program", program_file_name_to_be_loaded.c_str());
      return 1;
    }

    std::this_thread::sleep_for(std::chrono::seconds(1));

    // Play loaded program
    if (!my_dashboard->commandPlay())
    {
      URCL_LOG_ERROR("Could not play program");
      return 1;
    }

    // Pause running program
    if (!my_dashboard->commandPause())
    {
      URCL_LOG_ERROR("Could not pause program");
      return 1;
    }

    // Continue
    if (version_information->major >= 10)
    {
      // For PolyScope X, the command is called "resume"
      if (!my_dashboard->commandResume())
      {
        URCL_LOG_ERROR("Could not resume program");
        return 1;
      }
    }
    else
    {
      // For e-Series, the command is called "play"
      if (!my_dashboard->commandPlay())
      {
        URCL_LOG_ERROR("Could not resume program");
        return 1;
      }
    }

    // Stop program
    if (!my_dashboard->commandStop())
    {
      URCL_LOG_ERROR("Could not stop program");
      return 1;
    }

    // Power it off
    if (!my_dashboard->commandPowerOff())
    {
      URCL_LOG_ERROR("Could not send Power off command");
      return 1;
    }

    if (version_information->major < 10)
    {
      // Flush the log
      if (!my_dashboard->commandSaveLog())
      {
        URCL_LOG_ERROR("Could not send the save log command");
        return 1;
      }

      // Make a raw request and save the response
      std::string program_state = my_dashboard->sendAndReceive("programState");
      URCL_LOG_INFO("Program state: %s", program_state.c_str());

      // The response can be checked with a regular expression
      bool success = my_dashboard->sendRequest("power off", "Powering off");
      URCL_LOG_INFO("Power off command success: %d", success);
    }
  }

  return 0;

CB 3 and PolyScope 5 only

All commands are blocking and will wait for the necessary action being done. The dashboard server’s response will be compared with an expected response. For example, when calling commandPowerOn(timeout), it is checked that the dashboard server is answering "Powering on" and then it is queried until the robot reports "Robotmode: IDLE" or until the timeout is reached. The example contains more commands that follow the same scheme.

If you want to send a query / command to the dashboard server and only want to receive the response, you can use the sendAndReceive() function:

Listing 5 examples/dashboard_example.cpp

      // Make a raw request and save the response
      std::string program_state = my_dashboard->sendAndReceive("programState");
      URCL_LOG_INFO("Program state: %s", program_state.c_str());

For checking the response against an expected regular expression use sendRequest():

Listing 6 examples/dashboard_example.cpp

      // The response can be checked with a regular expression
      bool success = my_dashboard->sendRequest("power off", "Powering off");
      URCL_LOG_INFO("Power off command success: %d", success);

PolyScope X only

Internally, the dashboard client makes calls against a RESTful (Representational State Transfer) API. Hence, all responses contain a JSON-encoded string of the received answer. For example, an answer to a pause request could be

{"state":"PAUSED","message":"Program state changed: PAUSED","details":"Pause successful"}