API Reference

API Reference

All of the referenced items will be defined when the header "hax.h" is included.

#include <hax.h>

Robot Control Mode

During various phases of competition the "user" processor (on which all of your code and HAX’s code runs) has varying degrees of control and access to data provided by the "master" processor (programmed with unknown code by vex). The following provides a way to get information about this.

ctrl_mode_t

A type which holds the current control mode of the robot. Possible modes:

MODE_TELOP

Can be controlled by someone holding an OI (operator interface).

MODE_AUTON

No access to OI inputs, can set motor outputs.

MODE_DISABLE

Unable to set motor values or read from the OI.

ctrl_mode_t ctrl_mode_get(void)

returns the current operating mode of the robot.

Required arch specific upkeep

The code for each architecture provides a few functions which must be called by the program code at several points to keep the robot moving and operating properly.

void arch_init_1(void)

call prior to user initialization

void arch_init_2(void)

call following user initialization

void arch_loop_1(void)

call on entry to the slow loop

void arch_loop_2(void)

call on exit from the slow loop

bool do_slow_loop(void)

indicates whether the slow loop retinues should be executed.

Indexing

Give the IX_* macros the numeric label of the thing (pin or control group) you wish to refer to and they return a value of type index_t which can be passed to numerous functions to examine and modify the robot’s state.

For example, digital_get(IX_INTERRUPT(1)) would return the current digital value of Pin 1 in the Interrupt grouping of pins on the PIC arch and (for compatibility reasons) Pin 1 in the "digital" grouping of the Cortex arch (all pins in the "digital" grouping are interrupts).

As much as possible, we attempt to have the parameters to these macros match the labels printed on the physical hardware. This means many things are one (1) indexed rather than zero (0) indexed.

index_t

type returned by the IX_ family of macros

IX_ANALOG(num)

use this for pins in the "analog" grouping on the micro-controller.

IX_DIGITAL(num)

for pins in the "digital" grouping on the micro-controller. Note that on the Pic arch these are the same as "analog" pins.

IX_INTERRUPT(num)

pins in the "interrupt(s)" grouping on the micro-controller. Note that on the Cortex arch these are the same as "digital" pins.

IX_OI_GROUP(oi, group)

labeled group (numbered things, such as sticks, rockers, and a collection of buttons) on the OI.

IX_OI_BUTTON(oi, group, dir)

a single button from oi groups that consist of more than one button Possible dirs vary depending on the particular oi and group, but will be one of the following: [horizontal]

OI_B_UP

"up" button pressed.

OI_B_DN

down

OI_B_LT

left

OI_B_RT

right

Additional OI Indexing defines.

To allow additional portability in indexing OI inputs, the following macros are defined.

Pass to oi_group_get

OI_JOY_L_X(oi)

left joystick x axis

OI_JOY_L_Y(oi)

left joystick y axis

OI_JOY_R_X(oi)

right joystick x axis

OI_JOY_R_Y(oi)

right joystick y axis

Pass to oi_rocker_get

OI_ROCKER_L(oi)

OI_ROCKER_R(oi)

.Pass to oi_button_get

OI_TRIGGER_L(oi, dir)

parameter dir takes a direction as described above. If one uses only OI_B_UP and OI_B_DOWN in the dir parameter, the code will be reasonably portable as both controllers have up and down buttons. Note however, that the Vex v.5 (PIC) OI will not register both the up and down presses at the same time, leading to possible incompatibilities.

OI_TRIGGER_R(oi, dir)

same as above but for the right trigger on the oi.

Operator Interface (OI) Access

Functions which allow the reading of OI values. The output of these functions (given the same input) will only change once per slow loop. This is because we only update ourselves with the values from the master processor after an SPI transfer (which occurs every slow loop).

int8_t oi_group_get(index_t group)

Analog values are normalized to fall between -127 and +127 and digital values are either zero or one. Return value is undefined for groups that consist of more than one button, use oi_button_get or oi_rocker_get instead. Expects an index generated by IX_OI_GROUP().

int8_t oi_rocker_get(index_t group)

State of the rocker trigger buttons, where no press is 0, a down press is -1, and an up press is +1. Expects an index generated by IX_OI_GROUP().

bool oi_button_get(index_t button)

State of a single button in a group that consists of multiple buttons. Expects an index generated by IX_OI_BUTTON().

Motors and Servos

Motor outputs are set by sending the value to the master processor over the SPI link. As such, it does not often make sense to update motor values more than once per slow loop.

void motor_set(index_t pin, int8_t val)

When controlling a motor an analog value of -127 is full-speed backwards and +127 is full-speed forwards. Servos treat +127 and -127 as their two furthest turned angles. Expects an index generated by IX_MOTOR().

Input and Output

Functions for accessing on chip resources. These are updated continuously (unlike the oi_ functions)

void digital_setup(index_t pin, bool output)

This function must be used to initialize any pin passed to digital_get() or digital_get(). Expects an index generated by IX_ANALOG(), IX_DIGITAL(), or IX_INTERRUPT().

void digital_set(index_t pin, bool output)

Pin must be initialized using digital_setup() as output prior to use. Expects an index generated by IX_ANALOG(), IX_DIGITAL(), or IX_INTERRUPT().

bool digital_get(index_t pin)

Pin must be initialized using digital_setup() as input prior to use. Expects an index generated by IX_ANALOG(), IX_DIGITAL(), or IX_INTERRUPT().

uint16_t analog_get(index_t pin)

Always returns an analog value scaled to have 16 bits of precision, regardless of the true precision of the underlying hardware’s ADC(s). Expects an index generated by IX_ANALOG().

Interrupts

typedef void (*isr_t)(bool pin_state);

The type which the callback function must match.

void interrupt_setup(index_t pin, isr_t isr);

Associates a interrupt callback (isr) with a particular external pin (pin). For pin, IX_INTERRUPT(label) and IX_DIGITAL(label) are the recommended index generators. For protability, IX_INTERRUPT is a must. A call to interrupt_setup does not enable the corresponding interrupt, interrupt_set must also be called.

void interrupt_set(index_t pin, bool enable); Allows the interupt attached to pin pin to be enabled and disabled.