Python Native

How to use the Python Native robot skill

Run real CPython directly from ARC.

This is not a limited Python implementation or a Python-like scripting language. It is the same CPython interpreter you would run from a command prompt, with access to the full Python package ecosystem.

Install packages such as:

pip install numpy
pip install opencv-python
pip install torch
pip install requests
pip install pyserial
pip install mediapipe

You can also install your own packages and use them to control your robot.

The Python skill launches a genuine CPython process alongside ARC and connects the two through a fast local bridge. This gives Python access to ARC while preserving everything that makes normal Python useful: third-party packages, native modules, threading, virtual environments, development tools, and the standard library.

---

Getting Started

1. Add the Python skill to your ARC project.
2. If Python is already installed, the skill automatically searches for it and displays the selected interpreter in the status bar.
3. If Python is not installed, open Config Interpreter Download a private Python for ARC.
4. Press Run.

The private Python option downloads CPython directly from python.org into:

%LOCALAPPDATA%\ARC\PythonSkill

It also configures pip automatically and does not modify the rest of your computer.

A new Python skill includes an example script that:

• Prints the Python version.
• Lists the other robot skills in the project.
• Publishes a Greet ControlCommand.

---

The Window

Run

Press Run or F5 to execute the file currently selected in the editor.

Stop

Press Stop or Shift+F5 to stop the running script.

Restart

Restart terminates the current Python interpreter and launches a new one.

Use Restart after installing or updating Python packages so the new interpreter can load them.

Editor

The built-in editor includes:

• Python syntax highlighting.
• Find and replace with Ctrl+F.
• ARC API autocomplete.
• Multiple Python files.
• Normal Python module imports.

Press Ctrl+Space, or begin typing:

arc.

to browse the ARC API.

Use New File to create additional Python modules. Files within the workspace can import one another using normal Python imports.

Console

The Console displays output from the Python process.

Normal print() output is displayed normally, while stderr output is shown in red. Messages generated by the Python skill itself are displayed in grey.

The >>> field below the Console is a live Python REPL running inside the namespace of your current script.

This means you can inspect variables, call ARC APIs, test expressions, move a servo, or experiment with code without restarting your script.

Published Commands

The Published Commands panel lists ControlCommands exposed by your Python script.

Double-click a command to copy its ARC call syntax.

---

Talking to ARC from Python

Import the ARC module:

import arc

The arc module is the connection between your Python process and ARC.

---

Robot Subsystems

ARC subsystems are exposed as attributes of the arc module and use the same method names available from ARC's built-in Python and JavaScript scripting environments.

arc.Servo.SetPosition(arc.D0, 90)
arc.Servo.SetVelocity(arc.D0, 25)

arc.Movement.Forward(255, 1000)

arc.Audio.SayWait("hello world")

arc.Digital.Set(arc.D5, True)

distance = arc.Ping.Get(arc.D1, arc.D2)
light = arc.ADC.Get(arc.ADC0)

Available subsystems include:

Servo
Movement
Audio
Digital
ADC
PWM
I2C
UART
Ping
Net
File
Com
Navigation
EZB
Utility
Console

ARC ports are also available as module constants:

arc.D0
arc.D1
arc.D2

arc.V0
arc.V1

arc.ADC0
arc.ADC1

Digital ports continue through arc.D23.

Every method also includes a snake_case alias if you prefer Python naming conventions.

For example:

arc.Servo.SetPosition(arc.D0, 90)

can also be written as:

arc.Servo.set_position(arc.D0, 90)

The API exposed to Python is generated from the version of ARC you are currently running. This prevents the Python API from becoming outdated as ARC changes.

You can inspect the API from the REPL using normal Python tools:

dir(arc.Servo)

or:

help(arc.Servo.SetPosition)

---

Global Variables

ARC global variables can be read and written directly from Python.

arc.setVar("$distance", 42)

arc.setVar("$readings", [1, 2, 3])

value = arc.getVar("$distance")

Lists are automatically converted to ARC variable arrays.

You can also use dictionary-style access:

arc.vars["$distance"] = 42

if "$distance" in arc.vars:
  print("Variable exists")

variables = arc.vars.all()

To wait for an ARC variable to reach a specific value:

arc.wait_for_var("$SpeechPhrase", "go", timeout_ms=5000)

---

Calling Other Robot Skills

Python can execute ControlCommands published by other robot skills.

arc.controlCommand(
  "Speech Recognition",
  "PauseListening"
)

arc.controlCommand(
  "Auto Position",
  "AutoPositionAction",
  "Wave"
)

You can also discover available ControlCommands programmatically:

for command in arc.list_commands():
  print(command["code"])

This makes it possible for a Python script to discover and interact with the rest of an ARC project dynamically.

---

Camera Access

One of the biggest advantages of running real CPython is direct access to libraries such as OpenCV.

The Python skill can retrieve the current ARC camera frame as a NumPy-compatible BGR image.

import cv2
import arc

frame = arc.camera.get_frame()

gray = cv2.cvtColor(
  frame,
  cv2.COLOR_BGR2GRAY
)

faces = cascade.detectMultiScale(
  gray,
  1.1,
  5
)

for (x, y, w, h) in faces:
  cv2.rectangle(
    frame,
    (x, y),
    (x + w, y + h),
    (0, 255, 0),
    2
  )

arc.camera.set_frame(frame)

Calling:

arc.camera.get_frame()

returns the current camera image as a BGR NumPy array.

Calling:

arc.camera.set_frame(frame)

pushes the modified image back into ARC so other robot skills can see it.

If you do not need NumPy, you can retrieve raw JPEG data instead:

jpeg = arc.camera.get_jpeg()

To list Camera Device robot skills in the project:

arc.camera.list()

Camera functions also accept an optional camera name when a project contains more than one Camera Device skill.

---

Stopping Scripts Cleanly

For cancellable delays, use:

arc.sleep()

instead of:

time.sleep()

arc.sleep() returns early when the user presses Stop.

For example:

while not arc.is_cancelled():
  arc.Servo.Increment(arc.D0, 5)

  arc.sleep(100)

You can also register cleanup code that runs when a script stops:

@arc.on_stop
def cleanup():
  arc.Servo.ReleaseAll()

The Python skill uses several levels of cancellation to prevent a badly behaved script from blocking ARC.

When Stop is pressed, the skill attempts:

1. Cooperative cancellation.
2. A Python KeyboardInterrupt.
3. Process termination and interpreter restart.

If a script becomes stuck inside a native library call, ARC itself remains responsive.

---

Talking to Python from ARC

Python functions can be published as ARC ControlCommands.

Decorate the function with:

@arc.command()

For example:

@arc.command(
  "Detect",
  "Look for an object in the camera",
  params=["object name"]
)
def detect(target):
  frame = arc.camera.get_frame()

  labels = run_your_model(frame)

  return target in labels

The command can then be called from ARC Script, Blockly, JavaScript, another Python script, or another robot skill.

For example:

var found = ControlCommand(
  "Python",
  "Detect",
  "person"
)

Return values are sent back to the caller.

This allows a Python skill to operate as a reusable function library for the rest of your ARC project.

---

Resident Scripts

Publishing a ControlCommand keeps the Python interpreter resident.

After the script's top-level code finishes, background threads can continue running and published command handlers remain available.

The status bar displays:

Resident

while the interpreter is waiting for commands.

If a script does not publish any commands and has no remaining work, it simply runs to completion and stops normally.

---

Python Skill ControlCommands

The Python skill also publishes several ControlCommands of its own.

Command	Purpose
Run	Run the main Python script
RunFile(name)	Run a specific Python file
Stop	Stop the running script
StartInterpreter	Start Python without executing a script
RestartInterpreter	Terminate and restart Python
Eval(expression)	Evaluate an expression inside the script namespace and return the result
IsRunning	Determine whether a script is currently running
SetFileContents(name, code)	Replace the contents of a Python file without running it

RestartInterpreter is especially useful after installing or upgrading Python packages.

---

Packages

Select Packages from the toolbar to manage Python packages using pip.

Enter requirements using the same syntax as a standard requirements.txt file:

numpy
opencv-python==4.10.0.84
requests>=2.31

Install the packages and then press Restart so the interpreter can load them.

Package requirements are saved with the ARC project. When the project is opened on another computer, the project therefore retains a record of the Python dependencies it requires.

---

Virtual Environments

The Python skill automatically detects common virtual environment folders inside the workspace.

Supported names include:

.venv
venv
env

If one of these exists, the skill automatically uses it as the Python environment for the workspace.

---

Working in VS Code

The Python skill can also be used with an external editor such as Visual Studio Code.

In the configuration menu, change Source of truth to:

Folder

The .py files stored in the workspace folder then become authoritative.

You can edit the code in VS Code, save it, and press Run in ARC. The latest saved version on disk is what ARC executes.

Use Open Folder in the toolbar to open the workspace.

---

ARC API IntelliSense in VS Code

Each time the Python environment starts, the skill writes:

arc.pyi

into the workspace.

This Python type stub is generated directly from the ARC API available in the running version of ARC.

