.. _web-api-tutorial:

=======================================
REST API Tutorial
=======================================

**Controling the SageMotion System from an external computer**

.. image:: img/web_api_usage.png
  :width: 800



This tutorial demonstrates using the :ref:`SageMotion REST API<web-api>` to control the SageMotion system from an external computer. While the REST API can be interfaced from many languages, this example utilizes Python.


#. **Install python and required python packages on personal computer**
    - Install python: https://realpython.com/installing-python/
    - Open command prompt and type: ``python -m pip install websocket-client requests``
        .. note:: We use ``pip3 install ‘package name’`` or ``pip install ‘package name’`` to install packages (https://www.w3schools.com/python/python_pip.asp). For this example test app, we install the "websocket-client" and "requests" libraries using the command from above

    .. image:: img/hub_ethernet_connection.png
        :width: 400
        :align: right
#. **Power on Hub**
    - Plug USB-C into the Hub, and the other side of the cable into a USB power supply, (best to use 5V 3A or higher power) 
    - The green power LED on the hub will turn on
#. **Connect Hub to computer**
    - Plug the ethernet end of the ethernet-USB cable into the Sage Hub
    - Plug the USB end into your personal computer
#. **Prepare to run example code FrontalPlaneAngle.py**
    - Example code FrontalPlaneAngle.py gives haptic feedback based on angular rotation in the frontal plane
    - Download FrontalPlaneAngle.py from link here: `FrontalPlaneAngle.py <https://www.sagemotion.com/s/FrontalPlaneAngle.py>`_
    - After downloading, open FrontalPlaneAngle.py with `Notepad++ <https://notepad-plus-plus.org/downloads/>`_
    - Update to the MAC addresses in the sensor_pairings and feedback_pairings parameters. See section marked as  “REPLACE MAC ADDRESSES BELOW WITH YOUR NODE MAC ADDRESSES” **(MAC addresses in code must exactly match those labeled on the back of each node)**

        .. code-block:: python

            # REPLACE MAC ADDRESSES BELOW WITH YOUR NODE MAC ADDRESSES
            request_json = {"sensor_pairings" : ["88:6B:0F:E1:D8:A2"],
                            "feedback_pairings" : ["88:6B:0F:E1:D8:96",
                                                 "88:6B:0F:E1:D8:9F"]}
    - Open a Command Prompt, and navigate to the folder that contains FrontalPlanceAngle.py using the ``cd`` command


#. **Run example code FrontalPlaneAngle.py**
    - From the command line type: ``python FrontalPlaneAngle.py`` 

        .. note:: On some Windows-based computers, you can also just double click the FrontalPlaneAngle.py file to run it 
    - Wait for wireless nodes to connect (up to 20 sec). Once connected, you will see output messages to the command terminal like this::

        Connecting to nodes...    
    
        Connected to Sensors:['88:6b:0f:e1:d8:a2'] Feedback:['88:6b:0f:e1:d8:96', '88:6b:0f:e1:d8:9f']               
        
        Run Iteration 100
        
        Frontal Plane Angle is:
        
        -0.013    

    - Hold the sensor node vertically with the on/off switch pointing upward, as the sensor node is rotated to the left and right and observe haptic feedback vibration from the min_feedback node and max_feedback node when the angle limits are exceeded
    - End the program by pressing ``Ctrl+C`` in the command line