This wiki is intended for older versions of Motive. For the latest documentation, please refer to
docs.optitrack.com

NatNet: Remote Requests/Commands

Main Page → NatNet SDK → NatNet: Remote Requests/Commands



Remote Requests/Commands

The NatNet SDK features sending remote commands/requests from a client application over to a connected server application (i.e. Motive).

The SendMessageAndWait method under NatNetClient class is the core method for sending remote commands. This function takes in a string value of the command and sends it over to the connected Motive server each time it's called, and once the server receives the remote command, corresponding actions will be performed. Please note that only selected set of commands can be understood by the server; which are listed under the remote commands chart below.

NatNet commands are sent via the UDP connection; 1510 port by default.

Info2.png

For a sample use of NatNet commands, refer to the provided WinFormSample.

NatNetClient::SendMessageAndWait

ErrorCode	SendMessageAndWait( const char* szRequest,
				    void** ppServerResponse, 
					int* pResponseSize );

ErrorCode	SendMessageAndWait( const char* szRequest,
				    int tries, int timeout, 
				    void** ppServerResponse,
				    int* pResponseSize );

Description

Sends a NatNet command to the NatNet server and waits for a response.

Input Parameters:

  • szRequest: NatNet command string, which is one of the commands listed on the below remote commands chart. If the command requires input parameters, corresponding parameters should be included in the command with comma delimiters. (e.g. string strCommand = "SetPlaybackTakeName," + TakeName;).
  • tries: Number of attempts to send the command. Default: 10.
  • timeout: Number of milliseconds to wait for a response from the server before the call times out. Default: 20.
  • ppServerResponse: Server response for the remote command. The response format depends on which command is sent out.
  • pResponseSize: Number of bytes in response

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

Remote Commands

Motive Supported NatNet Commands/Requests
Command (string) Description Parameters (String) Returns
UnitsToMillimeters Sending this command requests current system’s measurement units, in terms of millimeters.


Sample command string:

<source>string command = "UnitsToMillimeters";</source>
 none float
FrameRate Queries for the tracking framerate of the system. Returns a float value representing the system framerate.


Sample command string:

<source>string command = "FrameRate";</source>
 none float
StartRecording This command initiates recording in Motive


Sample command string:

<source>string command = "StartRecording";</source>
 none none
StopRecording This command stops recording in Motive


Sample command string:

<source>string command = "StopRecording";</source>
 none none
LiveMode This command switches Motive to Live mode


Sample command string:

<source>string command = "LiveMode";</source>
 none none
EditMode This command switches Motive to Edit mode.


Sample command string:

<source>string command = "EditMode";</source>
 none None
CurrentMode Requests current mode that Motive is in. Returns 0 if Motive is in Live mode. Returns 1 if Motive is in Edit mode.


Sample command string:

<source>string command = "CurrentMode";</source>
 none int
TimelinePlay Starts playback of a Take that is loaded in Motive


Sample command string:

<source>string command = "TimelinePlay";</source>
 none none
TimelineStop Stops playback of the loaded Take


Sample command string:

<source>string command = "TimelineStop";</source>
 none none
SetPlaybackTakeName Set playback take


Sample command string:

<source>string command = "SetPlaybackTakeName," + stringTakeName;</source>
 Take name None
SetRecordTakeName Set a take name to record.


Sample command string:

<source>string command = "SetRecordTakeName," + stringTakeName;</source>
 Take name None
SetCurrentSession Set current session. If the session name already exists, Motive switches to that session. If the session does not exist, Motive will create a new session/


Sample command string:

<source>string command = "SetCurrentSession," + stringSessionName;</source>
 Session name None
SetPlaybackStartFrame Set start frame


Sample command string:

<source>string command = "SetPlaybackStartFrame," + stringFrameNumber;</source>
 Frame number None
SetPlaybackStopFrame Sets stop frame.


Sample command string:

<source>string command = "SetPlaybackStopFrame," + stringFrameNumber;</source>
 Frame number None
SetPlaybackCurrentFrame Set current frame


Sample command string:

