Brake Module¶

Provides the BrakeModule class that controls an electromagnetic particle brake.

template<const uint8_t kPin, const bool kNormallyEngaged, const bool kStartEngaged = true> class BrakeModule : public Module¶

#include <brake_module.h>

Controls the electromagnetic brake by sending digital or analog Pulse-Width-Modulated (PWM) currents through the brake.

Template Parameters:

kPin – the digital output pin connected to the logic terminal of the managed brake’s FET-gated power relay.
kNormallyEngaged – determines whether the brake is engaged (active) or disengaged (inactive) when unpowered.
kStartEngaged – determines the initial state of the brake during class initialization.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kEngaged¶: The brake is engaged at maximum possible strength.

enumerator kDisengaged¶: The brake is disengaged.

enumerator kVariable¶: The brake is engaged at the specified non-maximal strength.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kToggleOn¶: Engages the brake at maximum strength.

enumerator kToggleOff¶: Disengages the brake.

enumerator kSetBrakingPower¶: Sets the brake to engage at the requested braking strength.

enumerator kSendPulse¶: Briefly engages the brake at maximum strength for the specified duration.

Public Functions

inline BrakeModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~BrakeModule() override = default¶

Private Functions

inline void EnableBrake()¶: Engages the brake at the maximum strength.

inline void DisableBrake()¶: Disengages the brake.

inline void SetBrakingPower()¶: Engages the brake at the specified strength level.

inline void SendPulse()¶: Engages the brake at maximum strength for the requested pulse_duration of microseconds and then disengages it.

Private Members

struct BrakeModule::CustomRuntimeParameters _custom_parameters¶

Private Static Attributes

static bool kEngage = kNormallyEngaged ? LOW : HIGH¶: Stores the digital signal that needs to be sent to the output pin to engage the brake at maximum strength.

static bool kDisengage = kNormallyEngaged ? HIGH : LOW¶: Stores the digital signal that needs to be sent to the output pin to disengage the brake.

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

uint8_t braking_strength = 128¶: Determines the strength of the brake in variable mode.

uint32_t pulse_duration = 1000000¶: The time, in microseconds, to engage the brake during pulses.

Encoder Module¶

Provides the EncoderModule class that monitors and records the data produced by a quadrature encoder.

Warning

This file is written in a way that is NOT compatible with any other library or class that uses AttachInterrupt(). Disable the ‘ENCODER_USE_INTERRUPTS’ macro defined at the top of the file to make this file compatible with other interrupt libraries.

Defines

ENCODER_USE_INTERRUPTS¶

template<const uint8_t kPinA, const uint8_t kPinB, const uint8_t kPinX, const bool kInvertDirection = false> class EncoderModule : public Module¶

#include <encoder_module.h>

Wraps an Encoder class instance and provides access to its pulse counter to monitor the direction and magnitude of the rotation measured by the managed quadrature encoder.

Note

By default, the clockwise (CW) movement of the encoder is measured as a negative displacement, while the counterclockwise (CCW) movement of the encoder is measured as a positive displacement.

Warning

Both Pin A and Pin B must be hardware interrupt pins to achieve the maximum encoder state readout resolution.

Template Parameters:

kPinA – the digital interrupt pin connected to the ‘A’ channel of the quadrature encoder.
kPinB – the digital interrupt pin connected to the ‘B’ channel of the quadrature encoder.
kPinX – the digital pin connected to the ‘X’ (index) channel of the quadrature encoder.
kInvertDirection – determines whether to invert the sign of the value returned by the encoder.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kRotatedCCW¶: The encoder was rotated in the counterclockwise (CCW) direction.

enumerator kRotatedCW¶: The encoder was rotated in the clockwise (CW) direction.

enumerator kPPR¶: Communicates the estimated Pulse-Per-Revolution (PPR) value of the encoder.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kCheckState¶: Determines the direction and magnitude of the encoder’s motion since the last check.

enumerator kReset¶: Resets the encoder’s pulse tracker to 0.

enumerator kGetPPR¶: Estimates the encoder’s Pulse-Per-Revolution (PPR) value.

Public Functions

inline EncoderModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶

Overwrites the module’s runtime parameters structure with the data received from the PC.

Derives positive and negative amortization caps from delta_threshold. Amortization permits the overflow accumulator to store pulses in the non-reported direction up to the threshold, suppressing small jitter (for example, a locked running wheel) so that opposing micro-motions cancel out instead of accumulating into a spurious directional event.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~EncoderModule() override = default¶

Private Functions

