.. _hello-world-read-position:

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.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			#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;
			}

	.. tab-item:: Python
		:sync: python

		.. code-block:: 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``.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			#include "actuator.h"

	.. tab-item:: Python
		:sync: python

		.. code-block:: 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.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			Actuator motor;

	.. tab-item:: Python
		:sync: python

		.. code-block:: 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.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			#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;
			}
		

	.. tab-item:: Python
		:sync: python

		.. code-block:: 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.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. code-block:: cpp

			#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;
			}
			
	.. tab-item:: Python
		:sync: python

		.. code-block:: 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:

.. code-block:: 

	... 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 :ref:`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.

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp
			
		.. code-block:: cpp

			...
			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);
			...

	.. tab-item:: Python
		:sync: python

		.. code-block:: 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
----------------

.. tab-set::
	:sync-group: language

	.. tab-item:: C++
		:sync: cpp

		.. literalinclude:: Hello-World-Read-Position/main.cpp
			:language: cpp
			
	.. tab-item:: Python
		:sync: python

		.. literalinclude:: Hello-World-Read-Position/main.py
			:language: python