CANdle

class phoenix5.led.CANdle(deviceId: int, canbus: str = '')

Bases: pybind11_object

CTRE CANdle

Device for controlling LEDs from the CAN bus.

{@code
// Example usage of a CANdle
CANdle candle{0}; // creates a new CANdle with ID 0

CANdleConfiguration config;
config.stripType = LEDStripType::RGB; // set the strip type to RGB
config.brightnessScalar = 0.5; // dim the LEDs to half brightness
candle.ConfigAllSettings(config);

candle.SetLEDs(255, 255, 255); // set the CANdle LEDs to white

// create a rainbow animation:
// - max brightness
// - half speed
// - 64 LEDs
RainbowAnimation rainbowAnim{1, 0.5, 64};
candle.Animate(rainbowAnim);

ErrorCode error = candle.GetLastError(); // gets the last error generated by the CANdle
CANdleFaults faults;
ErrorCode faultsError = candle.GetFaults(faults); // fills faults with the current CANdle faults; returns the last error generated
}

Constructor for a CANdle Device

Parameters:

  • deviceId – The Device ID of the CANdle

  • canbus – Name of the CANbus; can be a SocketCAN interface (on Linux), or a CANivore device name or serial number

animate(animation: phoenix5._ctre.led.Animation, animSlot: int = 0) → phoenix5._ctre.ErrorCode

Animates the CANdle with the passed-in animation If the animation changes after calling this function, it must be passed into animate again for the changes to take effect

Parameters:

  • animation – The animation that CANdle will run. If this is null, it will clear the animation at the specified slot

  • animSlot – The animation slot to use for the animation, range is [0, getMaxSimultaneousAnimationCount()) exclusive

Returns:

ErrorCode generated by function. OK indicates no error.

