diff --git a/simplified_api/README.md b/simplified_api/README.md index 782fd96..f48b910 100644 --- a/simplified_api/README.md +++ b/simplified_api/README.md @@ -19,14 +19,17 @@ This software has been tested on **Ubuntu 16.04 (64-bit)** and **Windows 10** ## Download instructions -You can download the latest firmware package for the Gen3 from [here](https://artifactory.kinovaapps.com/artifactory/generic-local-public/kortex/gen3/2.0.0/Gen3-2.0.0.swu). - -You can download the latest Gen3 release notes from [here](https://artifactory.kinovaapps.com/artifactory/generic-local-public/kortex/gen3/2.0.0/RN-001_KINOVA_Gen3_Ultra_lightweight_robot-Release_Notes_EN_R04.pdf). - ## Installation Instructions -You can access the latest release of the MATLAB adaptor [here](https://artifactory.kinovaapps.com/artifactory/generic-local-public/kortex/matlab/simplified_API/2.0.0/matlab_simplified_api_2.0.0.zip) on the Kinova Artifactory. +You can access the latest release of the MATLAB adaptor [here](https://artifactory.kinovaapps.com/artifactory/webapp/#/artifacts/browse/tree/General/generic-local-public/kortex/matlab/simplified_api/) on the Kinova Artifactory. -Uncompress the MATLAB adaptor folders from the downloaded archive. +### Windows Operating System +From the Kinova Artifactory: +* Expand `kortex/matlab/simplified_api` to see the release folders +* Right-click on the desired release folder +* Select `Download` in the context menu +* Choose the desired Archive Type +* Click on `Download` +* Extract the MATLAB adaptor folders from the downloaded archive. ## Build instructions @@ -48,11 +51,8 @@ sudo apt install build-essential pkg-config ``` ### How to build -- Open MATLAB and navigate to the `mex-wrapper` folder. -- Add the current folder and all of its subfolders to the MATLAB path. -- Run the script `compileKortexMex.m` and wait until its completion. -You are now ready to use the KORTEX™ MEX (MATLAB executable) interface. +Refer to the dedicated page for [Setup](documentation/setup.md) ## Usage @@ -62,11 +62,13 @@ There are two ways to interact with the robot via MATLAB. 2. Using the MATLAB System object `kortex` (which itself uses the KORTEX™ API MEX interface) The KORTEX™ API MEX interface is the best option for controlling the arm via a MATLAB script. -The `kortex` System object on the other hand is intended for dynamical simulations of the robot as part of a system in [Simulink](https://www.mathworks.com/help/simulink/define-new-system-objects.html). +The `kortex` System object on the other hand is intended for dynamical simulations of the robot as part of a system in [Simulink](https://www.mathworks.com/help/simulink/define-new-system-objects.html). For more information on both options: * [MEX interface](documentation/mex_interface.md) * [System object](documentation/system_object.md) +In addtion, MATLAB Code Generation support for generating a ROS2 node and deploying the `kortex` System Object node directly on a NVidia Jetson Xavier platform is available. For more information, refer to the [ROS2 Code Generation on Jetson Target](documentation/setup.md#ROS2-Code-Generation-on-Jetson-Target) section in the Setup page. +For more information on MATLAB code generation, see this [Mathworks documentation page](https://www.mathworks.com/help/mpc/code-generation.html). diff --git a/simplified_api/documentation/data_structure.md b/simplified_api/documentation/data_structure.md index 23636ed..83f97cf 100644 --- a/simplified_api/documentation/data_structure.md +++ b/simplified_api/documentation/data_structure.md @@ -114,6 +114,22 @@ This is a data structure returned by most of the functions of the MEX interface. | uint32_t | code | A general [error code](#error-code-list) associated with this error. Most users will not need to work with this value because it does not tell much and is used internally in the Kortex API. | | uint32_t | sub_code | An [error sub code](#sub-error-code-list) that gives more information about the error. Most users will prefer to use this value instead of the general code. + +## MotorFeedback + +| Type | Name | Description | +|:-----:|:----:|:-----------:| +| uint32_t | motor_id | MessageId | +| uint32_t | status_flags | Status flags | +| uint32_t | jitter_comm | Jitter from the communication (in microsecond) | +| double | position | Position of the gripper motor (in Percentage 0-100%) | +| double | velocity | Velocity of the gripper motor (in Percentage 0-100%) | +| double | force | Force of the gripper motor | +| double | current_motor | Electric current of the gripper motor (in mA) | +| double | voltage | Voltage of the gripper motor (in V) | +| double | temperature_core | temparature of the core (in Celsius) | +| double | temperature_motor | temparature of the gripper motor (in Celsius) | + ## GripperFeedback @@ -126,13 +142,7 @@ This is a data structure returned by most of the functions of the MEX interface. | uint32_t | warning_bank_a | Warning bank A (see `GripperConfig.SafetyIdentifier`) | | uint32_t | warning_bank_b | Warning bank B (see `GripperConfig.SafetyIdentifier`) | | uint32_t | motor_count | Motor count on the gripper. | -| uint32_t\[GRIPPER_MAX_MOTOR_COUNT\] | motor_id | Motor ID | -| double\[GRIPPER_MAX_MOTOR_COUNT\] | motor_position | Position of the gripper fingers in percentage (0-100%) | -| double\[GRIPPER_MAX_MOTOR_COUNT\] | motor_velocity | Velocity of the gripper fingers in percentage (0-100%) | -| double\[GRIPPER_MAX_MOTOR_COUNT\] | motor_current_motor | Current comsumed by the gripper motor (mA) | -| double\[GRIPPER_MAX_MOTOR_COUNT\] | motor_voltage | Motor Voltage (V) | -| double\[GRIPPER_MAX_MOTOR_COUNT\] | motor_temperature_motor | Motor temperature. (degrees Celsius) | - +| [MotorFeedback](#motorfeedback)\[GRIPPER_MAX_MOTOR_COUNT\] | motor | Feedback of all gripper motors | ## InterconnectFeedback @@ -158,6 +168,16 @@ This is a data structure returned by most of the functions of the MEX interface. | double | difference_count_b | | | [GripperFeedback](#gripperfeedback) | gripper_feedback | Feedback data from gripper (if attached) | + +## DistortionCoefficients + +| Type | Name | Description | +|:-----:|:----:|:-----------:| +| double | k1 | First radial distortion coefficient | +| double | k2 | Second radial distortion coefficient | +| double | k3 | Third radial distortion coefficient | +| double | p1 | First tangential distortion coefficient | +| double | p2 | Second tangential distortion coefficient | ## IntrinsicParameters @@ -170,11 +190,7 @@ This is a data structure returned by most of the functions of the MEX interface. | double | principal_point_y | Vertical coordinate of the principal point of the image, as a pixel offset from the top edge | | double | focal_length_x | Focal length of the image plane, as a multiple of pixel width | | double | focal_length_y | Focal length of the image plane, as a multiple of pixel height | -| double | k1 | First radial distortion coefficient | -| double | k2 | Second radial distortion coefficient | -| double | k3 | Third radial distortion coefficient | -| double | p1 | First tangential distortion coefficient | -| double | p2 | Second tangential distortion coefficient | +| [DistortionCoefficients](#distortioncoefficients) | distortion_coeffs | Distortion Coefficients | diff --git a/simplified_api/documentation/images/Build&Run.PNG b/simplified_api/documentation/images/Build&Run.PNG new file mode 100644 index 0000000..02ad536 Binary files /dev/null and b/simplified_api/documentation/images/Build&Run.PNG differ diff --git a/simplified_api/documentation/images/JetsonParameters.PNG b/simplified_api/documentation/images/JetsonParameters.PNG new file mode 100644 index 0000000..5fb4123 Binary files /dev/null and b/simplified_api/documentation/images/JetsonParameters.PNG differ diff --git a/simplified_api/documentation/images/Run.png b/simplified_api/documentation/images/Run.png new file mode 100644 index 0000000..8a87e1a Binary files /dev/null and b/simplified_api/documentation/images/Run.png differ diff --git a/simplified_api/documentation/images/kortexConfig.PNG b/simplified_api/documentation/images/kortexConfig.PNG new file mode 100644 index 0000000..5665fd5 Binary files /dev/null and b/simplified_api/documentation/images/kortexConfig.PNG differ diff --git a/simplified_api/documentation/mex_interface.md b/simplified_api/documentation/mex_interface.md index 40da944..9e73041 100644 --- a/simplified_api/documentation/mex_interface.md +++ b/simplified_api/documentation/mex_interface.md @@ -43,9 +43,8 @@ This function initializes the KORTEX™ API that operates underneath the MEX int | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | -| uint32_t | An handle to the API. this handle will be needed by most of the function of this MEX interface.| +| uint32_t | An error code (`0` for success or non-zero for failure). | +| uint32_t | An handle to the API. This handle will be needed by most of the function of this MEX interface.| | uint32_t | The device ID of the vision module attached to the robot. | #### DestroyRobotApisWrapper @@ -61,8 +60,7 @@ This function closes the connection with the KORTEX™ API cleanly. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### SetAdmittance @@ -79,8 +77,7 @@ Set the robot into admittance mode. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### SetServoingMode Set the robot servoing mode. @@ -96,8 +93,7 @@ Set the robot servoing mode. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success(true) or not(false). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | --- @@ -116,8 +112,7 @@ Apply the emergency stop on the robot. The robot should stop moving and go to th | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### ClearFaults Try to clear the faults on the robot. If the robot is in a fault state, you should see a red LED on the robot's base. @@ -132,8 +127,7 @@ Try to clear the faults on the robot. If the robot is in a fault state, you shou | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### Reboot @@ -149,8 +143,7 @@ Reboot the robot. Warning: the robot may fall slowly for a short time because du | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### StopAction @@ -166,8 +159,7 @@ Stop the current trajectory. | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### PauseAction Pause the current trajectory. @@ -182,8 +174,7 @@ Pause the current trajectory. | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### ResumeAction Resume the current trajectory. @@ -198,8 +189,7 @@ Resume the current trajectory. | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | --- @@ -219,8 +209,7 @@ Returns the joint count of the robot. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | uint32_t | The joint count. | @@ -237,8 +226,7 @@ Returns the status of the robot. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | int32_t | Status of the robot. This value is described [here](data_structure.md#movementstatus). | @@ -255,8 +243,7 @@ It returns the feedback data from the base, the joints and tool. | C++ Type | Description | |:-------------:|:-------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | [BaseFeedback](data_structure.md#basefeedback) | Feedback data for the base. | | [ActuatorsFeedback](data_structure.md#actuatorsfeedback) | Feedback data for each joint. | | [InterconnectFeedback](data_structure.md#interconnectfeedback) | Feedback data for the interface module, including gripper. | @@ -275,7 +262,7 @@ Move the robot to a specific Cartesian pose. The orientation is represented with |:-------------:|:----------------------------------------------------------------------------------------------------------------:| | uint32_t | API Handle. | | int32_t | The [CartesianConstraintType](data_structure.md#cartesianconstrainttype) applied on the movement. | -| double\[2\] | Speed limitation that will be applied on the trajectory if the constraint has been set to CARTESIAN_CONSTRAINT_SPEED. The first value is the translation velocity and the second value is not used for now. | +| double\[2\] | Speed limitation that will be applied on the trajectory if the constraint has been set to CARTESIAN_CONSTRAINT_SPEED. The first value is the translation velocity and the second value is the orientation velocity. | | double | Not supported for now. | | double\[3\] | Translation (X, Y, Z) in meters. | | double\[3\] | Orientation. (X(gamma), Y(beta), Z(alpha)) in degrees. (**Tait-Bryan, extrinsic ZYX**) | @@ -284,8 +271,7 @@ Move the robot to a specific Cartesian pose. The orientation is represented with | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### ReachJointAngles Move the robot to a specific joint pose. @@ -305,8 +291,7 @@ Move the robot to a specific joint pose. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### SendJointSpeedCommand Move the robot using a speed command. @@ -324,8 +309,7 @@ Move the robot using a speed command. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### SendToolCommand Move the robot tool. For now, our gripper is considered as one tool so only one command (first index) is needed to move the tool. @@ -344,8 +328,7 @@ Move the robot tool. For now, our gripper is considered as one tool so only one | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### PlayPreComputedTrajectory @@ -366,8 +349,7 @@ Send a Precomputed Joint Trajectory to the robot. A Precomputed Joint Trajectory | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | --- @@ -392,8 +374,7 @@ Configure one of the sensors (either 2D or 3D) of the vision module. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### SetOptionValue Configure a specific option out of the options available on the vision module. @@ -411,8 +392,7 @@ Configure a specific option out of the options available on the vision module. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### InitVision Initialize the vision module API. @@ -427,8 +407,7 @@ Initialize the vision module API. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | #### GetSensorSettings Get the configuration of a specific sensor(2D or 3D) of the vision module. @@ -444,8 +423,7 @@ Get the configuration of a specific sensor(2D or 3D) of the vision module. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | uint32_t | The resolution of the sensor. See [Resolution](data_structure.md#resolution). | | uint32_t | The frame rate of the sensor. See [FrameRate](data_structure.md#framerate). | | uint32_t | The bit rate of the sensor. See [BitRate](data_structure.md#bitrate). | @@ -465,8 +443,7 @@ Get the value of a specific option from a specific sensor (eitrher 2D or 3D) of | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | uint32_t | The resolution of the sensor. This value is described [here](data_structure.md#resolution). | | uint32_t | The frame rate of the sensor. This value is described [here](data_structure.md#framerate). | | uint32_t | The bit rate of the sensor. This value is described [here](data_structure.md#bitrate). | @@ -525,8 +502,7 @@ Returns the last error that occurred in the API. | C++ Type | Description | |:--------------:|:-------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | uint32_t | The error code of the last error triggered by the Kortex API. | #### GetErrorName @@ -543,8 +519,7 @@ Returns a string that describe the error code provided as an input. | C++ Type | Description | |:-------------:|:----------------------------------------------------------------------------------------------------------------:| -| bool | A flag that tells if the operation was a success (`true`) or not (`false`). | -| [ErrorStructMatrix](data_structure.md#errorstructmatrix) | A data structure that contains the error code if the operation was not a success. | +| uint32_t | An error code (`0` for success or non-zero for failure). | | char * | The name that describe the error code. | diff --git a/simplified_api/documentation/precomputed_joint_trajectories.md b/simplified_api/documentation/precomputed_joint_trajectories.md index 0cb00c1..0994625 100644 --- a/simplified_api/documentation/precomputed_joint_trajectories.md +++ b/simplified_api/documentation/precomputed_joint_trajectories.md @@ -7,7 +7,7 @@ The Precomputed Joint Trajectories is the way to send the arm through joint-spac ### kObjTrajectoryFeeder object -The kObjTrajectoryFeeder object in the example Simulink model (`mex-wrapper/example_model.slx`) reads a Precomputed Joint Trajectory (computed offline with a motion planner) from a CSV file(`mex-wrapper/testpoints.csv`) and sends it to the kortex System Object. You will most likely create your own object to send your trajectories to the kortex System object. +The kObjTrajectoryFeeder object in the [example Simulink model](../mex-wrapper/example_model.slx) reads a Precomputed Joint Trajectory (computed offline with a motion planner) from a [CSV file](../mex-wrapper/testpoints.csv) and sends it to the kortex System Object. You will most likely create your own object to send your trajectories to the kortex System object. ### Structure of the input arrays diff --git a/simplified_api/documentation/setup.md b/simplified_api/documentation/setup.md new file mode 100644 index 0000000..82f9f4f --- /dev/null +++ b/simplified_api/documentation/setup.md @@ -0,0 +1,40 @@ +# Kortex System Object Setup Guide + +## Overview + +## Matlab Setup + +1. Open the `mex-wrapper` sub-folder in Matlab +2. Add the `matlab_api` folder and its sub-folders to the Matlab path +3. Open the `example_model.slx` Simulink model + +## Interpreted Execution + +1. Run `compileKortexMex.m` +2. Edit both `kortex` and `kObjTrajectoryFeeder` Simulink objects with Kinova Robot information +3. In Simulink, click on `Run` in the Simulate tab + + ![alt text](images/Run.png) + +## ROS2 Code Generation on Jetson Target + +1. Edit the `rosTargetPreferences.m` file with Jetson parameters + + ![Jetson Parameters](images/JetsonParameters.PNG) + +2. Run `configKortexModelROS2.m` +3. Edit both `kortex` and `kObjTrajectoryFeeder` Simulink objects with Kinova Robot information + + ![Configuration](images/kortexConfig.PNG) + +4. Open the Robot tab in Simulink +5. Select the ROS2 framework +6. Click on `Build & Run` + + ![Build & Run](images/Build&Run.PNG) + +The `Build & Run` will additionally do the following: + +1. Transfer the generated ROS2 package directly on the Jetson target +2. Compile on the Jetson target (using Colcon tools) +3. Run the compiled ROS2 package on the Jetson Target diff --git a/simplified_api/documentation/system_object.md b/simplified_api/documentation/system_object.md index fae6141..8c1a8ce 100644 --- a/simplified_api/documentation/system_object.md +++ b/simplified_api/documentation/system_object.md @@ -142,3 +142,222 @@ The configuration data of the vision system. This consists of several fields whi #### is_moving A Boolean flag that tells if the robot is moving (`true`) or not (`false`). + +### Functions + +#### SendCmd_Reboot +This function performs a software reboot on the gen3 robot. +**WARNING** Make sure the robot is in a secure position because all the joints will stop servoing and the robot will fall. + +##### Function Inputs +No input + +##### Function Outputs +| Name | Type | Description | +|:--------:|:------:|---------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + +#### GetExtrinsic +This function returns the extrinsic parameters of the camera. + +##### Function Inputs +No input + +##### Function Outputs +| Name | Type | Description | +|:---------:|:------------------:|---------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| extrinsic | Bus_ExtrinsicParam | A struct that contains all the cameras's extrinsic parameters. | + +#### GetIntrinsic +This function returns the intrinsic parameters of the camera. + +##### Function Inputs +| Name | Type | Description | +|:---------:|:------------------:|--------------------------------------------------------------------------| +| sensor | uint32 | ID of the target sensor that the intrinsic parameters will be read from. | + +##### Function Outputs +| Name | Type | Description | +|:---------:|:------------------:|---------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| intrinsic | Bus_IntrinsicParam | A struct that contains all the cameras's extrinsic parameters. | + +#### GetMovementStatus +This function returns the current movement status of the gen3 robot. + +##### Function Inputs +No input + +##### Function Outputs +| Name | Type | Description | +|:--------:|:-------|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| status | uint32 | Current movement status. Based on C enum MovementStatus from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +#### GetOptionValue +This function returns the value of an option on a specific sensor. + +##### Function Inputs +| Name | Type | Description | +|:---------:|:-------:|-----------------------------------------------------------------------------------------------------------| +| sensor | uint32 | Target sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| option | uint32 | Target option. Based on C enum **Option** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +##### Function Outputs +| Name | Type | Description | +|:---------:|:------------------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| value | uint32 | Value of the targeted option. | + +#### GetSensorSettings +This function returns the configured settings of a specific sensor. + +##### Function Inputs +| Name | Type | Description | +|:---------:|:-------:|-----------------------------------------------------------------------------------------------------------| +| sensor | uint32 | Target sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| resolution | uint32 | Resolution of the targeted sensor. Based on the C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| frame_rate | uint32 | Frame rate of the targeted sensor. Resolution of the targeted sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| bit_rate | uint32 | Bit rate of the targeted sensor. Resolution of the targeted sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +#### GetSensorSettings +This function returns the configured settings of a specific sensor. + +##### Function Inputs +| Name | Type | Description | +|:---------:|:-------:|-----------------------------------------------------------------------------------------------------------| +| sensor | uint32 | Target sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + | +| resolution | uint32 | Resolution of the targeted sensor. Based on the C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| frame_rate | uint32 | Frame rate of the targeted sensor. Resolution of the targeted sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| bit_rate | uint32 | Bit rate of the targeted sensor. Resolution of the targeted sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +#### DoSensorFocusAction +Execute a focus action on the camera. You can find a C++ example [here](https://github.com/Kinovarobotics/kortex/blob/master/api_cpp/examples/500-Vision/03_vision_sensor_focus_action.cpp) that explains how to use this function. + +##### Function Inputs +| Name | Type | Description | +|:-------------:|:-------:|-----------------------------------------------------------------------------------------------------------| +| sensor | uint32 | Target sensor. Based on C enum **Sensor** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | +| focus_action | uint32 | Target sensor. Based on C enum **FocusAction** from [kortex_wrapper_data.h](../mex-wrapper/include/kortex_wrapper_data.h). | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + | + +#### SendCartesianPose +Send a Cartesian pose to the robot. The orientation is represented with Euler angles and the convention used is the **Tait-Bryan, extrinsic ZYX**. + +##### Function Inputs +| Name | Type | Description | +|:----------------:|:----------------------------:|-----------------------------------------------------------------------------------------------------------| +| cartesian_cmd | double[6] | Cartesian command. [X, Y, Z, THETA_X, THETA_Y, THETA_Z] Translation in meters and orientation in degrees.| +| constraint_type | enum CartesianConstraintType | Type of constraint. Based on [CartesianConstraintType](data_structure.md). | +| speeds | double[2] | Translation and orientation speed. [TRANSLATION_SPEED, ORIENTATION_SPEED]. Translation in m / s and orientation in °/s| +| duration | uint32 | Not supported for now. | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + +#### SendJointAngles +Send a joint pose to the robot. All angles are in degrees. + +##### Function Inputs +| Name | Type | Description | +|:---------------:|:------------------------:|-----------------------------------------------------------------------------------------------------------| +| joint_cmd | double[ACTUATOR_COUNT] | Joint command, in degrees, where ACTUATOR_COUNT is the actual actuator count. The first index is the nearest joint to the base and the last index is the nearest joint to the gripper. | +| constraintType | enum JointConstraintType | Type of constraint. Based on [CartesianConstraintType](data_structure.md). | +| speed | double | Speed limitation, in degrees / second, that will be applied on the trajectory if the constraint has been set to JOINT_CONSTRAINT_SPEED.| +| duration | uint32 | Time limitation, in second, that will be applied on the trajectory if the constraint has been set to JOINT_CONSTRAINT_DURATION. | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + +#### SendPreComputedTrajectory +Send a Precomputed Joint Trajectory to the robot. A Precomputed Joint Trajectory is a set of (timestamp, angular position, angular velocity, angular acceleration) for each joint at each increment of the trajectory. Together, this represents a trajectory. For more information on the Precomputed Joint Trajectories, you can read [the documentation on Precomputed Joint Trajectories](./precomputed_joint_trajectories.md). + +##### Function Inputs +| Name | Type | Description | +|:--------------:|:------------------------:|-----------------------------------------------------------------------------------------------------------| +| position | double[ACTUATOR_COUNT][] | A matrix that contains a list of angular positions (degrees) for each joint at each increment. | +| velocity | double[ACTUATOR_COUNT][] | A matrix that contains a list of angular velocities (degrees / second) for each joint at each increment. | +| acceleration | double[ACTUATOR_COUNT][] | A matrix that contains a list of angular accelerations (degrees / second ^ squared) for each joint at each increment. | +| timestamp_sec | double[ACTUATOR_COUNT][] | A matrix that contains a list of timestamps for each joint at each increment. | + +##### Function Outputs +| Name | Type | Description | +|:----------:|:------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + +#### SendRefreshFeedback +It returns the feedback data from the base, the joints and tool. + +##### Function Inputs +No input + +##### Function Outputs +| Name | Type | Description | +|:--------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | +| baseFeedback | Bus_BaseFeedback | Feedback data from the Base. See [BaseFeedBack](data_structure.md#basefeedback). | +| jointsFeedback | Bus_JointsFeedback | Feedback data from each joint. See [ActuatorsFeedback](data_structure.md#actuatorsfeedback). | +| interconnectFeedback | Bus_ToolFeedback | Feedback data from the Base. See [InterconnectFeedBack](data_structure.md#interconnectfeedback). | + +#### SendToolCommand +A command to control the gripper movement + +##### Function Inputs +| Name | Type | Description | +|:--------------:|:------------------------:|-----------------------------------------------------------------------------------------------------------| +| tool_cmd_mode | uint32 | Command mode. Based on [ToolMode](data_structure.md). | +| duration | double | Duration constraint. If not 0, allows to set a limit (in seconds) to the tool_cmd. | +| tool_cmd | double[TOOL_COUNT] | Gripper movement values for each tool. (Most of the time you only have 1 tool.) In position, admissible values for each finger is between 0 and 1.0, where 0 is fully open and 1.0 is fully closed. In speed, admissible values for each finger is between -1.0 and 1.0, where 1.0 corresponds to maximum opening speed and -1.0 corresponds to maximum closing speed.| + +##### Function Outputs +| Name | Type | Description | +|:--------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + + +#### SetAdmittance +Activate the admittance mode. + +##### Function Inputs +| Name | Type | Description | +|:---------------:|:------:|-----------------------------------------------------------------------------------------------------------| +| admittanceMode | uint32 | Admittance mode. Based on [AdmittanceMode](data_structure.md). | + +##### Function Outputs +| Name | Type | Description | +|:--------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. | + +#### SetServoingMode +Set the robot's servoing mode. + +##### Function Inputs +| Name | Type | Description | +|:---------------:|:------:|-----------------------------------------------------------------------------------------------------------| +| servoingMode | uint32 | Servoing mode. Based on [ServoingMode](data_structure.md). | + +##### Function Outputs +| Name | Type | Description | +|:--------------------:|:------------------:|-----------------------------------------------------------------------------------------------------------| +| isOk | bool | A flag that indicates if the function has been executed correctly. |