gzlink

Assign and retrieve Gazebo model link information

Since R2021a

Syntax

List = gzlink("list",modelname)

[Status,Message] = gzlink("set",modelname,linkname,Name,Value)

[Output1,...,OutputN] = gzlink("get",modelname,linkname,params)

Description

List = gzlink("list",modelname) returns and displays a list of link names List in the specified Gazebo model modelname.

[Status,Message] = gzlink("set",modelname,linkname,Name,Value) assigns values to the link parameters using one or more name-value pair arguments for the specified Gazebo model modelname and the link linkname. The function returns the status of the value assignments Status and the message of their success and failure Message. For example, gzlink("set","unit_box","link","Position",[2 2 0.5]) sets the position of the link in the model unit_box.

[Output1,...,OutputN] = gzlink("get",modelname,linkname,params) retrieves values of the link parameters using one or more parameter name, params, for the specified Gazebo model modelname and the link linkname. The function returns one or more outputs, Output1,...,OutputN, corresponding to the specified parameter names.

Examples

Perform Co-Simulation Between MATLAB and Gazebo

Set up a simulation between MATLAB and Gazebo, receive data from Gazebo, and send commands to Gazebo.

Prerequisite

Follow the instructions in Perform Co-Simulation Between Simulink and Gazebo to download the Linux virtual machine (VM) with Gazebo and set up multiSensorPluginTest.world.

Configure and Perform Gazebo Co-Simulation

Initialize connection settings and check connectivity with the Gazebo plugin running on 192.168.198.129 and port 14581.

gzinit("192.168.198.129",14581)

Assign and Retrieve Gazebo Model Information

List the models available in the Gazebo world.

modelList = gzmodel("list")

modelList = 1×11 string
    "ground_plane"    "unit_box"    "camera0"    "camera1"    "depth_camera0"    "depth_camera1"    "imu0"    "imu1"    "hokuyo0"    "hokuyo1"    "velodyne"

Assign values to the Position and SelfCollide parameters of the unit_box model.

[status,message] = gzmodel("set","unit_box","Position",[2 2 0.5],"SelfCollide","on")

status = 1×2 logical array

   1   1

message = 1×2 string
    "Position parameter set successfully."    "SelfCollide parameter set successfully."

Retrieve the values of the Position and SelfCollide parameters of the unit_box model.

[position,selfcollide] = gzmodel("get","unit_box","Position","SelfCollide")

position = 1×3

                         2                         2           0.4999999999951

selfcollide = logical
   1

Assign and Retrieve Gazebo Model Link Information

List the links available in the unit_box model.

linkList = gzlink("list","unit_box")

linkList = 
"link"

Assign values to the link parameters Mass and Gravity of the link link in the unit_box model.

[status,message] = gzlink("set","unit_box","link","Mass",2,"Gravity","off")

status = 1×2 logical array

   1   1

message = 1×2 string
    "Mass parameter set successfully."    "Gravity parameter set successfully."

Retrieve the values of the link parameters Mass and Gravity of the link link in the unit_box model.

[mass,gravity] = gzlink("get","unit_box","link","Mass","Gravity")

mass = 
     2

gravity = logical
   0

Assign and Retrieve Gazebo Model Joint Information

List the joints available in the unit_box model.

jointList = gzjoint("list","unit_box")

jointList = 
"joint"

Assign a value to the joint parameter Damping of the axis Axis0 for the joint joint in the unit_box model.

[status,message] = gzjoint("set","unit_box","joint","Axis","0","Damping",0.25)

status = logical
   1

message = 
"Damping parameter set successfully."

Retrieve the value of the joint parameter Damping of the axis Axis0 for the joint joint in the unit_box model.

damping = gzjoint("get","unit_box","joint","Axis0","Damping")

damping = 
                      0.25

Reset all Gazebo model configurations.

gzworld("reset")

Input Arguments

modelname — Gazebo model name

string scalar | character vector

Gazebo model name, specified as a string scalar or character vector.

Data Types: char | string

linkname — Associated link name

string scalar | character vector

Associated link name, specified as a string scalar or character vector.

Data Types: char | string

params — Gazebo model link parameters

string scalars | character vectors

Gazebo model link parameters, specified as a comma-separated list of string scalars or character vectors. Specify the list of parameters you want to retrieve the values, from this table.

Parameters	Description
"Canonical"	Get the canonical parameter of the Gazebo model link.
"EnableWind"	Get the wind parameter of the Gazebo model link.
"Gravity"	Get the gravity parameter of the Gazebo model link.
"IsStatic"	Get the IsStatic parameter of the Gazebo model link.
"Kinematic"	Get the kinematic parameter of the Gazebo model link.
"Mass"	Get the mass parameter of the Gazebo model link.
"Orientation"	Get the orientation parameter of the Gazebo model link.
"Position"	Get the position parameter of the Gazebo model link.
"PrincipalMoments"	Get the principal moments parameter of the Gazebo model link.
"ProductOfInertia"	Get the product of inertia parameter of the Gazebo model link.
"SelfCollide"	Get the SelfCollide parameter of the Gazebo model link.

