Custom Events

Advanced Topic Skip if you’re new, explore when you’re ready.

Big idea

Each custom event type has a callback when its signal changes with the data type of the kind of event.

Each custom event type has its own unique callback for when its signal changes, with the signal parameter matching its underlying data type. The callbacks below are only called when the signal changes, unlike the effector signal on loop callback, which calls every loop tick. Initialization of pins is placed in the callback or near it for formatting reasons for the examples in this documentation. Better practice would be to move the pinMode initialization to the onThisControllerStarted callback rather than every callback trigger.

onCurvedCustomEventMovementChanged

BottangoArduinoCallbacks.cpp

void onCurvedCustomEventMovementChanged(AbstractEffector *effector, float newMovement)
{
    // example, fade an led based on the new movement value
    char effectorIdentifier[9];
    effector->getIdentifier(effectorIdentifier, 9);

    if (strcmp(effectorIdentifier, "myLight") == 0)
    {
        pinMode(5, OUTPUT);
        int brightness = 255 * newMovement;
        analogWrite(5, brightness);
    }
}

This callback is called by a curved custom event any time the movement value is changed during a curved movement. (Movement is a normalized float between 0.0 - 1.0)

The example here shows fading an LED on pin 5 based on the new movement value when an effector with the identifier “myLight” triggers the callback.

onOnOffCustomEventOnOffChanged

BottangoArduinoCallbacks.cpp

void onOnOffCustomEventOnOffChanged(AbstractEffector *effector, bool on)
{
    // example, turn on built-in LED based on the on off value
    char effectorIdentifier[9];
    effector->getIdentifier(effectorIdentifier, 9);

    if (strcmp(effectorIdentifier, "myLight") == 0)
    {
        pinMode(LED_BUILTIN, OUTPUT);
        digitalWrite(LED_BUILTIN, on ? HIGH : LOW);
    }
}

This callback is called by an on/off custom event any time the on/off value is changed.

The example here shows turning on or off the built-in LED based on the on off value, when an effector with the identifier “myLight” triggers the callback.

onTriggerCustomEventTriggered

BottangoArduinoCallbacks.cpp

void onTriggerCustomEventTriggered(AbstractEffector *effector)
{
    // example, set led to a random brightness each trigger
    char effectorIdentifier[9];
    effector->getIdentifier(effectorIdentifier, 9);

    if (strcmp(effectorIdentifier, "myLight") == 0)
    {
        pinMode(5, OUTPUT);
        int brightness = random(0, 256);
        analogWrite(5, brightness);
    }
}

This callback is called by a trigger custom event any time the event is triggered.

The example here shows setting an LED on pin 5 to a random brightness, when an effector with the identifier “myLight” triggers the callback.

onColorCustomEventColorChanged

BottangoArduinoCallbacks.cpp

void onColorCustomEventColorChanged(AbstractEffector *effector, byte newRed, byte newGreen, byte newBlue)
{
    // example, set RGB LED on pins 3, 5, and 6 to given red, green, and blue colors (represented as a byte between 0 and 255)
    char effectorIdentifier[9];
    effector->getIdentifier(effectorIdentifier, 9);

    if (strcmp(effectorIdentifier, "myLight") == 0)
    {
        pinMode(3, OUTPUT);
        pinMode(5, OUTPUT);
        pinMode(6, OUTPUT);

        analogWrite(3, newRed);
        analogWrite(5, newGreen);
        analogWrite(6, newBlue);
    }
}

This callback is called by a color custom event any time the target color changes.

The example here shows setting an RGB LED on pins 3, 5, and 6 to given red, green, and blue colors (represented as a byte between 0 and 255), when an effector with the identifier “myLight” triggers the callback. See this page for more detail on using addressable LEDs like a neopixel.