# Events

Events are predefined robot functions that you can embed conditional logic in. When an event occurs, the conditional logic is called and then the program returns to the main loop where it left off. The event will be called every time it occurs by default, unless you customize it. For example, "on collision, change LED lights to red and play the Collision sound," then return to the main loop.

Note: In the basic examples below the logic in the main loop is nested in a while 1 loop. This ensures there is logic to "return" to after an event is called. If there was longer time delayed logic in the main loop, you would not require the while 1 loop.

### On Collision

onCollisionEvent executes conditional logic when the robot collides with an object.

void handleCollision()
{
// code to execute if a collision is detected
}
onCollisionEvent = &handleCollision;

For example, below is a basic pong program where your robot bounces off walls in perpetuity. Place the robot on the floor between two parallel walls and run the below program with the robot pointed perpendicularly at one wall. Start the program and the robot will roll forward until it collides with the first wall, then it will stop, turn red, and reverse direction by 180° and continue this cycle:

void handleCollision()
// on collision change LED's to red, stop and turn around
{
setRgbLed(255, 0, 0);
controlSystemTargetSpeed = 0;
delay(0.5);
controlSystemTargetYaw = (controlSystemTargetYaw + 180);
delay(0.5);
}
onCollisionEvent = &handleCollision;

void startProgram()
// when no collision, set LED's to white and roll forward
{
while (1)
{
setRgbLed(255, 255, 255);
controlSystemTargetSpeed = 60;
}
}

### Configure Collisions

configureCollisionDetection(mode, xt, xs, yt, ys, deadTime) customizes the onCollisionEvent. It is a predefined function that configures collision detection and can identify which direction a collision came from. If you don't invoke new parameters (such as in the above pong example) the defaults will be used configureCollisionDetection(1, 90.0, 130.0, 90.0, 130.0, 1.0)

Collisions are based on an impact threshold; if you exceed the threshold then your robot experienced a collision. Oval allows you to read and customize the collision values for a few use cases:

1. Determine which direction a collision came from to write conditional logic based on directional awareness. For example, you could write a program that only experiences collisions on the left side of the robot.
2. Increase or decrease the impact sensitivity thresholds. For example, if you run a program on a bumpy surface you might find the robot experiences false positive collisions. You could increase the threshold to ensure that only higher impact collisions (eg. with a wall) were counted.

Collision is calculated by the vector of the x-axis and y-axis Accelerometer, and ignores the z-axis. The speed is also be considered so that collisions can be determined along the full range of speed from 0-255.

mode turns collision detection on (1) or off (0) so that it can be active for a portion of a program.

xt is the threshold on the x-axis of the Acceleromoeter in G's that needs to be surpassed to be considered a collision, with a default of 90.0. Use 0.0 to disable the contribution from the x-axis.

xs is the threshold on the x-axis of the Locator Speed in meters per second that must be surpassed to be considered a collision, with a default of 130.0.

yt is the threshold on the y-axis of the Acceleromoeter in G's that needs to be surpassed to be considered a collision, with a default of 90.0. Use 0.0 to disable the contribution from the y-axis.

ys is the threshold on the y-axis of the Locator Speed in meters per second that must be surpassed to be considered a collision, with a default of 130.0.

deadTime is how long the robot should wait before another event meeting the collision parameters is counted as a collision in seconds, with a default of 1.0s.

Warning: Setting these values saves them globally, so if you try to run another program with an onCollisionEvent event it will inhereit your custom values. Make sure the set them back to the defaults after you complete your program to avoid confusion.

For example, to prevent quick collisions you can increase deadTime:

void handleCollision()
// on collision change LED's to red, stop and turn around
{
setRgbLed(255, 0, 0);
controlSystemTargetSpeed = 0;
delay(0.5);
controlSystemTargetYaw = (controlSystemTargetYaw + 180);
delay(0.5);
}
onCollisionEvent = &handleCollision;

void startProgram()
// when no collision, set LED's to white and roll forward
{
// increase the deadTime to 4s
configureCollisionDetection(1, 90.0, 130.0, 90.0, 130.0, 4.0);
while (1)
{
setRgbLed(255, 255, 255);
controlSystemTargetSpeed = 60;
}
}

### Last Collision Time

// type: float // access: read // range: any // units: seconds

