====== ROS Custom Message Support for Matlab  ======
---------------------------------------------

This tutorial will guide the reader through the steps needed to generate the artifacts necessary for Matlab to import and use custom-defined ROS messages (e.g. defined within packages in a catkin workspace).

**Note**: Instructions on this page apply for Matlab R2017b through Matlab R2020a. For R2020b onward, the ''rosgenmsg'' command and custom message support have been incorporated into ROS Toolbox; use [[https://www.mathworks.com/help/ros/ug/create-custom-messages-from-ros-package.html | these]] instructions instead.
===== Pre-requisite(s):  =====

**1.** ROS Toolbox for Matlab must be installed  

**2.** ROS Custom Message Support Add-On must be installed in the ROS Toolbox

For **#2**, attempting to run 'rosgenmsg' at the Matlab command line should indicate whether any Add-Ons need to be installed. If not installed, the resulting error text will direct how to install.

===== Create ROS Custom Message  =====

See [[ROS/Tutorials/CreatingMsgAndSrv | http://wiki.ros.org/ROS/Tutorials/CreatingMsgAndSrv]].

In the catkin workspace, make sure custom message packages are successfully built, e.g.
''catkin build''.

===== Compile Custom Message Artifacts for Matlab  =====
**1.** If have previously compiled custom messages and are now re-compiling (if not, skip this step):

In Ubuntu Terminal:

**a.** Remove the ''matlab_gen/'' directory from the catkin workspace ''src/'' area:
<code>
cd <CATKIN_WS>/src/custom_robo_msgs
rm -rf matlab_gen
</code>

**b.** Remove or back-up javaclasspath.txt in the Matlab user area:
<code>
cd ~/.matlab/<MATLAB_VERSION>
rm javaclasspath.txt
</code>
or 
<code>
cd ~/.matlab/<MATLAB_VERSION>
mv javaclasspath.txt javaclasspath.txt.bak
</code>

**2.** Restart Matlab

At Matlab command line, run 
<code>
rosgenmsg('<CATKIN_WS>/src/<TOP_LEVEL_DIR>');
</code>
where ''<CATKIN_WS>'' is the path to the catkin workspace and ''<TOP_LEVEL_DIR>'' is the highest level directory, in the catkin workspace ''src/'' area, that contains the custom message packages you would like Matlab to support.

At the Matlab command line, you should see something similar to this example output:
<code>
>> rosgenmsg('~/catkin_ws/src/custom_robo_msgs');
 
Checking sub-folder "snake_gait_msgs" for custom messages.
 
Building custom message files for the following packages:
   snake_gait_msgs
 
 
Generating MATLAB classes for message packages in /home/achang/catkin_ws/src/custom_robo_msgs/matlab_gen/jar.
 
Loading file snake_gait_msgs-0.0.0.jar.
Generating MATLAB code for snake_gait_msgs/GaitCntrlCmd message type.
Generating MATLAB code for snake_gait_msgs/HeadScanGaitParams message type.
Generating MATLAB code for snake_gait_msgs/HeadScanGaitStatus message type.
Generating MATLAB code for snake_gait_msgs/RectilinearGaitParams message type.
Generating MATLAB code for snake_gait_msgs/SineWaveParams message type.
Generating MATLAB code for snake_gait_msgs/RectilinearGaitStatus message type.
Generating MATLAB code for snake_gait_msgs/TurnInPlaceGaitParams message type.
Generating MATLAB code for snake_gait_msgs/TurnInPlaceGaitStatus message type.
 
To use the custom messages, follow these steps:
 
1. Edit javaclasspath.txt, add the following file locations as new lines, and save the file:
 
/home/achang/catkin_ws/src/custom_robo_msgs/matlab_gen/jar/snake_gait_msgs-0.0.0.jar
 
2. Add the custom message folder to the MATLAB path by executing:
 
addpath('/home/achang/catkin_ws/src/custom_robo_msgs/matlab_gen/msggen')
savepath
 
3. Restart MATLAB and verify that you can use the custom messages. 
   Type "rosmsg list" and ensure that the output contains the generated
   custom message types.

</code>

Here, ''<CATKIN_WS> = ~/catkin_ws'' and ''<TOP_LEVEL_DIR> = custom_robo_msgs''.  ''custom_robo_msgs/snake_gait_msgs'' is a ROS package and contains ROS custom messages we would like Matlab to support. It contains definitions for the following message types:
- GaitCntrlCmd
- HeadScanGaitParams
- HeadScanGaitStatus
- RectilinearGaitParams
- SineWaveParams
- RectilinearGaitStatus
- TurnInPlaceGaitParams
- TurnInPlaceGaitStatus

**3.** In an Ubuntu Terminal:
<code>
cd ~/.matlab/<MATLAB_VERSION>
</code>
where ''<MATLAB_VERSION>'' is the version of Matlab which will be run and requires custom message support.

If re-compiling and no NEW message types have been created (i.e. no new .jar files need to be added to ''javaclasspath.txt''), you may restore the back-up from Step **#1**. 
<code>
mv javaclasspath.txt.bak javaclasspath.txt
</code>

Otherwise, create the file ''javaclasspath.txt'' according to the instructions in the text output from the Matlab ''rosgenmsg'' command (e.g. see example output above).

**4.** Restart Matlab

At Matlab  command line,
<code>
addpath('<CATKIN_WS>/src/<TOP_LEVEL_DIR>/matlab_gen/msggen');
</code>

Matlab should now be able to create/send/receive the compiled ROS custom messages. Run ''rosmsg list'' and verify that the custom message types are listed (alphabetical order).

**CAUTION:** The ''addpath( ... )'' command, above, MUST be run after any Matlab restart and prior to running ANY Matlab ROS-related commands. If a ROS-related command is run in Matlab prior to the ''addpath( ... )'' command, custom messages may not be imported. You will have to restart Matlab and run the ''addpath( ... )'' command first.


**References:**

[[ https://www.mathworks.com/help/ros/ug/ros-custom-message-support.html | https://www.mathworks.com/help/ros/ug/ros-custom-message-support.html ]]  

[[ https://www.mathworks.com/help/ros/ref/rosgenmsg.html | https://www.mathworks.com/help/ros/ref/rosgenmsg.html ]]  

[[ https://www.mathworks.com/help/ros/custom-message-support.html | https://www.mathworks.com/help/ros/custom-message-support.html ]]  

[[ https://www.mathworks.com/matlabcentral/fileexchange/49810-ros-toolbox-interface-for-ros-custom-messages | https://www.mathworks.com/matlabcentral/fileexchange/49810-ros-toolbox-interface-for-ros-custom-messages ]]