Skip to content

Commit

Permalink
Feature/reorganize examples (#20)
Browse files Browse the repository at this point in the history 
* Re-organize C++ and Python examples to group into basics and intermediate tutorials

* Add zero force torque sensor tutorial

* Add description print for all tutorials

* For intermediate tutorials, move to home pose if possible before any motions

* Update motion force control example to use base frame by default

* Increase command frequency lower bound from 1Hz to 20Hz for non-real-time motion control tutorials

* Update README: change Visual Studio minimum required version from 2010 to 2015

* Update README: change CMake minimum required version from 3.4 to 3.16.3

* Update README: improve compilation steps
  • Loading branch information
@pzhu-flexiv
pzhu-flexiv authored May 2, 2023
1 parent 919d489 commit a9931cb
Show file tree
Hide file tree
Showing 27 changed files with 1,283 additions and 683 deletions.
46 changes: 26 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,52 +25,58 @@ Flexiv RDK (Robotic Development Kit), a key component of the Flexiv Robotic Soft

The C++ interface of Flexiv RDK is packed into a unified modern CMake library named ``flexiv_rdk``, which can be configured via CMake on all supported OS.

NOTE: if you will only be using Python RDK, you can skip this section and jump to [Python RDK](#python-rdk).

#### Compile and install for Linux

1. In a new Terminal, use ``cmake-gui`` to configure the top-level ``flexiv_rdk`` CMake project:
1. In a new Terminal, install C++ compiler, Git, and CMake (with GUI) using the package manager:

sudo apt install build-essential git cmake cmake-qt-gui -y

2. Choose a directory for installing ``flexiv_rdk`` library and all its dependencies. For example, a new folder named ``rdk_install`` under the home directory.
3. In a new Terminal, use CMake to configure ``flexiv_rdk``:

cd flexiv_rdk
mkdir build && cd build
cmake-gui .. &
cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install

2. *Configure* with default native compiler settings.
3. Set ``CMAKE_INSTALL_PREFIX`` to a dedicated directory (preferably not a system path) for the ``flexiv_rdk`` library to be installed to. For example ``~/rdk_install``.
4. *Configure* and *Generate*, then back to the Terminal to compile and install:
NOTE: ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` is a CMake parameter specifying the path of the chosen installation directory. Alternatively, this configuration step can also be done through CMake GUI.

4. Compile and install ``flexiv_rdk`` library:

cd flexiv_rdk/build
cmake --build . --target install --config Release

5. The user project can now find and link to the installed ``flexiv_rdk`` library:
NOTE: the installation of ``flexiv_rdk`` library is complete now. The following steps show how to link to the installed library from a user project.

5. To find and link to the installed ``flexiv_rdk`` library from a user project, using the provided example project for instance:

cd flexiv_rdk/example
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install
cmake --build . --config Release
cmake --build . --config Release -j 4

NOTE: ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` tells user project's CMake where to find the installed ``flexiv_rdk`` library.

Note: ``CMAKE_INSTALL_PREFIX`` is set to the same directory where ``flexiv_rdk`` was installed to.
6. Assuming the system setup detailed in the Flexiv RDK Manual is done, to run an compiled example program:

./<program_name> [robot_ip] [local_ip] [...]

Note: ``sudo`` is not required unless prompted by the program.
Note: ``sudo`` is not required unless prompted by the program saying "root privilege is required".

#### Compile and install for Mac
#### Compile and install for macOS

1. In a Terminal, use ``xcode-select`` command to invoke the installation of Xcode Command Line Tools, then follow the prompted window to finish the installation.
2. Download ``cmake-3.x.x-macos-universal.dmg`` from [CMake download page](https://cmake.org/download/) and install the dmg file. The minimum required version is 3.4.
2. Download ``cmake-3.x.x-macos-universal.dmg`` from [CMake download page](https://cmake.org/download/) and install the dmg file. The minimum required version is 3.16.3.
3. When done, start CMake from Launchpad and navigate to Tools -> How to Install For Command Line Use. Then follow the instruction "Or, to install symlinks to '/usr/local/bin', run:" to install ``cmake`` and ``cmake-gui`` command for use in Terminal.
4. The rest steps are the same as [Compile and install for Linux](#compile-and-install-for-linux).
4. The rest steps are the same as [Compile and install for Linux](#compile-and-install-for-linux), beginning from step 2.

#### Compile and install for Windows

1. Install any edition of Microsoft Visual Studio with version 2010 or above. Choose the "Desktop development with C++" package during installation.
2. Download ``cmake-3.x.x-windows-x86_64.msi`` from [CMake download page](https://cmake.org/download/) and install the msi file. The minimum required version is 3.4. **Add CMake to system PATH** when prompted, so that ``cmake`` and ``cmake-gui`` command can be used from Command Prompt or PowerShell.
3. Configure the ``flexiv_rdk`` CMake project using the same steps mentioned in [Compile and install for Linux](#compile-and-install-for-linux).
4. The rest steps are the same as [Compile and install for Linux](#compile-and-install-for-linux).
5. To run an compiled example program:

cd Release
<program_name>.exe [robot_ip] [local_ip] [...]
1. Install Microsoft Visual Studio with version 2015 or above (MSVC 14.0+). Choose the "Desktop development with C++" package during installation.
2. Download ``cmake-3.x.x-windows-x86_64.msi`` from [CMake download page](https://cmake.org/download/) and install the msi file. The minimum required version is 3.16.3. **Add CMake to system PATH** when prompted, so that ``cmake`` and ``cmake-gui`` command can be used from Command Prompt or a bash emulator.
3. Install a bash emulator. Git Bash that comes with Git (for Windows) installation is recommended.
4. Within the bash emulator, the rest steps are the same as [Compile and install for Linux](#compile-and-install-for-linux), beginning from step 2.

### Python RDK

Expand Down
27 changes: 14 additions & 13 deletions example/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,26 @@ endif()

# Minumum example list for all OS
set(EXAMPLE_LIST
auto_recovery
clear_fault
display_robot_states
gripper_control
plan_execution
primitive_execution
teach_by_demonstration
basics1_display_robot_states
basics2_clear_fault
basics3_primitive_execution
basics4_plan_execution
basics5_zero_force_torque_sensors
basics6_gripper_control
basics7_auto_recovery
intermediate7_teach_by_demonstration
)


# Additional examples for Linux and Mac
if(CMAKE_HOST_UNIX)
list(APPEND EXAMPLE_LIST
RT_cartesian_pure_motion_control
RT_cartesian_motion_force_control
RT_joint_floating
RT_joint_impedance_control
RT_joint_position_control
robot_dynamics
intermediate1_realtime_joint_position_control
intermediate2_realtime_joint_torque_control
intermediate3_realtime_joint_floating
intermediate4_realtime_cartesian_pure_motion_control
intermediate5_realtime_cartesian_motion_force_control
intermediate6_robot_dynamics
)
endif()

Expand Down
67 changes: 40 additions & 27 deletions example/display_robot_states.cpp → example/basics1_display_robot_states.cpp
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/**
* @example display_robot_states.cpp
* Print received robot states.
* @example basics1_display_robot_states.cpp
* This tutorial does the very first thing: check connection with the robot server and print
* received robot states.
* @copyright Copyright (C) 2016-2021 Flexiv Ltd. All Rights Reserved.
* @author Flexiv
*/
Expand All @@ -13,7 +14,28 @@
#include <iostream>
#include <thread>

/** Print robot states data @ 1Hz */
/** @brief Print tutorial description */
void printDescription()
{
std::cout << "This tutorial does the very first thing: check connection with the robot server "
"and print received robot states."
<< std::endl
<< std::endl;
}

/** @brief Print program usage help */
void printHelp()
{
// clang-format off
std::cout << "Required arguments: [robot IP] [local IP]" << std::endl;
std::cout << " robot IP: address of the robot server" << std::endl;
std::cout << " local IP: address of this PC" << std::endl;
std::cout << "Optional arguments: None" << std::endl;
std::cout << std::endl;
// clang-format on
}

/** @brief Print robot states data @ 1Hz */
void printRobotStates(flexiv::Robot& robot, flexiv::Log& log)
{
// Data struct storing robot states
Expand All @@ -31,38 +53,30 @@ void printRobotStates(flexiv::Robot& robot, flexiv::Log& log)
}
}

void printHelp()
{
// clang-format off
std::cout << "Required arguments: [robot IP] [local IP]" << std::endl;
std::cout << " robot IP: address of the robot server" << std::endl;
std::cout << " local IP: address of this PC" << std::endl;
std::cout << "Optional arguments: None" << std::endl;
std::cout << std::endl;
// clang-format on
}

int main(int argc, char* argv[])
{
// Log object for printing message with timestamp and coloring
// Program Setup
// =============================================================================================
// Logger for printing message with timestamp and coloring
flexiv::Log log;

// Parse Parameters
//=============================================================================
// Parse parameters
if (argc < 3 || flexiv::utility::programArgsExistAny(argc, argv, {"-h", "--help"})) {
printHelp();
return 1;
}

// IP of the robot server
std::string robotIP = argv[1];

// IP of the workstation PC running this program
std::string localIP = argv[2];

// Print description
log.info("Tutorial description:");
printDescription();

try {
// RDK Initialization
//=============================================================================
// =========================================================================================
// Instantiate robot interface
flexiv::Robot robot(robotIP, localIP);

Expand Down Expand Up @@ -90,17 +104,16 @@ int main(int argc, char* argv[])
std::this_thread::sleep_for(std::chrono::seconds(1));
if (++secondsWaited == 10) {
log.warn(
"Still waiting for robot to become operational, please "
"check that the robot 1) has no fault, 2) is booted "
"into Auto mode");
"Still waiting for robot to become operational, please check that the robot 1) "
"has no fault, 2) is in [Auto (remote)] mode");
}
}
log.info("Robot is now operational");

// Periodic Tasks
//=============================================================================
// Use std::thread to do scheduling so that this example can run on all
// OS, since not all OS support flexiv::Scheduler
// Print States
// =========================================================================================
// Use std::thread to do scheduling so that this example can run on all OS, since not all OS
// support flexiv::Scheduler
std::thread lowPriorityThread(std::bind(printRobotStates, std::ref(robot), std::ref(log)));

// Properly exit thread
Expand Down
36 changes: 25 additions & 11 deletions example/clear_fault.cpp → example/basics2_clear_fault.cpp
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/**
* @example clear_fault.cpp
* Clear minor fault on the robot server side if any.
* @example basics2_clear_fault.cpp
* This tutorial clears minor faults from the robot server if any. Note that critical faults cannot
* be cleared, see RDK manual for more details.
* @copyright Copyright (C) 2016-2021 Flexiv Ltd. All Rights Reserved.
* @author Flexiv
*/
Expand All @@ -14,6 +15,16 @@
#include <string>
#include <thread>

/** @brief Print tutorial description */
void printDescription()
{
std::cout << "This tutorial clears minor faults from the robot server if any. Note that "
"critical faults cannot be cleared, see RDK manual for more details."
<< std::endl
<< std::endl;
}

/** @brief Print program usage help */
void printHelp()
{
// clang-format off
Expand All @@ -27,31 +38,34 @@ void printHelp()

int main(int argc, char* argv[])
{
// Log object for printing message with timestamp and coloring
// Program Setup
// =============================================================================================
// Logger for printing message with timestamp and coloring
flexiv::Log log;

// Parse Parameters
//=============================================================================
// Parse parameters
if (argc < 3 || flexiv::utility::programArgsExistAny(argc, argv, {"-h", "--help"})) {
printHelp();
return 1;
}

// IP of the robot server
std::string robotIP = argv[1];

// IP of the workstation PC running this program
std::string localIP = argv[2];

// Print description
log.info("Tutorial description:");
printDescription();

try {
// RDK Initialization
//=============================================================================
// =========================================================================================
// Instantiate robot interface
flexiv::Robot robot(robotIP, localIP);

// Application-specific Code
//=============================================================================
// Clear fault on robot server if any
// Fault Clearing
// =========================================================================================
// Check if the robot has fault
if (robot.isFault()) {
log.warn("Fault occurred on robot server, trying to clear ...");
// Try to clear the fault
Expand Down
Loading

0 comments on commit a9931cb

Please sign in to comment.