lastCollisionTime gets the time of the last onCollisionEvent in seconds, based on the difference of currentRobotTime - lastCollisionTime.

### On Freefall

onFreeFallEvent executes conditional logic when gravity is the only force acting on the robot, such as when dropping or throwing it. Freefall is measured by an accelerometer reading of < 0.1 G for => 0.1 s, where 1G is resting. On earth, objects in Freefall accelerate downwards at 9.81 m/s². If you were in space, objects always appear to be in Freefall with a reading of 0G at rest because there is no gravity - they do not accelerate in any direction unless acted upon.

void handleFreeFall()
{
// code to execute if a freefall is detected
}
onFreeFallEvent = &handleFreeFall;

For example, to change the LED's to red on freefall for a short duration use:

void handleFreeFall()
{
setRgbLed (255, 0, 0);
delay(.5);
}
onFreeFallEvent = &handleFreeFall;

void startProgram()
{
while(1)
{
setRgbLed (255, 255, 255);
}
}

### Configure Freefall

freeFallMaxG customizes the onFreeFallEvent. It redefines maximum combined Acceleration in G's that is required to count as an onFreeFallEvent event, on a scale of 0-14G's with a default of 0.1G.

freeFallMinDuration also customizes the onFreeFallEvent. It redefines the duration parameter in seconds that is required to count as an onFreeFallEvent event, on a scale of 0-Ns with a default of 0.1s.

Warning: Setting these values saves them globally, so if you try to run another program with an onFreeFallEvent event it will inhereit your custom values. Make sure the set them back to the defaults after you complete your program to avoid confusion.

For example, to require a larger G force and longer freefall period use:

freeFallMaxG =.5;
freeFallMinDuration = 1;

void handleFreeFall()
{
setRgbLed (255, 0, 0);
delay(.5);
}
onFreeFallEvent = &handleFreeFall;

void startProgram()
{
while(1)
{
setRgbLed (255, 255, 255);
}
}

### On Land

onLandingEvent executes conditional logic when the robot lands after an onFreeFallEvent. You don't need to define an onFreeFallEvent event for the robot to experience an onLandingEvent, but the robot must meet the conditions for freefall before land.

void handleLanding()
{
// code to execute if a landing is detected
}
onLandingEvent = &handleLanding;

For example, to change the LED to green after landing use:

void handleLanding()
{
setRgbLed (0, 255, 0);
delay(.5);
}
onLandingEvent = &handleLanding;

void handleFreeFall()
{
setRgbLed (255, 0, 0);
delay(.5);
}
onFreeFallEvent = &handleFreeFall;

void startProgram()
{
while(1)
{
setRgbLed (255, 255, 255);
}
}

### Configure Landing

landingMinG customizes the onLandingEvent. It redefines the minimum force for onLandingEvent as measured by the z-axis of the Accelerometer on a scale of -8 to 8 G's with a default of 6G's.

Warning: Setting this value saves it globally, so if you try to run another program with an onLandingEvent event it will inhereit your custom value. Make sure the set it back to the default after you complete your program to avoid confusion.

For example, to reduce the force required down to 4G's use:

landingMinG = 4;

void handleFreeFall()
{
setRgbLed (255, 8, 28);
delay(.5);
}
onFreeFallEvent = &handleFreeFall;

void handleLanding()
{
controlSystemTargetSpeed = 40;
delay(5);
}
onLandingEvent = &handleLanding;

void startProgram()
{
while(1)
{
setRgbLed (255, 255, 255);
controlSystemTargetSpeed = 188;
}
}

### On Gyromax

onGyroMaxEvent executes conditional logic when the robot exceeds the bounds of measurable rotational velocity of -2,000° - 2,000° per second. This can be triggered by spinning the robot around like a top on a table really fast. You need to spin it around > 5.5 revolutions per second.

void handleGyroMax()
{
// code to execute if gyromax is detected
}
onGyroMaxEvent = &handleGyroMax;

For example, to play the boing sound and change the LED's to red when you reach gyromax, use:

void handleGyroMax()
{
playSound(0, 3);
setRgbLed (255, 0, 0);
delay(.5);
}
onGyroMaxEvent = &handleGyroMax;

void startProgram()
{
controlSystemIsOn = 0;
while(1)
{
setRgbLed (255, 255, 255);
}
}