Macro File Format

This section provides a deeper overview of the recorded .hrpr macro file format.

When you open a recorded .hrpr file, you will see a series of header fields followed by the recorded motion data organized by time step.

The header contains the following keys:

• FORMAT_VERSION: Specifies the version of the .hrpr file format.
• PROGRAM_NAME: Specifies the full path where the file was saved. Mixed \ and / separators, as well as repeated //, do not affect file interpretation.
• DATE: Specifies the date when the recording was created.
• SAMPLE_RATE: Specifies the recording frequency. HARP records at 100 samples per second (100 Hz).
• POSITION_LEADER: Identifies the Inverse3 device used as the position leader during the recording.
• ORIENTATION_LEADER: Identifies the VerseGrip or Ruko device used as the orientation leader during the recording.
• FOLLOWERS: Lists the follower devices included in the recording. For example, cg_0 refers to Control Group 0, and the value in brackets identifies the follower slot within that control group.
• DESCRIPTION: Stores an optional free-text description associated with the recording.

Following the header, the recorded motion data is stored using the format described in the table below.

Field	Meaning	Example
N#	Frame number	N1 N169
t#	Time as a Unix timestamp in milliseconds	t1788878409547
{...}	holds one frame. Each follower line ends with ,. A file needs at least one complete block to play back.	{cg_0::Follower(0): ... cg_0::Follower(1): ...}
X Y Z	Tool position coordinate in metres	X0.1183887 Y-0.0375092 Z0.1076392
rW rX rY rZ	Tool orientation as a quaternion	rW0.1575889 rX-0.160 rY0.973 rZ-0.051
F#.#####	Linear speed (feedrate), in m/s	F0.0010804 F0.0150
Fa#.#####	Angular speed (feedrate), in rad/s	Fa0.2586200 Fa1.0053328
J6[#,#,#,#,#,#]	Joint angles in radians	J6[0.403,0.157,1.000,-0.936,0.214,0.977]
JV6[#,#,#,#,#,#]	Joint velocities	JV6[0.000 0.000 0.000 0.000 0.000 0.000]

How Lines Are Interpreted

• A line that specifies X, Y, and Z commands moves the robot to the corresponding absolute Cartesian position.
• If a coordinate is omitted, the robot retains its current value for that axis.
  • For example, if X is omitted from a command, playback updates only the specified axes, such as Y and Z, while maintaining the current X position.
• The file format is intentionally permissive, allowing each line to include only the axes or values that need to change.
• When editing an existing .hrpr file, use Save As to preserve the original file and create a separate version of your modified macro.

Examples

Format

The following example shows a portion of a recorded .hrpr macro file, including the header information and recorded motion samples:

(FORMAT_VERSION: 1)
(PROGRAM_NAME: C:\Users\demo\Documents\user\projects\demo\raw//2026-8-14_12-13-19.hrpr)
(DATE: 2026/09/14)
(SAMPLE_RATE: 100)
(POSITION_LEADER: 051D)
(ORIENTATION_LEADER: 1451)
(FOLLOWERS: 
cg_0::Follower(0): Mecademic Industrial Robotics SERIAL (arm);
cg_0::Follower(1): Mecademic Industrial Robotics PARALLEL (end_effector);
)
(DESCRIPTION: a story of two machines)
N1 t1789402399210 {
cg_0::Follower(0): X0.1183887 Y0.0375092 Z0.1076392 rW0.1575889 rX-0.160 rY0.973 rZ-0.051 F0.0008606 Fa0.9414008 J6[0.403,0.157,1.000,-0.936,0.214,0.977] JV6[0.000,0.000,0.000,0.000,0.000,0.000] ,
cg_0::Follower(1): J1[4.800] ,
}
...

Safe Z height

This example shows how a single Z-axis command can be added at line N4 to move the robot to a specified Z position without changing the other axes.

Because omitted axis values are preserved, only the Z-axis is updated during this step.

N1 t1 {
0: X0.184 Y0.004 Z0.141 rW0.0498 rX-0.032 rY0.998 rZ-0.024 F0.00200 Fa0.005
}
N2 t10 {
0: X0.184 Y0.022 Z0.141 rW0.0498 rX-0.032 rY0.998 rZ-0.024
}
N3 t20 {
0: X0.184 Y0.022 Z-0.052 rW0.049 rX-0.032 rY0.998 rZ-0.024
}
N4 t31 {
0: Z0.600
}
N5 t41 {
0: X-0.005 Y0.022 Z-0.6 rW0.049 rX-0.032 rY0.998 rZ-0.024 F0.00010 Fa0.400
}
N6 t51 {
0: X-0.005 Y-0.054 Z0.000 rW0.049 rX-0.032 rY0.998 rZ-0.024
}

Move XY

This example shows how X and Y commands can be used together to move the robot only along those two axes.

At line N5, only the X- and Y-axis values are updated. All omitted axes retain their current values.

N1 t1 {
0: X0.184 Y0.004 Z0.141 rW0.0498 rX-0.032 rY0.998 rZ-0.024 F0.00200 Fa0.005
}
N2 t10 {
0: X0.184 Y0.022 Z0.141 rW0.0498 rX-0.032 rY0.998 rZ-0.024
}
N3 t20 {
0: X0.184 Y0.022 Z-0.052 rW0.049 rX-0.032 rY0.998 rZ-0.024
}
N4 t31 {
0: X0.184 Y0.022 Z-0.600 rW0.049 rX-0.032 rY0.998 rZ-0.024 F0.00010 Fa0.400
}
N5 t41 {
0: X-0.005 Y0.022
}
N6 t51 {
0: X-0.005 Y-0.054 Z0.000 rW0.049 rX-0.032 rY0.998 rZ-0.024
}

Optimizing a Macro

The following example shows an optimized macro in which only the values that need to change are included in each command.

• The robot orientation remains unchanged throughout the sequence.
• The first command moves the robot to the complete target pose using a specified feed rate.
• N2 updates only the Y-axis.
• N3 and N4 update only the Z-axis.
• N5 updates the X-axis and changes the feed rates.
• N6 updates both the Y-axis and Z-axis.

By omitting values that do not change, the macro remains more compact and easier to read or modify.

N1 t1 {
0: X0.184 Y0.004 Z0.141 rW0.0498 rX-0.032 rY0.998 rZ-0.024 F0.00200 Fa0.005
}
N2 t10 {
0: Y0.022
}
N3 t20 {
0: Z-0.052
}
N4 t31 {
0: Z-0.600
}
N5 t41 {
0: X-0.005 F0.00010 Fa0.400
}
N6 t51 {
0: Y-0.054 Z0.000
}