Student API

The student API is the set of all functions that the students have available to them to communicate with the robot. This page has two overall sections. The first section is intended as documentation for the student API that can be used as reference for website updates, PiE Robot Simulator, and staff intending to learn how the PiE Robot API works. The second section is intended as a deeper dive into the inner workings of the API for Runtime developers to read.

PiE Student API Documentation

Robot Class

Robot.get_value(device_id, param)

The get_value function returns the current value of the specified param of the device with the specified device_id (which is of the form <device_type>_<device_uuid>).

• device_id string - the ID that specifies which PiE device will be read
• param string - identifies which parameter on the specified PiE device will be read. Possible param values depend on the specified device. Find a list of params for each device on the lowcar devices page

This function is useful for checking the state of certain parts of your robot while it is driving. For example, calling this function with a Limit Switch Sensor's ID and “switch0” would get the value True if the first Limit Switch was pressed down and False if it was not. Possible devices include:

• LimitSwitch
• LineFollower
• ServoControl
• PolarBear
• KoalaBear
• BatteryBuzzer

Robot.set_value(device_id, param, value)

The set_value function sets the specified value of the specified param of the device with the specified device_id (which is of the form <device_type>_<device_uuid>).

• device_id string - the ID that specifies which PiE device will have its parameter set
• param string - identifies which parameter on the specified PiE device will be set to the provided value. Possible values depend on the specified device. Find a list of parameters that can be set for each device on the lowcar devices page.
• value <int, float> - a variety of inputs depending on the specified device and parameter which change the value of the parameter

This function is useful for changing the state of certain parts of your robot while it is driving. For example, calling this function with a KoalaBear's ID, the parameter “velocity_a”, and the value -1.0 would result in the motor attached to the KoalaBear to spin backwards at full power. Possible devices include:

• ServoControl
• KoalaBear

Robot.run(function_name, args...)

Executes another function with the list of args passed into the function as inputs. The function specified by function_name is run at the same time as the main loop.

• function_name: the name of a function in the student code which will be run simultaneously with the main loop
• args...: this is a list of zero or more inputs, which will be passed to the function_name specified previously as arguments (inputs)

Any function can be run simultaneously with the main loop with this function. Beware of putting this function in the main loop code, as this will cause the function to be run many, many, many times simultaneously and break the onboard computer. Runtime has some safeguards in place to prevent this from happening and will shut down the student code if it tries to do this.

Robot.is_running(function_name)

Returns a boolean value (True or False) indicating whether the specified function is still running.

• function_name: the name of a function defined by the student that may or may not have been run using Robot.run

Robot.sleep(seconds)

Pauses the execution of the current function for the specified number of seconds.

• seconds: the number of seconds to pause the execution of the current function for. Changing modes in the middle of this function will cause all execution to stop, as it should.

Gamepad Class

Gamepad.get_value(name_of_input)

Returns the state of a button or joystick of a connected gamepad.

• name_of_input string: identifies which button or joystick value will be by returned

This function is useful for checking the state of buttons or joysticks of your gamepad or controller. For example, calling this function with ”button_a” would result in True if the A button is pressed down and False if it is not.

This function is essential for controlling your robot with the gamepad. The possible values for name_of_input are:

• "joystick_left_x"
• "joystick_left_y"
• "joystick_right_x"
• "joystick_right_y"
• "button_a"
• "button_b"
• "button_x"
• "button_y"
• "l_bumper"
• "r_bumper"
• "l_trigger"
• "r_trigger"
• "button_back"
• "button_start"
• "l_stick"
• "r_stick"
• "dpad_up"
• "dpad_down"
• "dpad_left"
• "dpad_right"
• "button_xbox"

Users should be careful to distinguish between values such as “l_stick” and values such as “joystick_left_x”. “l_stick” returns whether the joystick has been depressed like a button. “joystick_left_x” returns how far the joystick is moved on the x-axis.

When a button is passed in, this function returns a boolean value: True if the button is pressed, and False if the button is not pressed. When a joystick is passed in, this function returns a floating-point (decimal) value between -1.0 and 1.0, which correspond to the extremes of movement for the given joystick.