Point VS Code at the workspace and you receive completion and signature information for APIs such as:

arc.Servo.SetPosition

as well as the rest of the ARC API.

Because the stub is generated from ARC itself, it automatically stays synchronized with the installed ARC version.

---

Project Mode

Project is the default source-of-truth mode.

In Project mode, Python source code is stored directly inside the ARC .ezb project.

This makes the Python code part of the project itself, so sharing the ARC project also shares its Python files.

Before execution, the files are still written into the workspace directory. This allows Python imports between your own modules to work normally.

---

Configuration

The Python skill configuration is divided into several areas.

Interpreter

The Interpreter section controls which Python executable the skill uses.

It displays Python installations discovered on the computer and provides the option to download a private Python installation specifically for ARC.

Leave the interpreter path empty if you want ARC to automatically select the best interpreter it discovers.

---

Startup

Startup settings control how Python behaves when an ARC project opens.

Options include:

• Start the Python interpreter automatically.
• Run the main script automatically.
• Relaunch Python after an unexpected crash.
• Select the main Python file.
• Configure the amount of Console scrollback retained.

Starting the interpreter and running the main script automatically are enabled by default because handlers created using @arc.command do not exist until the script defining them has executed.

---

Workspace

Workspace settings control where the Python environment operates.

Options include:

• Source-of-truth mode.
• Workspace folder.
• Additional sys.path entries.
• Environment variables supplied to the Python child process.

---

Troubleshooting

No Python interpreter was found

Open:

Config Interpreter Download a private Python for ARC

The skill will download and configure a private Python installation.

Alternatively, install Python from python.org and enable:

Add Python to PATH

during installation.

Then select Search Again in the Python skill.

---

A Package Installed but Python Cannot Import It

Restart the interpreter.

A Python process that was already running does not automatically recognize packages that were installed after it started.

Press:

Restart

and try the import again.

---

The Interpreter Will Not Start

Set the environment variable:

ARCPY_DEBUG_LOG

to a writable file path before launching ARC.

For example:

C:\Temp\arcpy.log

The Python side will then record communication between Python and ARC to the specified file.

This includes startup information and the reason the bridge stopped or failed to initialize.

When the Python-to-ARC bridge itself is failing, the normal Console may not be able to display the error because that Console depends on the same bridge.

For that reason, the ARCPY_DEBUG_LOG file is the most useful diagnostic information to include with a support post involving interpreter startup failures.

---

Red Console Lines That Are Not Errors

Some Python libraries intentionally write status or progress information to stderr.

Certain native libraries may also write directly to the operating system's raw stdout handle.

The Python skill redirects these writes to protect the communication bridge, and ARC displays them as red Console output.

Red text therefore does not always indicate that something has failed.

---

Changing the Skill Title Moved My Files

By default, the workspace folder is based on the robot skill's name.

Changing the skill title can therefore cause the default workspace location to change.

To prevent this, open the Workspace configuration and pin the workspace to a specific folder.

---

Notes and Limitations

One Script at a Time Per Skill Instance

Each Python skill contains one Python interpreter, and a single interpreter executes one primary script at a time.

If you need two independent Python environments running in parallel, add two Python skills to the ARC project.

Each instance receives:

• Its own Python interpreter.
• Its own Python process.
• Its own workspace.

The two skills can therefore operate in parallel.

Within a single Python skill, you can also use Python's standard:

threading

module for background or concurrent work.

The full Python standard library is available.

---

A Script Cannot ControlCommand Its Own Python Skill

A Python script cannot issue a ControlCommand back to the same Python skill instance that is currently executing it.

Doing so could create a deadlock.

The bridge detects and rejects this situation with an explanation.

If you need to reuse logic within the same script, call the Python function directly instead.

---

print() Goes to the ARC Console

Python's:

print()

does not write to a normal terminal.

sys.stdout is replaced with a stream that forwards the output to the Python skill's ARC Console.

If a native Python library bypasses sys.stdout and writes directly to the process's raw output handle, the skill redirects that data so it cannot corrupt the ARC communication bridge.

That output may appear as an error-colored line in the Console even when it is not an actual Python error.

---

Values Cross the Bridge by Value

Values passed between ARC and Python are serialized and transferred by value.

Supported types include:

• Numbers.
• Strings.
• Booleans.
• Lists.
• Dictionaries.

Images are transferred as JPEG data where appropriate.

Because Python runs in a separate CPython process, a Python variable cannot directly hold a live .NET object from ARC.

That separation is the tradeoff that allows the skill to use genuine CPython while retaining access to Python's complete package ecosystem.