clearStickyFaults(timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Clears the sticky faults.

Parameters:

timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configAllSettings(allConfigs: phoenix5._ctre.led.CANdleConfiguration, timeoutMs: int = 50) → phoenix5._ctre.ErrorCode

Configures all persistent settings.

Parameters:

  • allConfigs – Object with all of the persistant settings

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configBrightnessScalar(brightness: float, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures the brightness scalar to be applied to every LED output. This value is bounded to [0, 1].

Setting this to 1 will allow the LEDs to function at max brightness. Setting this to 0.5 will scale all values to half their applied value. Setting this to 0 will turn off the LEDs.

Forcing the LEDs off this way may be useful in certain testing circumstances but is generally not necessary. Self-test (Tuner) may be used to verify what the effective scalar is in case user forgot to restore the scalar to a non-zero value.

Parameters:

  • brightness – Value from [0, 1] that will scale the LED output.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configFactoryDefault(timeoutMs: int = 50) → phoenix5._ctre.ErrorCode

Configures all persistent settings to defaults.

Parameters:

timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configGetCustomParam(paramIndex: int, timeoutMs: int = 0) → int

Gets the value of a custom parameter. This is for arbitrary use.

Sometimes it is necessary to save calibration/duty cycle/output information in the device. Particularly if the device is part of a subsystem that can be replaced.

Parameters:

  • paramIndex – Index of custom parameter. [0-1]

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Value of the custom param.

configGetParameter(param: phoenix5._ctre.ParamEnum, ordinal: int, timeoutMs: int = 0) → float

Gets a parameter. Generally this is not used. This can be utilized in - Using new features without updating API installation. - Errata workarounds to circumvent API implementation. - Allows for rapid testing / unit testing of firmware.

Parameters:

  • param – Parameter enumeration.

  • ordinal – Ordinal of parameter.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Value of parameter.

configLEDType(type: phoenix5._ctre.led.LEDStripType, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures the type of LED the CANdle controls

Parameters:

  • type – The type of the LEDs the CANdle controls

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

ErrorCode generated by function. OK indicates no error.

configLOSBehavior(disableWhenLOS: bool, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures what the CANdle should do if it loses communications to the Controller

Parameters:

  • disableWhenLOS – Set to true to disable the LEDs on Loss of Signal.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

ErrorCode generated by function. OK indicates no error.

configSetCustomParam(paramIndex: int, value: int, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Sets the value of a custom parameter. This is for arbitrary use.

Sometimes it is necessary to save calibration/duty cycle/output information in the device. Particularly if the device is part of a subsystem that can be replaced.

Parameters:

  • newValue – Value for custom parameter.

  • paramIndex – Index of custom parameter. [0-1]

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configSetParameter(param: phoenix5._ctre.ParamEnum, value: float, subValue: int = 0, ordinal: int = 0, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Sets a parameter. Generally this is not used. This can be utilized in - Using new features without updating API installation. - Errata workarounds to circumvent API implementation. - Allows for rapid testing / unit testing of firmware.

Parameters:

  • param – Parameter enumeration.

  • value – Value of parameter.

  • subValue – Subvalue for parameter. Maximum value of 255.

  • ordinal – Ordinal of parameter.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configStatusLedState(disableWhenRunning: bool, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures how the status led will behave when the CANdle is actively controlling LEDs If the CANdle is LOS or not actively commanded a value, it will always turn on its status LED.

Parameters:

  • disableWhenRunning – Disables the status LED when the CANdle is running

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

configV5Enabled(v5Enabled: bool, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures the enable state for the 5V rail. This also affects the on-board LEDs.

Parameters:

  • v5Enabled – True to enable the 5V rail.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

ErrorCode generated by function. OK indicates no error.

configVBatOutput(mode: phoenix5._ctre.led.VBatOutputMode, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Configures how the VBat Output will behave

Parameters:

  • mode – VBat Output Behavior

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.

get5VRailVoltage() → float

Gets the Voltage of the 5V line as measured by CANdle

Returns:

Voltage of the 5V line

getAllConfigs(allConfigs: phoenix5._ctre.led.CANdleConfiguration, timeoutMs: int = 50) → None

Gets all persistant settings.

Parameters:

  • allConfigs – Object with all of the persistant settings

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

getBusVoltage() → float

Gets the Voltage of VBat as measured by CANdle

Returns:

Voltage of VBat

getCurrent() → float

Gets the low-side current as measured by CANdle

Returns:

Current in Amps

getFaults(toFill: phoenix5._ctre.led.CANdleFaults) → phoenix5._ctre.ErrorCode

Gets the CANdle fault status

Parameters:

toFill – Container for fault statuses.

Returns:

Error Code generated by function. OK indicates no error.

getLastError() → phoenix5._ctre.ErrorCode

Call GetLastError() generated by this object. Not all functions return an error code but can potentially report errors.

This function can be used to retrieve those error codes.

Returns:

The last ErrorCode generated.

getMaxSimultaneousAnimationCount() → int

Gets the maximum number of simultaneous animations this version of CANdle firmware supports. If you specify an animation slot >= to this return, Phoenix will error out. You can also get the maximum count from a self-test snapshot.

Returns:

Maximum number of simultaneous animations this version of firmware supports.

getStatusFramePeriod(frame: phoenix5._ctre.led.CANdleStatusFrame, timeoutMs: int = 0) → int

Gets the period of the given status frame.

Parameters:

  • frame – Frame to get the period of.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Period of the given status frame.

getStickyFaults(toFill: phoenix5._ctre.led.CANdleStickyFaults) → phoenix5._ctre.ErrorCode

Gets the CANdle sticky fault status

Parameters:

toFill – Container for sticky fault statuses.

Returns:

Error Code generated by function. OK indicates no error.

getTemperature() → float

Gets the temperature of the CANdle in Celcius

Returns:

Temperature in Celcius

getVBatModulation() → float

Gets the applied vbat modulation in percent. If the CANdle is configured to always enable VBat, this returns 1 If the CANdle is confgigured to always disable VBat, this returns 0 Otherwise it returns the last set Modulation as a value [0, 1]

Returns:

VBat Output Modulation

hasResetOccurred() → bool

Returns true if the device has reset since last call.

Returns:

Has a Device Reset Occurred?

modulateVBatOutput(dutyCyclePrcnt: float) → phoenix5._ctre.ErrorCode

Modulates the VBat output to the specified duty cycle percentage This function will only do something if the CANdle’s VBatOutput is configured to Modulated

Parameters:

dutyCyclePrcnt – The duty cycle of the output modulation [0, 1]

Returns:

ErrorCode generated by function. OK indicates no error.

setControlFramePeriod(frame: phoenix5._ctre.led.CANdleControlFrame, periodMs: int) → phoenix5._ctre.ErrorCode

Sets the period of the given control frame.

Parameters:

  • frame – Frame whose period is to be changed.

  • periodMs – Period in ms for the given frame.

Returns:

Error Code generated by function. 0 indicates no error.

setLEDs(r: int, g: int, b: int, w: int = 0, startIdx: int = 0, count: int = 512) → phoenix5._ctre.ErrorCode

Sets a block of LEDs to the specified color

Parameters:

  • r – The amount of Red to set, range is [0, 255]

  • g – The amount of Green to set, range is [0, 255]

  • b – The amount of Blue to set, range is [0, 255]

  • w – The amount of White to set, range is [0, 255]. This only applies for LED strips with white in them.

  • startIdx – Where to start setting the LEDs

  • count – The number of LEDs to apply this to

Returns:

ErrorCode generated by function. OK indicates no error.

setStatusFramePeriod(frame: phoenix5._ctre.led.CANdleStatusFrame, periodMs: int, timeoutMs: int = 0) → phoenix5._ctre.ErrorCode

Sets the period of the given status frame.

Parameters:

  • frame – Frame whose period is to be changed.

  • periodMs – Period in ms for the given frame.

  • timeoutMs – Timeout value in ms. If nonzero, function will wait for config success and report an error if it times out. If zero, no blocking or checking is performed.

Returns:

Error Code generated by function. 0 indicates no error.