Full Reference¶

Props File¶

About Props File¶

Props can be provided in three ways:

Using the cloud service UI: In this case, you don’t need to read this section because the user interface is self-explaining. The file will be generated from your settings, and will be passed to the appropriate services transparently.
As a static YAML or JSON file: This is the recommended way if you’re not using the cloud service. In this method, a file named props.yaml or props.json is used to specify project props. In both cases, a props object is described. The schema for the props object is specified in the following lines. YAML is generally considered better than JSON for the files that are to be manually maintained.

3. As a python Dict object: This method is more flexible, as the dict is dynamically generated. However, you probably shouldn’t use it as it makes the project more complicated. Also, this variant can’t be used with bundler.

Specifications¶

Top Level Keys¶

Props file contains the following top level keys and values:

name: Name of the project
author: Author of the project (optional)
pip_requirements: PyPI dependencies (required if using bundler)
sim: Whether or not this is a simulation (default: false)
hardware: Hardware of the robot. See the section below.
ros1_port: ROS 1 master port (required if robot uses ROS 1 driver)
body_size: Longest dimention of the robot in meters (default: 0.5)

Hardware Definitions¶

Hardware props go under hardware key of the props file. Each set of hardware (e.g. wheels, camera, lidar) is denoted by a unique key and a value object. The latter defines properties of robot hardware, and is passed to the corresponding hardware module. Therefore, the schema of value object depends on the type of hardware that is to be defined. In fact, the only key that is fixed in the value object is type itself, which is used to determine the parser class of the hardware part.

To understand the schema for each type of hardware, see Hardware Modules documentation. TODO: add hyperlink.

Example props file

name: An Example Robot Program
pip_requirements:
    - numpy
hardware:
    camera-1:
        type: camera
        variant: rgb
        location: 10, 0, 5 cm
        orientation: front-facing
        fov: 60 deg
        connection: usb

    wheels-1:
        type: wheels
        steering: ackermann
        locations:
            front-axis: 3, 0, 0 cm
            back-axis: 14, 0, 0 cm
        actuated-wheels: back
        max-torque: 10 N.cm
        max-steering: 20 deg
        driver: dca-440

Robot object¶

robot.navigation¶

This object can be used to map the environment and move to a target position.

from_props(props, robot)¶

This object becomes available automaically if all the following conditions are met:

At least one hardware with type=wheels is defined in the props file.
At least one hardware with type=imu is defined in the props file.
At least one hardware with type=lidar is defined in the props file.

Supporting more hardware systems is on our todo list.

class Navigation(robot)¶

cancel_task()¶: Cancels the pending task.

explore(method='random_walk', timeout=None)¶

Explores the room and generates a map using SLAM.

Parameters

method – Exploration method: ‘random_walk’ (default) | ‘random_walk_open_loop’ (Open-loop i.e. may hit obstacles)
timeout – Duration of exploration in seconds.

get_heading()¶

Returns robot heading in radians from -pi to pi.

In SLAM mode with no existing map, the starting heading is zero.

get_position()¶

Returns robot position as a tuple of (x, y, z) in meters from the origin.

In SLAM mode with no existing map, the starting point is the origin.

is_task_complete()¶: Returns whether or not the last task is finished.

move_to(target_x, target_y, target_heading=None, wait_to_finish=True)¶

Moves the robot to the target position.

Parameters

target_x – X-location of the target. If the robot is performing in SLAM mode, origin will be the starting point and x will correspond to right direction at starting moment.
target_y – y-location of the target. If the robot is performing in SLAM mode, origin will be the starting point and y will correspond to forward direction at starting moment.
target_heading – Target heading in radians. Optional.
wait_to_finish – Defaults to False. If set to True, the method will block the execution of the next lines of code until the movement is completed.

stop()¶: Cancels the pending task and stops immediately.

robot.wheels¶

This object controls the wheels in a low-level manner. See robot.navigation for a high-level alternative.

from_props(props, robot)¶

Global props read by robot.wheels¶
Key	Type	Default	Description
sim	boolean	false	If set to true, the simulation driver will be used.

Hardware props read by robot.wheels¶
Key	Type	Default	Description
driver	‘ros2’ \| ‘ros1’ \| ‘dummy’ \| None	None	Driver to use for the wheels. Required if sim != True.
steering	‘ackermann’ \| ‘diff’	required	The steering method of the wheels.

class Wheels(robot)¶

set_rotation_rate(target_rotation_rate)¶

Sets robot heading change rate to a desired value.

Parameters: target_rotation_rate – Desired angular velocity in rad/s. Direction of rotation is interpreted by the right-hand rule around upward z axis.

set_speed(target_speed)¶

Sets robot linear speed to a desired value.

Parameters: target_speed – Desired linear speed in m/s. Use negative numbers for backward motion.

stop()¶: Stops the wheels.