Actuators

Basics

An Actuator is a controller object that can perform a function on something in the physical world. Examples include motors, heaters, servos, and others. Actuators primarily are concerned with engaging a device at some driving intensity, direction, and optionally for a set time, a lot of which is typically managed by the tracking Scheduler or one of its Drivers.

Actuators come in a variety of types: relay-based binary (on/off, e.g. panel heater), relay-based motor (on/off, e.g. linear actuator), and PWM-based analog (pulse width modulation, e.g. servos).

Supported Actuators

• Positional servo: an angle-limited positional servo that can move along an axis, uses absolute driving values.
• Linear actuator: an extendable shaft that can lift heavy panels to face the sun, uses relative driving values.
• Continuous servo: an angle-unlimited continuous servo that can move along an axis, uses relative driving values.
• Panel brake: a brake that can be applied onto large panels so that driving actuators can disable after alignment.
• Panel cover: a type of cover that can be moved into place after the panel returns to its home position.
• Panel heater: a heater that can keep solar panels free of ice and snow.
• Panel sprayer/wiper: a sprayer/wiper that can engage on schedule for a set time to clean the panels automatically.

Activation Handles

To enable an actuator, you must first grab a proper ActivationHandle object, which defines that particular activation's setup parameters, and can be thought of as a hallway pass - don't lose it. An ActuatorAttachment object is helpful in this case since it manages just such an object, but regardless, a call is expected to setupActivation() prior to enabling that activation with enableActivation(). A call to disableActivation() can also be used to deactivate that activation, or when the handle is deconstructed.

Any Actuator object is free to choose how to respond to activation handles, as there can be numerous different objects that are requesting activation at once, possibly at different driving intensities/directions. Actuators use their enableMode setting to determine how to resolve these multiple-handle request situations, with the default option being to run all activations in parallel at the highest driving intensity value. Other options include being able to serialize activation, and responding one-by-one in different orderings.

Actuator objects typically will respond to activations on their next update cycle, and will update the activation handle as it runs. Using activations this way instead of directly providing access to the actuator's direct pin outputs allows activations to stack in different ways depending on usage dynamic. Additionally, actuators may have to wait for a chance to enable if there are many devices on a shared power line (e.g. a bunch of large motors all engaging at once is going to give you a bad electrics day), or based on other system dynamics.