triangula.task: Task Management

Tasks are single purpose activities that your robot may be doing. Examples include manual control, showing a system menu, showing an error message (hopefully not too frequently), executing a route plan etc. Basically anything where you’re in an event loop, reading sensor data and other inputs, and acting on it to move or otherwise control the robot.

Because this is where a lot of the fun happens, we want to be able to create new tasks easily, and add them into Triangula’s menu system, select them with the controller, exit them cleanly etc. This package handles all that kind of stuff.

The core concept is that of a triangula.task.Task - this is a super-class which you extend, implementing the init_task and poll_task functions. The triangula.task.TaskManager is responsible for calling the appropriate functions in your task, to which it passes populated instances of triangula.task.TaskContext. This TaskContext contains all the resources you might need in your task, such as an object to manage the chassis, one that can communicate with the sensors, a reference to the joystick, a convenience function to help determine which buttons have been pressed, basically anything your task will need to interact with the robot. The init_task is called exactly once, and then poll_task is called as often as possible (use the triangula.util.IntervalCheck class to cope with this properly). The TaskManager will exit back to whatever task it was started with if the SELECT button is pressed on the controller, but your task can also explicitly yield control to another task by returning that new task from the poll_task function (if nothing is returned your current task continues and will be polled again next time around). So, for example, you might make one task which allows you to enter a set of waypoints with the controller, then yield from that task to one that can drive the robot through those waypoints - doing this allows you to uncouple the route planning from the autopilot, so you can use both in other overall tasks. The triangula.tasks.main_menu.MenuTask is an example of this, it shows a menu of other tasks and yields to whichever task is currently selected when the user hits the CROSS button on the controller.

class triangula.task.ClearStateTask(following_task)[source]

Task which clears the state, turns the lights off and stops the motors, then immediately passes control to another task.

__init__(following_task)[source]

Create a new clear state task, this will effectively reset the robot’s peripherals and pass control to the next task. Use this when switching to ensure we’re not leaving the wheels running etc.

Parameters:following_task – Another triangula.task.Task which is immediately returned from the first poll operation.
Returns:
class triangula.task.ErrorTask(exception)[source]

Task used to display an error message

__init__(exception)[source]

Create a new error display task

Parameters:exception – An exception which caused this display to be shown
class triangula.task.ExitTask[source]

Special case Task, used to indicate that the current level of the task manager has completed and should take no further actions.

__init__()[source]

No argument constructor

class triangula.task.PauseTask(pause_time, following_task=None, led_hue=None)[source]

Task which will pause for at least the specified number of seconds, then yield to the specified task. If no task is specified an ExitTask is used.

__init__(pause_time, following_task=None, led_hue=None)[source]

Constructor

Parameters:
  • pause_time – This task should wait for at least this number of seconds before yielding.
  • following_task – A task to which this will yield, if this is None an instance of ExitTask will be used.
  • led_hue – Optional, if specified must be an integer between 0 and 255 and requests that all LEDs on the robot are set to the specified hue value.
class triangula.task.Task(task_name='New Task', requires_compass=False)[source]

Base class for tasks. Tasks are single-minded activities which are run, one at a time, on Triangula’s processor. The service script is responsible for polling the active task, providing it with an appropriate set of objects and properties such that it can interact with its environment.

__init__(task_name='New Task', requires_compass=False)[source]

Create a new task with the specified name

Parameters:
  • task_name – Name for this task, used in debug mostly. Defaults to ‘New Task’
  • requires_compass – Set to True to require that the task is provided with the current compass bearing when polled. This defaults to False because I2C transactions are expensive and we don’t want to make more of them than we have to.
init_task(context)[source]

Called exactly once, the first time a new task is activated. Use this to set up any properties which weren’t available during construction.

Parameters:context – An instance of triangula.task.TaskContext containing objects and properties which allow the task to comprehend and act on its environment.
poll_task(context, tick)[source]

Polled to perform the task’s action, you shouldn’t hang around too long in this method but there’s no explicit requirement for timely processing.

Parameters:
  • context – An instance of triangula.task.TaskContext containing objects and properties which allow the task to comprehend and act on its environment.
  • tick (int) – A counter, incremented each time poll is called.
Returns:

Either None, to continue this task, or a subclass of triangula.task.Task to switch to that task.
class triangula.task.TaskContext(arduino, lcd, bearing, imu_data, chassis, joystick, buttons_pressed)[source]

Contains the resources a task might need to perform its function

Variables:timestamp – The time, in seconds since the epoch, that this context was created. In effect this is also the task creation time as they’re created at the same time.
__init__(arduino, lcd, bearing, imu_data, chassis, joystick, buttons_pressed)[source]

Create a new task context

Parameters:
  • arduino – Instance of triangula.arduino.Arduino that can be used to manipulate the motors and lights, and which can poll the encoders attached to the motors.
  • lcd – Instance of triangula.lcd.LCD that can be used to display messages.
  • bearing – If the task has indicated that a bearing is required, this is float value from the compass on the IMU.
  • imu_data – If the task has indicated that a bearing is required, contains the entire IMU data block.
  • chassis – An instance of triangula.chassis.HoloChassis defining the motion dynamics for the robot.
  • joystick – An instance of triangula.input.SixAxis which can be used to get the joystick axes.
  • buttons_pressed – A bitfield where bits are set to 1 if the corresponding SixAxis button was pressed since the start of the previous task poll. Use this in preference to handler registration as it simplifies threading and cleanup
button_pressed(button_code)[source]

Helper method, equivalent to ‘self.buttons_pressed & 1 << button_code

Parameters:button_code – A button index from triangula.input.SixAxis i.e. SixAxis.BUTTON_SQUARE
Returns:0 if the button wasn’t pressed at the time the context was created, non-zero otherwise
class triangula.task.TaskManager(arduino, lcd, chassis, joystick)[source]

Manages the task loop

__init__(arduino, lcd, chassis, joystick)[source]
run(initial_task)[source]

Start the task loop. Handles task switching and initialisation as well as any exceptions thrown within tasks.

Parameters:initial_task – An instance of triangula.task.Task to use as the first task. Typically this is a menu or startup task of some kind.