---
title: "MachineLogic Python Programming Guide"
slug: "machinelogic-python-programming-guide"
updated: 2026-06-19T21:21:15Z
published: 2026-06-19T21:21:15Z
canonical: "docs.vention.com/machinelogic-python-programming-guide"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MachineLogic Python Programming Guide

## Table of Contents

1. [Accessing MachineLogic](/technicaldocumentation/docs/machinelogic-python-programming-guide#2-accessing-machinelogic)
2. [Creating a New Python Application](/technicaldocumentation/docs/machinelogic-python-programming-guide#2-programming-your-application-from-machinelogics-python-editor1)
3. [MachineLogic’s Python Editor](/technicaldocumentation/docs/machinelogic-python-programming-guide#2-programming-your-application-from-machinelogics-python-editor)
4. [Adding External Python Modules to your Development Environment](/technicaldocumentation/docs/machinelogic-python-programming-guide#4-adding-external-python-modules-to-your-development-environment)
5. [Complex Applications with Developer Toolkit](/technicaldocumentation/docs/machinelogic-python-programming-guide#5-complex-applications)

### 1. Accessing MachineLogic

To access MachineLogic, your MachineBuilder design must contain:

- A [MachineMotionAI](https://vention.io/parts-library?category=CM&sub_category=MM#q=machinemotion&f-ec_category=CM%7CCM-MM) Controller
- One or many of the following automation components:
  - [Linear Motion](https://vention.io/parts-library?category=MV)
  - [Rotary Motion](https://vention.io/parts-library?category=RO)
  - [Pneumatics](https://vention.io/parts-library?category=PN)
  - [Material Handling](https://vention.io/parts-library?category=CV)
  - [Control and Motors](https://vention.io/parts-library?category=CM)
  - [Sensors](https://vention.io/parts-library?category=SE)
  - [Robots](https://vention.io/parts-library?category=RB)

Once your automation component(s) have been added to a design, their configuration properties will be shown in the **Configuration** pane:

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(616).png)

The configuration data is automatically populated once the corresponding device has been added to the design. For more information on each device’s configuration properties, select one of the links below:

- [Linear actuators, rotary actuators and conveyors](/technicaldocumentation/docs/machinemotion-ai-actuator-configuration)
- [Pneumatic actuators](/technicaldocumentation/docs/pneumatic-ecosystem)
- [Robots](/technicaldocumentation/docs/robot-programming-and-scene-assets-in-machinelogic)
- [Inputs and Outputs](/technicaldocumentation/docs/digital-io-module-user-manual)
- [Power Switch modules](/technicaldocumentation/docs/power-switch-module-user-manual)

Once the automation devices have been added to the design, access MachineLogic by selecting the **MachineLogic** tab at the top of the MachineBuilder toolbar:

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(597).png)

### 2. Creating a New Python Application

#### Option 1: Create App dropdown

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(598).png)

#### Option 2: Generate app with Vention Copilot

Describe what you want your python app to do, and Vention Copilot will create and open it for you.

The Copilot has context of your machine **Configuration** and [**Scene Assets**](/technicaldocumentation/docs/robot-programming-and-scene-assets-in-machinelogic), so you can refer to them directly in the prompt.

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(599).png)

### 3. MachineLogic’s Python Editor

The Python Editor feature is a cloud implementation of VSCode. To learn more about its functionalities and features, consult the VS Code documentation [here](https://code.visualstudio.com/docs). You can drag to resize the MachineLogic Python Editor or use this button to collapse it completely: ![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(629).png)

Every new Python application contains two files by default, [**main.py**](/technicaldocumentation/docs/machinelogic-python-programming-guide#38-mainpy) and [**project.json**](/technicaldocumentation/docs/machinelogic-python-programming-guide#37-projectjson)

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(600).png)

#### 3.1. Left Side Panel

The collapsible side panel is used to display either the Explorer, Search or Extension functions. The Explorer is displayed by default.

**Explorer** The Explorer is used to create files and directories contained in an application. it is possible to upload files and directories by Drag and Dropping content directly over the Side Panel.

Use this icon: ![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781901569282.png)

**Search** Use Search to quickly query the application to find or replace code snippets.

Use this icon:![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781901519612.png)

**Extensions** Extensions are provided by the VS Code community and allow access to additional functionalities that can be installed to the current application.

Use this icon: ![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781901486183.png)

**Vention Extension Toggle** Toggles the [Bottom Panel](/technicaldocumentation/docs/machinelogic-python-programming-guide#37-bottom-panel) of the editor that shows and hides the Terminal, Copilot, and Logs tab

Use this icon: ![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781901450697.png)

#### 3.2. Top Bar

**Application Name**

**![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781903461389.png)**

The Application name can be double-clicked to edit the name of your application:

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(621).png)

You can also Download, Duplicate or Delete the app via the application dropdown:

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(620).png)

**Deploy**

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781903304671.png)

The deployment buttons are used to access One-Click-Deploy functionalities. To learn more about deployment of your application, [click here](/technicaldocumentation/docs/deploy-your-application-and-configuration-to-controller).

**Edit HMI**

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781903440342.png)

Edit HMI button opens access to the HMI Builder. HMI Builder is a feature that can be used to create Operator Interfaces that allow interaction with the application.

To learn more about HMI builder, [click here](/technicaldocumentation/docs/custom-hmi-development).

**Run Button**

**![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image-1781903424609.png)**

Use this button to launch or interrupt the simulation. On click of the “Run” button, the **Logs** tab of the bottom panel will be focused to follow the application logs output.

#### 3.3. Bottom Panel

The bottom panel is used to access the **Terminal**, the Process **Logs** of your running application, or the Vention **Copilot** tool.

**Terminal:** A fully integrated terminal that starts at the root of your workspace and enables working in the shell of your choice without leaving the editor

**Logs** The logs display information about running processes and provide error reporting and debugging help. ![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(603).png)

**Copilot** Copilot enables AI assistance for programming your application using Vention’s Python API. Once a prompt has been entered, code modifications can be directly applied in the application. Use Copilot to speed up your development time and learning curve when programming with Vention’s Python API (machine-logic-sdk).

- The Copilot is pre-populated with context of the machine’s Configuration and any robot Scene Assets already in your design.
- The Copilot agent suggests changes that the user can “Apply” and “Accept” directly in their application.

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(602).png)

> Tip: Paste log errors from the **Log** tab directly into it to the **Copilot** to quickly debug and solve issues in your application.

#### **3.4. MachineLogic Right Pane**

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(622).png)

**Configuration Panel**

See [Accessing MachineLogic](/technicaldocumentation/docs/machinelogic-python-programming-guide#2-accessing-machinelogic) for more information

**Scene assets Panel**

The scene Assets pane is where robot programming Assets are displayed. To learn more about Scene Assets and how to use them to generate robot motion, [click here](https://docs.vention.com/technicaldocumentation/docs/robot-programming-and-scene-assets-in-machinelogic)

**Simulation Panel**

- Device Emulation:
  - The simulation panel allows for the emulation of IO devices and push buttons added to the design. When these devices are configured, they will show in the simulation pane and allow interactions with the program and application when the simulation is running. Emulation is supported for the following devices: [PushButton module](https://vention.io/parts/latching-pushbutton-module-1202) [Digital I/O module](https://vention.io/parts/digital-io-module-v2-1464) [Estop Module](https://vention.io/parts/e-stop-module-1626) [Estop Module W/ reset](https://vention.io/parts/e-stop-module-with-reset-1078)
- Cycle Time

Use this button at the bottom of the Simulation pane to access the Cycle Time:

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(628).png) The Cycle time functionality displays both cycle time and cycle count when playing a program in simulation. To calculate cycle time, the application must contain both a [MachineAnalytics](/technicaldocumentation/docs/machineanalytics) Cycle Start and Cycle End events. Both commands are found in the Set Output Category.

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(617).png)

  

#### 3.5. Program Entrypoint: main.py

This file will be executed by default when launching your application. This is where most of the control code for your application should be written. This file is pre-populated with initialization code so you can start programming your application as soon as the application is created.

Here is an example of the initialization code for a new application containing a robot, conveyor and a digital output:

```python
from machinelogic import Machine, ActuatorGroup
from machinelogic import MachineException, MachineMotionException, ActuatorGroupException, ActuatorException, RobotException, DigitalOutputException

### Configuration ###

# The following code has been automatically generated from the configuration.
# If the configuration changes, please update the code below, and ensure that the names match.

machine = Machine()
scene = machine.get_scene()
my_controller__1 = machine.get_machine_motion("Controller #1")

# Configured Actuators
my_conveyor = machine.get_actuator("Conveyor")
# Configured Robots
robot = machine.get_robot("New robot")
# Configured Outputs
my_gripper = machine.get_output("Gripper")

### Prgram ###

# Start coding here!
# Documentation can be found at /technicaldocumentation/docs/

print("Hello, Vention")
```

Notice how the content of the configuration is automatically populated in the **main.py** file using commands from the API:

```python
# Configured Actuators
my_conveyor = machine.get_actuator("Conveyor")
# Configured Robots
robot = machine.get_robot("New robot")
# Configured Outputs
my_gripper = machine.get_output("Gripper")
```

> **Tip:** These commands use the friendly names as defined in the configuration page, any changes made to the configuration prior to the creation of the app will have to be manually adjusted in the main.py file afterwards.

Using a single **main.py** file as the entry point for simulation is the most straightforward way to simulate your python application from the web environment using [Vention’s Python API](/technicaldocumentation/docs/vention-python-api). However, specifying additional simulation entry points is possible by configurating the **project.json** file

#### 3.6. project.json

Using the **project.json**, file you can specify what bash commands you want to run when playing the application. This makes it possible to launch multiple processes simultaneously as specified in the **project.json** file, enabling enabling the creation of more scalable and modular Python apps. Complex applications can be broken down into different processes running in parallel.

By default, the **project.json** file specifies the **main.py** file as the single entry point:

```json
{
  "processes": {
    "onPlay": [
      {
        "name": "MachineCode App","command": "python3 -u main.py"
      }
    ]
  }
}
```

> **Tip:** Adding the -u command line option when running python scripts allow for the stdout and stderr streams to be unbuffered, allowing for proper log output in the “LOGS” tab

to specify additional processes, add them to the **project.json** file as shown in the example below:

```json
{
  "processes": {
    "onPlay": [
        { "name": "Process 1", "command": "python3 -u Process 1.py" },
        { "name": "Process 2", "command": "python3 -u Process 2.py" },
        { "name": "Server process", "command": "node web_server.js", "port": 3020 },
     ]
  }
}
```

Notice how the example above also contains the port number when launching a web server process. In the example below, pressing the play button will simultaneously launch Process 1.py, Process 2.py and web_server.js.

For access to python applications example, [click here](/technicaldocumentation/docs/machinelogic-application-library)

### 4. Adding External Python Modules to your Development Environment

If your application requires special python packages, create a `requirements.txt` file in your application and list all required modules. When the “Run” button is clicked, a separate process will run to create and activate `venv` for all packages specified.

![](https://cdn.document360.io/3eee4d14-5ca0-4ea6-b426-1c19393e6a5e/Images/Documentation/image(627).png)

> [!WARNING]
> The proper `machine-logic-sdk` version compatible with your MachineMotion controller should also be specified in the `requirements.txt` file. See [Python API documentation](/technicaldocumentation/docs/vention-python-api) for compatibility table.

### 5. Complex Applications with Developer Toolkit

Creating python apps to control your machine is the tip of the ice burg. To learn more about developing complex applications with rich UI’s, persisted state, state-machines and more, please refer to our **Developer Toolkit** by [clicking here](/technicaldocumentation/docs/introduction-to-the-vention-developer-toolkit).