--- title: "Vicon Evoke API & automation" canonical: "https://help.vicon.com/space/Evoke17/10814590/Vicon%20Evoke%20API%20%26%20automation" format: markdown --- > Macro (scroll-ignore) > > ![image](media://2f0c235d-3bf2-43bb-a546-0f6c793ca05c) Evoke includes an extensive Application Programming Interface (API) for remote control, system monitoring and third-party application integration. The API has two parts, both of which are covered in this section of the guide. > Macro (scroll-only) > > > Macro (toc) For information on running entirely via the API, without the Graphical User Interface (GUI), see [Headless operation](#Headless). # Vicon Core API The Vicon Core API provides the core functionality for client/server communication, and schemas that define the types, functions and callbacks supported by the Vicon application. It is a generic JSON-based protocol operating over TCP. Evoke opens the server socket on port 52800 by default. To specify the port number, launch Evoke with a command-line argument: `C:\Program Files\Vicon\Evoke1.7\Evoke.exe --terminal-port=52800` A sample exchange may look like this (debug logging has been turned on for the ViconCoreAPI category, so all messages sent and received are logged): **ViconCoreAPI client-server exchange** ```diff 2019.09.13 13:42:38.123 +1 Default ViconCoreAPI Starting Vicon Core API server on port 52800... 2019.09.13 13:42:38.456 +1 Default ViconCoreAPI Opened connection to 127.0.0.1:53926 2019.09.13 13:42:38.629 +1 Debug ViconCoreAPI Sending to 127.0.0.1:53926 [4,0][] 2019.09.13 13:42:38.631 +1 Debug ViconCoreAPI Received from 127.0.0.1:53926 [Terminal.AppInfo,5] [] 2019.09.13 13:42:38.632 +1 Debug ViconCoreAPI Sending to 127.0.0.1:53926 [5,0]["Evoke","1.7.0.0","0"] 2019.09.13 13:42:38.645 +1 Debug ViconCoreAPI Received from 127.0.0.1:53926 [ApplicationServices.Shutdown,6] [] 2019.09.13 13:42:38.730 +1 Debug ViconCoreAPI Sending to 127.0.0.1:53926 [6,0][""] ``` > Macro (scroll-pagebreak) This trace shows two commands sent to the server as JSON-encoded strings, in the format `[SchemaName,CommandId] [Data]`: - `Terminal.AppInfo` This is a built-in Vicon Core API command that returns the current application information. - `ApplicationServices.Shutdown` This is an Evoke API command that safely closes down the application, releasing all resources and writing settings files as required. Each command is assigned a unique number by the client, and this number is sent back by the server with the reply, with the format `[CommandId,ResultCode][Data]`. This enables the client to match replies to the correct command. # Evoke API The Evoke API is a client library that facilitates access to the services provided by Evoke. It includes all the schemas supported by the application, and classes for the data types exchanged via API. It is also responsible for serializing user data into JSON for transmission to the Vicon Core API server, and deserializing the replies back into user data. Evoke API is compatible with Python 2.7 and Python 3.7 and later. > Macro (scroll-pagebreak) The following services are currently provided: - **Application services** – System file management, license information and application shutdown - **Basic object services** – Management of basic objects - **Camera calibration services** – Camera calibration operations and file management - **Camera device services** – Camera information, monitoring and control - **Capture services** – Data capture and control - **Character from clusters services** – Management of characters from clusters - **Cluster device services** – Smart cluster device information, monitoring and control - **Log services** – Logging control - **Object evaluation services** – Control of object evaluation (for basic and smart objects) - **Playback services** – Data review and playback control - **Radio device services** – Radio device information, monitoring and control - **Selection services** – Selection and deselection of all device types - **Smart object services** – Management of smart objects - **Subject services** – Import and export of basic objects and overall tracking configuration - **System health services** – Monitoring of system and camera calibration health - **View services** – View file management Client libraries are supplied for C# and Python, located by default at: `C:\Program Files\Vicon\Evoke1.7\SDK` Instructions for use and full documentation are included in the packages. A limited dashboard application is provided for C#, together with a number of sample Python scripts. > Macro (scroll-pagebreak) ## Install the Evoke API To use the Evoke API with Python, you must make sure that you have both installed. The Evoke API provides support for Python 2.7 and Python 3. Vicon recommends that you use the latest full release of Python 3, unless your project requires you to use a specific version of Python. These procedures guide you through the installation process: - [Check Python version](#CheckPython) - [Installing Python](#InstallPython) - [Installing the Evoke Python module](#InstallTrackerModule) - [Check that the Python module installed correctly](#CheckPythonModule) ### > Macro (anchor) Check Python version If you are not sure if you have Python installed or which version of Python you are using, you can open a command prompt and run the *py* command. For example: ```plaintext c:\>py Python 3.11.3 (tags/v3.11.3:f3909b8, Apr 4 2023, 23:49:59) [MSC v.1934 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> ``` If you do not have Python installed, see [Install Python](#InstallPython). > Macro (scroll-pagebreak) ### > Macro (anchor) Install Python **To install Python 2 or 3:** 1. Go to [https://www.python.org/downloads/](https://www.python.org/downloads/) 2. Locate the required version and install Python, ensuring that **Add python.exe to PATH** is selected: In the above image, *ABC* is replaced with your username for the installation folder. ### > Macro (anchor) Install the Evoke Python module The following steps assume you are using Python version 3 and Evoke 1.7. **To install the Evoke Python module:** 1. Locate the installation files. If you installed Evoke in the default location, they are found in this folder: *C:\Program Files\Vicon\Evoke1.7\SDK\Python * These folders and files are displayed: - *evoke_api* - *sample_scripts* - *vicon_core_api* - *install_evoke_api.bat* - *readme.txt* - *uninstall_evoke_api.bat* 2. Install the Evoke Python module in either of the following ways, depending on your particular installation: - The simplest way is to run the batch file (*install_evoke_api.bat*) that is included in the Evoke installation (as shown in the previous image). This usually works well if: - Python was installed to the PATH variable; or - Multiple versions of Python are installed, but you want to install the API to the latest version that you installed; or - Only a single version of Python is installed. If any of these conditions apply, see [Install the python module by running the batch file](#BatchFile). - In all other cases, install the Python module by using pip. This usually applies if: - Multiple versions of Python are installed, but you want to install to a specific version; or - Multiple different versions of Python are installed and you want to install to all of them (in this case, you must install the module for each version); or - Only a single version of Python is installed, but you didn't install to PATH. If any of these conditions apply, see [Install the Python module by running pip](#InstallPIP). ### > Macro (anchor) Install the Python module by running the batch file To do this: 1. Navigate to the Python install folder: *C:\Program Files\Vicon\Evoke1.7\SDK\Python* 2. Double-click *install_evoke_api.bat*. This will open the Command Prompt that runs the installation process initializes automatically. ![image](media://372262c2-1234-4e77-aee1-ab35a44181c1) ### > Macro (anchor) Install the Python module by running pip > ❌ **Caution** > ❌ > ❌ > ❌ If you are using Python 3, you must copy the *SDK* folder from the *Program Files* directory to a new folder that doesn't require Administrator permission. This is due to a permissions issue with pip versions 21.3 or later. > ❌ > ❌ By default, you can find the *SDK* folder at *C:\Program Files\Vicon\Evoke1.7\SDK* (if you installed Evoke in another location, use this path to find the SDK folder). > ❌ > ❌ We recommend copying the *SDK* folder into a new folder with an easy-to-access location, for example, "*C:\EvokeAPI*". You can delete this folder after the pip installation is complete. > ❌ > ❌ > ❌ **The steps in this guide assume you have copied the *****SDK***** folder to *****C:\EvokeAPI*****.** 1. Navigate to the *Scripts* folder for the Python that you want to use: - For Python 3, the default installation folder is: *C:\Users\\AppData\Local\Programs\Python\Python311\Scripts* - For Python 2.7, the default installation folder is:*C:\Python27\Scripts* 2. Open a command window or powershell in that folder. 3. Run the following command to install the Vicon Core API: 4. Run the following command to install the Evoke API: > ℹ️ **Note** > ℹ️ The above examples use a Python 3.11 installation with Evoke 1.7. Your path and commands may differ slightly. ### > Macro (anchor) Check that the Python module installed correctly Check that the following modules have been installed: - **vicon_core_api**: This is the core remote control API and includes a client for communication with the terminal server. - **evoke_api**: Services API for accessing evoke specific application functionality. To test that the Evoke Python module installed correctly, try importing one of the modules in Python: ```plaintext >>> import vicon_core_api ``` If the above process fails to recognize the module, try the following: - Check the *site-packages* folder in the Python installation for the *evoke_api* or*vicon_core_api* folder. For Python 3.11, the location of the default installation folder is: *C:\Users\\AppData\Local\Programs\Python\Python311\Lib\site-packages* - Check your system environment variables and ensure that the scripts folder for the Python installation you want to use is the highest in the list. For Python 3.11, the default location of the installation folder is: *C:\Users\\AppData\Local\Programs\Python\Python311\Scripts* If either of the modules folders is missing, and you have verified the path, re-run through the installation process described in [Installing the evoke Python module](#InstallTrackerModule). # Connect to the terminal server To connect to the terminal server, first import the Vicon Core API module: ```plaintext >>> import vicon_core_api >>> from vicon_core_api import * ``` Next, create a client. This automatically tries to connect to the specific host address on the default port (52800) ```plaintext >>> c = Client('localhost') ``` Check that the client successfully connected to the server: ```plaintext >>> print(c.connected) True ``` If the response is `False`, ensure that you have an instance of Evoke running at the specified host address and your firewall is not blocking traffic on port 52800, before creating a new client. When you have successfully connected, you can access the services provided by the Evoke terminal server. > Macro (scroll-pagebreak) This example uses basic object services: ```plaintext >>> import evoke_api >>> from evoke_api import BasicObjectServices >>> services = BasicObjectServices(c) ``` When it is connected, you can call methods on the Evoke instance. For example, to get a list of objects in the Tracking panel, use: ```plaintext >>> result, object_list = services.basic_object_list() >>> print(result) Ok: the function succeeded >>> print(object_list) ['Object1', 'Object2'...] ``` All API calls return a result code, which are described in vicon_core_api/result.py. One possible failure code is `Result.RPCNotConnected`, which is received if the connection to the terminal server is lost. For example: ```plaintext >>> result, object_list = services.basic_object_list() ... vicon_core_api.client.RPCError: RPCNotConnected: The connection to the remote function or callback is not open ``` To display a list of all available functions and documentation: ```plaintext >>> help( evoke_api) ``` # Example scripts You can find example scripts showing the use of common API functions at: * "C:\Program Files\Vicon\**Evoke1.7**\SDK\Python\sample_scripts"* All the scripts have documentation and take a --help option that gives details of the relevant arguments. To run a sample script, open a command window or power shell in the scripts folder above. You can do this in one of these ways: - Open the command prompt and change your directory to the scripts folder: `C:\> cd "` `C:\Program Files\Vicon\Evoke1.7\SDK\Python\sample_scripts"` or - SHIFT+right-click in the scripts folder and select *Open command window here* or *Open Powershell window here*. From here you can run the example script of your choice. > Macro (scroll-pagebreak) The following examples use the command window. ### camera_calibration_wave.py This script demonstrates how to use API functions to control the calibration process of starting and stopping the wand wave. ```plaintext C:\Program Files\Vicon\Evoke1.7\SDK\Python\sample_scripts> py camera_calibration_wave.py ``` If successful, calibration controls are displayed. ![image](media://10cce97c-2767-4ca7-9d93-abd240f2ebdd) ### capture_control.py This script shows how to capture live data. ```plaintext C:\Program Files\Vicon\Evoke1.7\SDK\Python\sample_scripts> py capture_control.py ``` ![image](media://27827318-dade-46dc-b5cd-cc2953015d4a) The Capture name is listed before the controls. To change the capture name, use `capture_services` and `SetCaptureName`. For questions on using the Evoke API, contact [Vicon Support](mailto:support@vicon.com). # > Macro (anchor) Headless operation Evoke may be operated entirely via API, in which case it may be advantageous to run without the Graphical User Interface (GUI). A separate executable is provided for this purpose: `C:\Program Files\Vicon\Evoke1.7\EvokeHeadless.exe` Headless operation may be more suitable for running Evoke as a service, and additionally benefits from slightly lower CPU usage without the overhead of running a GUI. System and tracking setup must normally be completed with the GUI, as some setup functionality is not yet available via the API. For more information, see [Evoke Headless](https://vicon-help.atlassian.net/wiki/spaces/Evoke17/pages/10816832/Evoke+command+line+options#Evoke) in the *Vicon Evoke Reference Guide*.