Keyboard Class

Keyboard.get_value(name_of_key)

Returns the state of the specified key on the keyboard.

• name_of_key string: identifies the key whose state will be returned by this function

This function is essential to controlling your robot with the keyboard. Possible values for name_of_key are:

• The letters on the keyboard, lowercase and no spaces "a"-"z"
• The numbers on the keyboard, no spaces "0"-"9"
• The punctuation keys ",", ".", "/", ";", "'", "[", "]"
• The four arrow keys "left_arrow", "right_arrow", "up_arrow", "down_arrow"

The function will return True if the button is pressed, and False if the button is not pressed.

Student API Explanation for Runtime Devs

Cython

The student API is written entirely in Cython, which is a static compiler from Python to C. It provides static typing and lets you easily call C functions within Python. You can learn more about Cython at our wiki page https://github.com/pioneers/runtime/wiki/Cython.

In Cython, the .pxd files act as header files while .pyx files act as source files. In runtime.pxd, you will see many extern declarations to C functions in Runtime. In studentapi.pyx, each API function converts the Python arguments into C arguments and calls the corresponding shm_wrapper C functions to access shared memory. We will now discuss each API function in more detail.

API

print

We actually modify the default print function by changing builtins.print so that any print statement used by the student code is instead redirected to log_printf in the logger to be sent over the network. This also includes changing the default sys.stderr file stream to have the exception tracebacks be properly formatted when printed.

Robot.get_value

This function will retrieve a device parameter for a specific device id from shared memory. This uses the device_read_uid function from shm_wrapper. The device id input is of the form {type}_{uid}. The proper exceptions are thrown for invalid parameters.

Robot.set_value

This function will set a device parameter for a specific device id in shared memory. This uses the device_write_uid function from shm_wrapper. The device id input is of the form {type}_{uid}. The proper exceptions are thrown for invalid parameters.

Robot.run

This is a purely Python function that will start the given function in a separate thread using the threading module. We have to create a new Thread subclass called ThreadWrapper to have us that will properly print out the exception traceback. It will also set a threading.Event to ensure that exceptions in this action thread are correctly raised to the executor to stop running the mode.

Robot.is_running

This just returns whether the given function is being run asynchronously in another thread.

Robot.log

This allows students to log values other than device parameters on the Dawn dashboard. This uses the log_data_write function from shm_wrapper. It will also raise an exception if the type of the value is not an int, float, or bool.

Robot.sleep

We had some issues figuring out how to cancel running the student code when it is busy doing other calculations or when it is sleeping. To make this possible, all sleeps in the student code should use Robot.sleep instead of time.sleep. This function is different in that if the sleep is called in the main thread, it will use the threading.Event.wait function, which is cancellable by the executor by calling threading.Event.set. If this is called in an action thread, then it uses the normal time.sleep as these threads are killed immediately when their parent process is killed.

The reason we needed to use the threading.Event is that the Python code is being executed in the main thread of the executor process along with our C code. So if we sleep in the main thread, none of our C error-checking/timeout code will run, which is not good as it is very unsafe if we can't cancel the robot at any point in time.

Gamepad.get_value

This function will receive a gamepad value from shared memory, which is populated by the net_handler. This uses the input_read function in shm_wrapper and will throw an exception if the parameter is invalid.

Keyboard.get_value

This function will retrieve data about the keyboard state from shared memory, which is populated by net_handler. It uses the input_read function in shm_wrapper and will throw an exception if the parameter is invalid.

Device Subscriptions

To reduce the amount of data we communicate over Serial, we have to specify to the Lowcar devices which parameters we want to receive. To know which parameters the students use, we parse the student code using get_all_params to find all devices and their corresponding parameters in any Robot.get_value or Robot.set_value functions using regex. Then we request the subscriptions in executor by calling make_device_subs, which then calls place_sub_requests from shm_wrapper. One significant drawback that still exists with this is that if the devices or parameters are local variables instead of being global variables or literals, then the parsing will break which might cause the student code to give incorrect device values. This is an ongoing bug, and thus the students need to be warned to not do this.