Tasks

You are reading our Automation1 API documentation for the Python™ programming language.

In the Python API, Tasks lets you interact with and manage the Automation1 controller tasks.

The Basics

The Automation1 controller has one or more tasks that execute AeroScript programs and AeroScript commands on the controller. Each task has a task name and a task index.

Task indices start at 1. Task index 0 is reserved and cannot be used.

How to Use

In the Python API, Tasks is part of the Controller.runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with tasks. For more information about this property, see the Controller page.

To work with tasks in the Python API, use the Controller.runtime.tasks property and index the task that you want to work with. You can specify a task by task name or task index. Refer to the example that follows.

Copy

controller.runtime.tasks["Task 1"]
controller.runtime.tasks[1]

You can get the status of a task to see if the task is running an AeroScript program or if there is an error on the task. Refer to the example that follows.

Copy

controller_task_status = controller.runtime.tasks[task].status

Each time that you access the status property, you get a new status from the controller. For best results, access the status property one time only to get the most current status. Then use the returned ControllerTaskStatus object until you need to get the most current status of the controller again. If you do not do this and try to access the status property too many times, bugs known as race conditions can occur. These bugs occur when the status of the controller changes between multiple accesses of the property.

Manage AeroScript Programs

You can use tasks in the Python API to run AeroScript programs on controller tasks. This is one of two ways to command your Automation1 controller, with the other being Commands. Use the program property on a task to manage AeroScript programs on the controller task. Refer to the example that follows.

Copy

controller.runtime.tasks[task].program.run(controller_file_name)

The ControllerTask.program.run method starts the execution of the AeroScript program, but it does not wait for the program to complete. The specified controller file can be either an AeroScript source file (.ascript) or a compiled AeroScript file (.a1exe). If the controller file is an AeroScript source file, then the file will compile before it executes.

To determine if an AeroScript program is still running, get the status of the task. Then examine the task_state property, which returns the TaskState enum. The values of this enum will give you information about your program:

The TaskState.ProgramRunning enum value tells you if an AeroScript program is currently running on that task.
The TaskState.ProgramComplete enum value tells you if an AeroScript program completed successfully on that task.
The TaskState.Error enum value tells you if an AeroScript program failed with an error, which you can examine with the error property. Use the error_message property to get the string message of the error. Refer to the example that follows.

Copy

task_state = controller.runtime.tasks[task_name].status.task_state
task_error = controller.runtime.tasks[task_name].error

To stop an AeroScript program that is running, use the ControllerTask.program.stop method. Refer to the example that follows.

Copy

controller.runtime.tasks[task_name].program.stop()

Handle AeroScript Callbacks

AeroScript programs that run on a controller task can use the Callback() AeroScript function to send information to or pass execution to a Python custom application. When the Callback() function is executed from AeroScript, program execution on that task waits for any registered Python callback handler to execute. After the Python callback handler completes execution, the AeroScript program will continue.

Each callback is identified by a unique identifier, which is a callback ID. This ID is used when you register for the callback and when you execute the Callback() AeroScript function. You can give these handlers data from AeroScript and return data back to AeroScript. To learn more, see the Callback Functions page.

Inputs into a Python callback handler and outputs out of a Python callback handler can be AeroScript integers, AeroScript reals, and AeroScript strings. AeroScript integers are 64-bit. They are represented in Python by the int data type. AeroScript reals are double-precision floating-point numbers. They are represented in Python by the float data type.

You can use the callback property to register for the Callback() AeroScript function. When you register a handler for the Callback() function, you must specify a function that is invoked when the callback function is executed. The Callback() function requires values to be returned to AeroScript. Thus, your delegate will also return a value. If you do not want to return one or more values, return None.

If an error or exception occurs inside the Python callback handler, it will cause a task error to occur on the AeroScript program that raised the callback.

Example Code

Copy

import automation1 as a1

def my_callback(args: a1.ControllerTaskCallbackArguments):
    print(f"Integers ({len(args.aeroscript_integer_inputs)}):")
    for integer in args.aeroscript_integer_inputs:
        print(integer)

    print(f'Reals ({len(args.aeroscript_real_inputs)}):')
    for real in args.aeroscript_real_inputs:
        print(real)

    print(f'Strings ({len(args.aeroscript_string_inputs)}):')
    for string in args.aeroscript_string_inputs:
        print(string)

    return a1.ControllerTaskCallbackReturn(
        [1, 2, 3],
        None,
        ["Hello", "from", "python", "!"]
    )
controller = a1.Controller.connect()
controller.start()

controller.runtime.tasks[1].callback.register(1, my_callback)

# Do something else here, such as sleep or a long-running operation. The callback will be handled on a background thread.

controller.disconnect()

Task Variables

In the Python API, Task Variables let you get and set task variables on a task on an Automation1 controller. You can use task variables to share information between iterations of a program running on the same task.

IMPORTANT: Refer to Task Variables to learn how to use Task variables in the Python API.

Thread Safety

The threading library is the only multithreading library that is officially supported by the Automation1 Python API.

All the methods and properties that operate under the Controller.runtime.tasks property are thread safe. You can call them from two or more threads without interference.

The Controller.runtime.tasks property is a collection of controller tasks that can be iterated over.

WARNING: While you can call the iter function on the Controller.runtime.tasks property, it is not recommended. If you do this, the iter function will return an iterator object that is not thread safe.

The Python API is thread safe. But the controller might not be able to handle all the task operations that you do on separate threads. A single controller task can run only one AeroScript program at a time. You must synchronize or coordinate your process to prevent controller errors from occurring.

For Example

You can make a single Python thread responsible for a single controller task.

Full Reference

For more information about the properties and methods that are available for Tasks, refer to the lists that follow.

Controller.runtime.tasks Properties

Controller.runtime.tasks[].debug Methods

Controller.runtime.tasks[].program Methods

Controller.runtime.tasks[].motion Methods

ControllerTaskStatus Properties