REST API Tutorial

Controling the SageMotion System from an external computer

This tutorial demonstrates using the SageMotion REST API to control the SageMotion system from an external computer. While the REST API can be interfaced from many languages, this example utilizes Python.

1. 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

   

2. 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

3. 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

4. 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

   • After downloading, open FrontalPlaneAngle.py with Notepad++

   • 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)

     # 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

5. 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