Example: [mass,gravity] = gzlink("get","unit_box","link","Mass","Gravity")

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: For example, gzlink("set","unit_box","link","Position",[2 2 0.5]) sets the position of the link in the model unit_box.

Canonical — Gazebo model link canonical parameter

'on' | 'off'

Gazebo model link canonical parameter, specified as the comma-separated pair consisting of 'Canonical' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","Canonical","off");

Data Types: char | string

EnableWind — Gazebo model link wind parameter

'on' | 'off'

Gazebo model link wind parameter, specified as the comma-separated pair consisting of 'EnableWind' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","EnableWind","off");

Data Types: char | string

Gravity — Gazebo model link gravity parameter

'on' | 'off'

Gazebo model link gravity parameter, specified as the comma-separated pair consisting of 'Gravity' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","Gravity","off");

Data Types: char | string

IsStatic — Gazebo model link IsStatic parameter

'on' | 'off'

Gazebo model link IsStatic parameter, specified as the comma-separated pair consisting of 'IsStatic' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","IsStatic","off");

Data Types: char | string

Kinematic — Gazebo model link kinematic parameter

'on' | 'off'

Gazebo model link kinematic parameter, specified as the comma-separated pair consisting of 'Kinematic' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","Kinematic","off");

Data Types: char | string

Mass — Gazebo model link mass parameter

numeric scalar

Gazebo model link mass parameter, specified as the comma-separated pair consisting of 'Mass' and a numeric scalar in kilograms.

Example: [status,message] = gzlink("set","unit_box","link","Mass",1);

Data Types: single | double

Orientation — Gazebo model link orientation parameter

four-element vector

Gazebo model link orientation parameter, specified as the comma-separated pair consisting of 'Orientation' and a four-element quaternion vector of the form [w x y z].

Example: [status,message] = gzlink("set","unit_box","link","Orientation",[1 0 0 0]);

Data Types: single | double

Position — Gazebo model link position

three-element vector

Gazebo model link position parameter, specified as the comma-separated pair consisting of 'Position' and a three-element vector of the form [x y z] in meters.

Example: [status,message] = gzlink("set","unit_box","link","Position",[0 0 0]);

Data Types: single | double

PrincipalMoments — Gazebo model link principal moments

three-element vector

Gazebo model link principal moments parameter, specified as the comma-separated pair consisting of 'PrincipalMoments' and a three-element vector of the form [ixx iyy izz] in kilogram square meters.

Example: [status,message] = gzlink("set","unit_box","link","PrincipalMoments",[0 0 0]);

Data Types: single | double

ProductOfInertia — Gazebo model link product of inertia

three-element vector

Gazebo model link product of inertia parameter, specified as the comma-separated pair consisting of 'ProductOfInertia' and a three-element vector of the form [ixy ixz iyz] in kilogram square meters.

Example: [status,message] = gzlink("set","unit_box","link","ProductOfInertia",[0 0 0]);

Data Types: single | double

SelfCollide — Gazebo model link SelfCollide parameter

'on' | 'off'

Gazebo model link SelfCollide parameter, specified as the comma-separated pair consisting of 'SelfCollide' and either 'on' or 'off'.

Example: [status,message] = gzlink("set","unit_box","link","SelfCollide","off");

Data Types: char | string

Output Arguments

List — List of links in model

cell array of character vectors

List of links in the model, returned as a cell array of character vectors.

Status — Status of values assigned to parameters

logical array

Status of the values assigned to the parameters, returned as a logical array.

Message — Success or failure message

string array

Success or failure message, returned as a string array.

Output1,...,OutputN — Values of specified parameters

logical scalar | numeric scalar | numeric vector

Values of specified parameters, returned as a logical or numeric vector based on the specified parameters. The following table shows the returned data type of parameter values.

Parameters	Description
"Canonical"	Gazebo model link canonical parameter, returns a logical scalar.
"EnableWind"	Gazebo model link wind parameter, returns a logical scalar.
"Gravity"	Gazebo model link gravity parameter, returns a logical scalar.
"IsStatic"	Gazebo model link IsStatic parameter, returns a logical scalar.
"Kinematic"	Gazebo model link kinematic parameter, returns a logical scalar.
"Mass"	Gazebo model link mass parameter, returns a numeric scalar in kilograms.
"Orientation"	Gazebo model link orientation parameter, returns a four-element quaternion vector of the form [w x y z].
"Position"	Gazebo model link position parameter, returns a three-element vector of the form [x y z] in meters.
"PrincipalMoments"	Gazebo model link principal moments parameter, returns a three-element vector of the form [ixx iyy izz] in kilogram square meters.
"ProductOfInertia"	Gazebo model link product of inertia parameter, returns a three-element vector of the form [ixy ixz iyz] in kilogram square meters.
"SelfCollide"	Gazebo model link SelfCollide parameter, returns a logical scalar.

Limitations

• gzlink function not supported with MATLAB^® Compiler™.

Version History

Introduced in R2021a