Effector Lifecycle

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

Big idea

You can add custom logic to effector registration (set live), deregistration (set not live), and when the desired signal on the effector changes.

Motors and effectors registered with a hardware driver have the following lifecycle callbacks that allow you to input your own code. 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.

onEffectorRegistered

BottangoArduinoCallbacks.cpp

void onEffectorRegistered(AbstractEffector *effector)
{
  char effectorIdentifier[9];
  effector->getIdentifier(effectorIdentifier, 9);

  if (strcmp(effectorIdentifier, "1") == 0)
  {
    // Your logic here.
    // In this example, we turn on the built-in LED when the effector with the identifier "1" is registered
    pinMode(LED_BUILTIN, OUTPUT);
    digitalWrite(LED_BUILTIN, HIGH);
  }
}

This callback is called when an effector is registered. An effector is registered when it is set “live” in the Bottango desktop app, or as part of startup when running from exported animations.

The example here shows turning on the built-in LED when an effector with the identifier “1” is registered.

onEffectorDeregistered

BottangoArduinoCallbacks.cpp

void onEffectorDeregistered(AbstractEffector *effector)
{
  char effectorIdentifier[9];
  effector->getIdentifier(effectorIdentifier, 9);

  if (strcmp(effectorIdentifier, "1") == 0)
  {
    // Your logic here.
    // In this example, we turn off the built-in LED when the effector with the identifier "1" is deregistered
    digitalWrite(LED_BUILTIN, LOW);
  }
}

This callback is called when an effector is deregistered. An effector is deregistered when it is set “live” in the Bottango desktop app. Deregistration does not happen normally when running off of exported code, though you could modify that behavior.

The example here shows turning off the built-in LED when an effector with the identifier “1” is deregistered.

effectorSignalOnLoop

BottangoArduinoCallbacks.cpp

void effectorSignalOnLoop(AbstractEffector *effector, int signal, bool didChange)
{
    // example, set built-in LED for effector with identifier "1" based on if signal is greater than 1500

    char effectorIdentifier[9];
    effector->getIdentifier(effectorIdentifier, 9);

   if (didChange && strcmp(effectorIdentifier, "1") == 0)
    {
        pinMode(LED_BUILTIN, OUTPUT);
        if (signal > 1500)
        {
            digitalWrite(LED_BUILTIN, HIGH);
        }
        else
        {
            digitalWrite(LED_BUILTIN, LOW);
        }
    }
}

This callback is called with the current signal for the effector each loop tick. It also passes a bool “didChange” which is true if the signal this call is different than the last time this callback was triggered.

The example here shows toggling the built-in LED if signal is > 1500 on an effector with the identifier “1.”