<source>string command = "SetPlaybackCurrentFrame," + stringFrameNumber;</source>
 Frame number None
CurrentTakeLength Request length of current take.

Sample command string:

<source>string command = "CurrentTakeLength";</source>
 None int
AnalogSamplesPerMocapFrame Request number of analog samples per each motion capture frame. This will represent the sampling rate of analog devices as a multiples of the framerate of the camera system.


Sample command string:

<source>string command = "AnalogSamplesPerMocapFrame";</source>
 None int
DisableAsset Disables tracking of a corresponding asset (rigid body / skeleton) from Motive.


Sample command string:

<source>string command = "DisableAsset," + stringNodeName;</source>
 Asset name None
EnableAsset Enables tracking of corresponding asset (rigid body / skeleton) from Motive


Sample command string:

<source>string command = "EnableAsset," + stringNodeName;</source>
 Asset name None
GetProperty Queries the server for configured value of a property in Motive. The property name must exactly match the displayed name. This request string must have the following inputs along with the command, each of them separated by a comma.
  • Node name
  • Property name


Sample command string:

<source>string command = "GetProperty," + stringNodeName + "," + stringPropertyName;</source>

Info2.png

{{{1}}}

  • Node name (if applicable)
  • Property name
 int
SetProperty Requests Motive to configure specified properties. The property name must exactly match the respective name of setting displayed in Motive.


Sample command string:

<source>string command = "SetProperty," + stringNodeName + "," + stringPropertyName + "," + stringPropertyValue;</source>

Info2.png

{{{1}}}

  • Node name. Leave it empty if not applicable.
  • Property name
  • Desired value
 int

Sample Use

Below is a sample use of the NatNet commands from the WinFormsSample application.

Start Recording

private void RecordButton_Click(object sender, EventArgs e)
{
	string command = "StartRecording";

	int nBytes = 0;
	byte[] response = new byte[10000];
	int rc = m_NatNet.SendMessageAndWait(command, 3, 100, out response, out nBytes);
	if (rc != 0)
	{
		OutputMessage(command + " not handled by server");
	}
	else
	{
		int opResult = System.BitConverter.ToInt32(response, 0);
		if (opResult == 0)
			OutputMessage(command + " handled and succeeded.");
		else
			OutputMessage(command + " handled but failed.");
	}
}

Framerate Query

// [NatNet] [optional] Query mocap server for the current camera framerate
int nBytes = 0;
byte[] response = new byte[10000];
int rc;
rc = m_NatNet.SendMessageAndWait("FrameRate", out response, out nBytes);

if (rc == 0)
{
    try
    {
        m_ServerFramerate = BitConverter.ToSingle(response, 0);
        OutputMessage(String.Format("   Camera Framerate: {0}", m_ServerFramerate));
    }
    catch (System.Exception ex)
    {
        OutputMessage(ex.Message);
    }
}

Setting name of the recorded Take

private void SetRecordingTakeButton_Click(object sender, EventArgs e)
{
    int nBytes = 0;
    byte[] response = new byte[10000];
    String strCommand = "SetRecordTakeName," + RecordingTakeNameText.Text;
    int rc = m_NatNet.SendMessageAndWait(strCommand, out response, out nBytes);
}

Setting Motive Properties

private void SetPropertyButton_Click(object sender, EventArgs e)
{
    int nBytes = 0;
    byte[] response = new byte[10000];
    string command = "SetProperty," + NodeNameText.Text + "," + PropertyNameText.Text + "," + PropertyValueText.Text;
    int rc = m_NatNet.SendMessageAndWait(command, out response, out nBytes);
    if (rc != 0)
    {
         OutputMessage(command + " not handled by server");
     }
    else
    {
        int opResult = System.BitConverter.ToInt32(response, 0);
        if (opResult == 0)
            OutputMessage(command + " handled and succeeded.");
        else
            OutputMessage(command + " handled but failed.");
    }
}
Retrieved from "https://v23.wiki.optitrack.com/index.php?title=NatNet:_Remote_Requests/Commands&oldid=13763"