inline void ReadEncoder()¶: Reads the direction and magnitude of the encoder’s rotation since the previous check and sends it to the PC when the accumulated displacement exceeds the configured delta threshold.

inline void ResetEncoder()¶: Resets the encoder pulse counter back to 0.

inline void GetPPR()¶: Estimates the Pulse-Per-Revolution (PPR) value of the encoder by using the index pin to precisely measure the number of pulses emitted during a full (360-degree) encoder rotation.

Warning

Blocks the runtime in-place. The method spins waiting on the index pin and delays between rotations. Intended only for offline calibration, never during an active behavior session.

Private Members

struct EncoderModule::CustomRuntimeParameters _custom_parameters¶

Encoder _encoder = Encoder(kPinA, kPinB)¶: The encoder class that monitors the encoder’s rotation. Must be initialized statically; deferred initialization causes a runtime crash.

int32_t _overflow = 0¶: Accumulates insignificant encoder readouts to be reused during future encoder state evaluation calls.

int32_t _positive_amortization = 0¶: Determines the maximum encoder displacement (rotation) in the counterclockwise (CCW) that can be accumulated in the _overflow attribute during runtime when reporting the CCW rotation is disabled.

int32_t _negative_amortization = 0¶: Determines the maximum encoder displacement (rotation) in the clockwise (CW) that can be accumulated in the _overflow attribute during runtime when reporting the CW rotation is disabled.

Private Static Attributes

static int32_t kMultiplier = kInvertDirection ? -1 : 1¶: Stores the multiplier used to optionally invert the pulse counter sign to virtually flip the direction of encoder readouts.

static uint8_t kPPRMeasuredRotations = 10¶: The number of full encoder rotations to measure when estimating the Pulse-Per-Revolution (PPR) value.

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

bool report_ccw = true¶: Determines whether to report rotation in the CCW direction.

bool report_cw = true¶: Determines whether to report rotation in the CW direction.

uint32_t delta_threshold = 15¶: The minimum displacement change (delta) for reporting rotation.

Lick Module¶

Provides the LickModule class that monitors and records the data produced by a conductive lick sensor.

template<const uint8_t kPin> class LickModule : public Module¶

#include <lick_module.h>

Monitors the voltage fluctuations measured by a conductive lick sensor to detect interactions with the sensor’s circuitry.

Template Parameters:: kPin – the analog pin connected to the output terminal of the lick sensor.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kChanged¶: The sensor has experienced a significant change in the conducted voltage level.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kCheckState¶: Checks the voltage level across the sensor.

Public Functions

inline LickModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~LickModule() override = default¶

Private Functions

inline void CheckState()¶: Checks the voltage level across the sensor’s circuitry and sends it to the PC if it is significantly different from the previous readout.

Private Members

struct LickModule::CustomRuntimeParameters _custom_parameters¶

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

uint16_t signal_threshold = 300¶: The minimum voltage level to report to the PC.

uint16_t delta_threshold = 300¶: The minimum change in voltage level readouts to report to the PC.

uint8_t average_pool_size = 0¶: The number of readouts to average to determine the voltage level.

Screen Module¶

Provides the ScreenModule class that controls the screen power boards used in the Sollertia platform’s Virtual Reality system.

template<const uint8_t kPin, const bool kNormallyClosed = false> class ScreenModule : public Module¶

#include <screen_module.h>

Switches the screen power state by sending digital currents to the FET gate that shorts the power board’s button terminals.

Template Parameters:

kPin – the digital pin connected to the logic terminals of the VR screen’s power board FET gates.
kNormallyClosed – determines whether the FET relays used to control the screens’ power are closed (On / conducting) or opened (Off / not conducting) when unpowered.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kOn¶: The screen power board’s button-press signal is asserted.

enumerator kOff¶: The screen power board’s button-press signal is released.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kToggle¶: Pulses the screens’ power board FET gates to simulate pressing the screens’ power button.

Public Functions

inline ScreenModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~ScreenModule() override = default¶

Private Functions

inline void Toggle()¶: Sends a digital pulse through the output pin, using the preconfigured pulse_duration of microseconds, to simulate pressing and releasing the screens’ power button.

Private Members

struct ScreenModule::CustomRuntimeParameters _custom_parameters¶

Private Static Attributes

static bool kOn = kNormallyClosed ? LOW : HIGH¶: Stores the digital signal that needs to be sent to the output pin to simulate pressing the screens’ power button.

static bool kOff = kNormallyClosed ? HIGH : LOW¶: Stores the digital signal that needs to be sent to the output pin to simulate releasing the screens’ power button.

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

