Hello World / Read Position

In this tutorial we will set up the most basic app that demonstrates communication with your ORCA motor. The end goal of this tutorial is an application which reads and displays the sensed position of a connected ORCA motor.

---

The Source Code

To begin let’s start with a slightly modified “Hello World” program.

C++

#include <iostream>
#include "actuator.h"

// Everything in orcaSDK is defined under the namespace 'orcaSDK'
using namespace orcaSDK;

int main()
{
        Actuator motor;
        std::cout << "Hello World\n";
        return 0;
}

Python

from pyorcasdk import Actuator

motor = Actuator()

print("Hello World")

This file is largely identical to an implementation of “Hello World”, but here we’ve imported the library and constructed an object of type Actuator.

C++

#include "actuator.h"

Python

from pyorcasdk import Actuator

This import statement gives our file access to the main object in the SDK, the Actuator object. This object is our abstraction for an ORCA linear motor.

C++

Actuator motor;

Python

motor = Actuator()

This line constructs an Actuator object and assigns it to the variable motor.

At this point we now have a virtual representation of an ORCA motor, but it isn’t yet connected to a physical motor. In order to connect to an actual motor, we must open that motor’s corresponding serial port.

C++

#include <iostream>
#include "actuator.h"

int main()
{
        Actuator motor;

        motor.open_serial_port(<your_serial_port_number_here>);

        std::cout << "Hello World\n";
        return 0;
}

Python

from pyorcasdk import Actuator

motor = Actuator()

motor.open_serial_port(<your_serial_port_number_here>)

print("Hello World")

The motor.open_serial_port() function triggers the Actuator object to obtain the serial port indicated by the passed in parameter. For this function, pass in the serial port number of your motor’s rs422 interface. Alternatively, you may pass a string containing the filepath to your serial port.

After calling this method, you now have not only a virtual representation of your ORCA, but a representation that is now connected to your actual motor.

Finally, let’s get some information out of the motor. The most common information needed from the motor is its position, so that’s what we’ll begin with. To display the active position of the motor, add the following lines.

C++

#include <iostream>
#include "actuator.h"

int main()
{
        Actuator motor;

        motor.open_serial_port(<your_serial_port_number_here>);

        std::cout << "Hello World\n";

        while(true) {
                std::cout << "Current Position: " << motor.get_position_um().value << "          \r";
        }

        return 0;
}

Python

from pyorcasdk import Actuator

motor = Actuator()

motor.open_serial_port(<your_serial_port_number_here>)

print("Hello World")

while True:
        print("Current Position: " + str(motor.get_position_um().value), end="       \r")

The new code we’ve added is in an infinite loop. Because of this, it will continue to run until we manually interrupt the program. The only line being executed inside this loop is a line that prints info to the output console. From this line, the only command that we’re particularly interested in is:

... motor.get_position_um().value ...

The function motor.get_position_um() is what retrieves the current shaft position from the motor. This function returns an error object, which is explored in detail in SDK Error Handling. For this example, we ignore the error and simply print the value.

Note

On Infinite Loops

Very often it is the case that code interacting with our motors runs in some form of an infinite loop. In general, it is wise to include some method of escape from the loop, but we ignore that in the tutorials.

Note

Carriage Return

The spaces and '\r' printed after the position value allow the function to clean up and re-print the data on the same line, this is meant simply to clean up what the output looks like when running.

Run Your Program!

With this you have completed writing the most basic SDK program! Try running the program and see what your motor’s position is. Try pushing your motor’s shaft back and forth, and see how it changes the output.

What’s Next?

Each of our tutorials also contains example source code for what the completed tutorial should look like. If you’d like to expedite the tutorials, you can read through and begin playing with the completed examples immediately

All code examples and every tutorial following this will use some simple helper code to prompt the user to input the serial port number of their connected motor so that each file can be run without any edits. This is what that code looks like.

C++

...
int serial_port;
std::cout << "Please input the serial port number of your connected motor. ";
std::cin >> serial_port;

motor.open_serial_port(serial_port);
...

Python

...
serial_port = int(input("Please input the serial port number of your connected motor. "))

motor.open_serial_port(serial_port)
...

Now that you’ve completed the basic orcaSDK tutorial, feel free to browse the remaining tutorials and read them in any order that feels appropriate. If the tutorial you wish to read next contains a prerequisite that you have not read yet, please complete that prerequisite before continuing.

---

Complete Example

C++

#include <iostream>
#include "actuator.h"

using namespace orcaSDK;

int main() {
	Actuator motor;

	int serial_port;
	std::cout << "Please input the serial port number of your connected motor. ";
	std::cin >> serial_port;

	motor.open_serial_port(serial_port);
	
	while (true)
	{
		std::cout << "Current Position: " << motor.get_position_um().value << "          \r";
	}

	return 0;
}

Python

from pyorcasdk import Actuator

motor = Actuator( "MyMotorName" )

serial_port = int(input("Please input the serial port number of your connected motor. "))

motor.open_serial_port(serial_port)

while True:
    print("Current Position: " + str(motor.get_position_um().value), end="        \r")