uint32_t pulse_duration = 1000000¶: The time, in microseconds, the button-press signal is held.

Torque Module¶

Provides the TorqueModule class that monitors and records the data produced by a reaction torque sensor.

template<const uint8_t kPin, const uint16_t kBaseline, const bool kInvertDirection = false> class TorqueModule : public Module¶

#include <torque_module.h>

Monitors the amplified voltage signal sent through an AD620 instrumentation amplifier to detect the direction and the magnitude of the rotational force measured by the managed torque sensor.

Note

By default, the sensor interprets torque in the counterclockwise (CCW) direction as positive and torque in the clockwise (CW) direction as negative.

Template Parameters:

kPin – the analog pin connected to the signal terminal of the AD620 instrumentation amplifier.
kBaseline – the value, in 12-bit Analog-to-Digital Converter (ADC) units, of the received signal interpreted as 0 torque.
kInvertDirection – determines whether to invert the sign of the value returned by the sensor.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kCCWTorque¶: The sensor detects torque in the counterclockwise (CCW) direction.

enumerator kCWTorque¶: The sensor detects torque in the clockwise (CW) direction.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kCheckState¶: Determines the direction and magnitude of the detected torque since the last check.

Public Functions

inline TorqueModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~TorqueModule() override = default¶

Private Functions

inline void CheckState()¶: Reads the current direction and magnitude of the torque recorded by the sensor and sends it to the PC if it is significantly different from the previous readout.

Private Members

struct TorqueModule::CustomRuntimeParameters _custom_parameters¶

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

bool report_ccw = true¶: Determines whether to report changes in the CCW direction.

bool report_cw = true¶: Determines whether to report changes in the CW direction.

uint16_t signal_threshold = 100¶: The minimum rescaled torque magnitude reported to the PC.

uint16_t delta_threshold = 70¶: The minimum signal difference to report torque changes.

uint8_t average_pool_size = 5¶: The number of readouts to average when computing torque.

TTL Module¶

Provides the TTLModule class that supports Transistor-to-Transistor Logic (TTL) communication with other hardware systems by sending or receiving TTL logic pulses.

template<const uint8_t kPin, const bool kOutput = true, const bool kStartOn = false> class TTLModule : public Module¶

#include <ttl_module.h>

Sends or receives Transistor-to-Transistor Logic (TTL) signals using the specified digital pin.

Warning

Each class instance can either receive or output TTL signals, it cannot do both at the same time!

Template Parameters:

kPin – the digital pin used to output or receive TTL signals.
kOutput – determines whether the instance is used to send TTL signals (if true) or receive TTL signals (if false).
kStartOn – determines the initial state of the output pin when the class is configured to output TTL signals.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kInputOn¶: The input TTL pin is receiving a HIGH signal.

enumerator kInputOff¶: The input TTL pin is receiving a LOW signal.

enumerator kInvalidPinMode¶: The instance’s pin mode is not valid for the requested command.

enumerator kOutputOn¶: The output TTL pin is set to HIGH.

enumerator kOutputOff¶: The output TTL pin is set to LOW.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kSendPulse¶: Sends a TTL pulse through the output pin.

enumerator kToggleOn¶: Sets the output pin to HIGH.

enumerator kToggleOff¶: Sets the output pin to LOW.

enumerator kCheckState¶: Checks the state of the input pin.

Public Functions

inline TTLModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~TTLModule() override = default¶

Private Functions

inline void SendPulse()¶: Sets the output pin to HIGH for the requested pulse_duration of microseconds and then sets it LOW.

inline void ToggleOn()¶: Sets the output pin to emit the HIGH signal.

inline void ToggleOff()¶: Sets the output pin to emit the LOW signal.

inline void CheckState()¶: Checks the state of the input pin and sends it to the PC if it is significantly different from the previous readout.

Private Members

struct TTLModule::CustomRuntimeParameters _custom_parameters¶

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

uint32_t pulse_duration = 10000¶: The time, in microseconds, the pin outputs HIGH during pulses.

uint8_t average_pool_size = 0¶: The number of digital readouts to average when checking pin state.

Valve Module¶

Provides the ValveModule class that controls a solenoid valve and, optionally, a piezoelectric tone buzzer.

Variables

static uint8_t kUnusedTonePin = 255¶: The kTonePin template parameter value used to indicate that no piezoelectric tone buzzer is connected.

template<const uint8_t kValvePin, const bool kNormallyClosed, const bool kStartClosed = true, const uint8_t kTonePin = kUnusedTonePin, const bool kNormallyOff = true, const bool kStartOff = true> class ValveModule : public Module¶

#include <valve_module.h>

Dispenses precise volumes of fluid or gas by sending digital currents through a solenoid valve and optionally emits tones by sending digital currents through a piezoelectric buzzer.

Template Parameters:

kValvePin – the digital pin connected to the logic terminal of the managed solenoid valve’s FET-gated power relay.
kNormallyClosed – determines whether the managed solenoid valve is opened (allows the fluid or gas to flow) or closed (prevents the fluid or gas from flowing) when unpowered.
kStartClosed – determines the initial state of the managed solenoid valve during class initialization.
kTonePin – the digital pin connected to the logic terminal of the managed piezoelectric buzzer’s FET-gated power relay.
kNormallyOff – determines whether the FET relay used to control the piezoelectric buzzer is closed (on / conducting) or opened (off / not conducting) when unpowered.
kStartOff – determines the initial state of the managed piezoelectric buzzer during class initialization.

Public Types

enum class kCustomStatusCodes : uint8_t¶

Defines the codes used by each module instance to communicate its runtime state to the PC.

Values:

enumerator kOpen¶: The valve is open.

enumerator kClosed¶: The valve is closed.

enumerator kCalibrated¶: The valve has completed a calibration cycle.

enumerator kToneOn¶: The tone is played.

enumerator kToneOff¶: The tone is silenced.

enumerator kInvalidToneConfiguration¶: The instance is not configured to emit audible tones.

enum class kModuleCommands : uint8_t¶

Defines the codes for the commands supported by the module’s instance.

Values:

enumerator kSendPulse¶: Opens the valve for the requested period of time and then closes it.

enumerator kToggleOn¶: Opens the managed valve.

enumerator kToggleOff¶: Closes the managed valve.

enumerator kCalibrate¶: Repeatedly opens the valve for the requested period of time.

enumerator kTonePulse¶: Activates the managed buzzer to play the tone for the requested period of time.

Public Functions

inline ValveModule(const uint8_t module_type, const uint8_t module_id, Communication &communication)¶: Initializes the base Module class.

inline bool SetCustomParameters() override¶: Overwrites the module’s runtime parameters structure with the data received from the PC.

inline bool RunActiveCommand() override¶: Resolves and executes the currently active command.

inline bool SetupModule() override¶: Sets the module instance’s software and hardware parameters to the default values.

~ValveModule() override = default¶

Private Functions

inline void Pulse()¶: Opens the valve to deliver a precise volume of fluid or gas and then closes it.

inline void Open()¶: Opens the valve.

inline void Close()¶: Closes the valve.

inline void Calibrate()¶: Delivers calibration_count consecutive valve pulses of pulse_duration microseconds each, separated by the hardcoded calibration delay.

Warning

Blocks the runtime in-place via delayMicroseconds() for the duration of the calibration burst. Intended only for offline calibration, never during an active behavior session.

inline void Tone()¶: Activates the tone buzzer to deliver an audible tone for the specified duration of time and then deactivates it.

Private Members

struct ValveModule::CustomRuntimeParameters _custom_parameters¶

uint32_t _tone_time_delta = 0¶: Stores the difference, in microseconds, between the valve’s pulse duration and the buzzer’s tone duration, if both are used during valve pulsing.

Private Static Attributes

static bool kOpen = kNormallyClosed ? HIGH : LOW¶: Stores the digital signal that needs to be sent to the valve pin to open the valve.

static bool kClose = kNormallyClosed ? LOW : HIGH¶: Stores the digital signal that needs to be sent to the valve pin to close the valve.

static bool kActivate = kNormallyOff ? HIGH : LOW¶: Stores the digital signal that needs to be sent to the tone pin to activate the tone buzzer.

static bool kInactivate = kNormallyOff ? LOW : HIGH¶: Stores the digital signal that needs to be sent to the tone pin to deactivate the tone buzzer.

static uint32_t kCalibrationDelay = 300000¶: Stores the time, in microseconds, that must separate any two consecutive pulses during the valve calibration. The value for this attribute is hardcoded for the system’s safety, as pulsing the valve too fast may generate undue stress in the calibrated hydraulic system.

struct CustomRuntimeParameters¶

Stores the instance’s addressable runtime parameters.

Public Members

uint32_t pulse_duration = 35000¶: The time, in microseconds, to keep the valve open.

uint16_t calibration_count = 500¶: The number of times to pulse the valve during calibration.

uint32_t tone_duration = 300000¶: The time, in microseconds, to keep playing the tone.