001/*
002 * Copyright (C) Cross The Road Electronics.  All rights reserved.
003 * License information can be found in CTRE_LICENSE.txt
004 * For support and suggestions contact support@ctr-electronics.com or file
005 * an issue tracker at https://github.com/CrossTheRoadElec/Phoenix-Releases
006 */
007package com.ctre.phoenixpro.controls;
008
009import com.ctre.phoenix6.StatusCode;
010import com.ctre.phoenix6.controls.jni.ControlJNI;
011import com.ctre.phoenix6.controls.jni.ControlConfigJNI;
012import com.ctre.phoenixpro.configs.*;
013
014/**
015 * Request a specified voltage.
016 * <p>
017 * This control mode will attempt to apply the specified voltage to the motor. If the supply voltage is below
018 * the requested voltage, the motor controller will output the supply voltage.
019 *
020 * @deprecated Classes in the phoenixpro package will be removed in 2024.
021 *             Users should instead use classes from the phoenix6 package.
022 */
023@Deprecated(forRemoval = true)
024public class VoltageOut extends ControlRequest
025{
026    private boolean applyConfigsOnRequest;
027    /**
028     * Voltage to attempt to drive at
029     */
030    public double Output;
031    /**
032     * Set to true to use FOC commutation, which increases peak power by ~15%. Set
033     * to false to use trapezoidal commutation.  FOC improves motor performance by
034     * leveraging torque (current) control.  However, this may be inconvenient for
035     * applications that require specifying duty cycle or voltage.  CTR-Electronics
036     * has developed a hybrid method that combines the performances gains of FOC
037     * while still allowing applications to provide duty cycle or voltage demand. 
038     * This not to be confused with simple sinusoidal control or phase voltage
039     * control which lacks the performance gains.
040     */
041    public boolean EnableFOC;
042    /**
043     * Set to true to static-brake the rotor when output is zero (or within
044     * deadband).  Set to false to use the NeutralMode configuration setting
045     * (default). This flag exists to provide the fundamental behavior of this
046     * control when output is zero, which is to provide 0V to the motor.
047     */
048    public boolean OverrideBrakeDurNeutral;
049
050    /**
051     *  Voltage-specific configs
052     * <p>
053     *  Voltage-specific configs
054     */
055    public VoltageConfigs Voltage = new VoltageConfigs();
056    /**
057     * The period at which this control will update at.
058     * This is designated in Hertz, with a minimum of 20 Hz
059     * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
060     * <p>
061     * If this field is set to 0 Hz, the control request will
062     * be sent immediately as a one-shot frame. This may be useful
063     * for advanced applications that require outputs to be
064     * synchronized with data acquisition. In this case, we
065     * recommend not exceeding 50 ms between control calls.
066     */
067    public double UpdateFreqHz = 100; // Default to 100Hz
068
069    /**
070     * The timeout when sending configs associated with this control
071     */
072    public double configTimeout = 0.1;
073
074    /**
075     * Request a specified voltage.
076     * <p>
077     * This control mode will attempt to apply the specified voltage to the
078     * motor. If the supply voltage is below the requested voltage, the motor
079     * controller will output the supply voltage.
080     *
081     * @param Output     Voltage to attempt to drive at
082     * @param EnableFOC     Set to true to use FOC commutation, which increases
083     *                      peak power by ~15%. Set to false to use trapezoidal
084     *                      commutation.  FOC improves motor performance by
085     *                      leveraging torque (current) control.  However, this
086     *                      may be inconvenient for applications that require
087     *                      specifying duty cycle or voltage.  CTR-Electronics
088     *                      has developed a hybrid method that combines the
089     *                      performances gains of FOC while still allowing
090     *                      applications to provide duty cycle or voltage
091     *                      demand.  This not to be confused with simple
092     *                      sinusoidal control or phase voltage control which
093     *                      lacks the performance gains.
094     * @param OverrideBrakeDurNeutral     Set to true to static-brake the rotor
095     *                                    when output is zero (or within
096     *                                    deadband).  Set to false to use the
097     *                                    NeutralMode configuration setting
098     *                                    (default). This flag exists to provide
099     *                                    the fundamental behavior of this
100     *                                    control when output is zero, which is
101     *                                    to provide 0V to the motor.
102     *
103     * @deprecated Classes in the phoenixpro package will be removed in 2024.
104     *             Users should instead use classes from the phoenix6 package.
105     */
106    @Deprecated(forRemoval = true)
107    public VoltageOut(double Output, boolean EnableFOC, boolean OverrideBrakeDurNeutral)
108    {
109        super("VoltageOut");
110        this.Output = Output;
111        this.EnableFOC = EnableFOC;
112        this.OverrideBrakeDurNeutral = OverrideBrakeDurNeutral;
113    }
114
115    /**
116     * Request a specified voltage.
117     * <p>
118     * This control mode will attempt to apply the specified voltage to the
119     * motor. If the supply voltage is below the requested voltage, the motor
120     * controller will output the supply voltage.
121     *
122     * @param Output     Voltage to attempt to drive at
123     *
124     * @deprecated Classes in the phoenixpro package will be removed in 2024.
125     *             Users should instead use classes from the phoenix6 package.
126     */
127    @Deprecated(forRemoval = true)
128    public VoltageOut(double Output)
129    {
130        this(Output, true, false);
131    }
132
133    @Override
134    public String toString()
135    {
136        String ss = "class: VoltageOut\n";
137        ss += "Output: " + Output + "\n";
138        ss += "EnableFOC: " + EnableFOC + "\n";
139        ss += "OverrideBrakeDurNeutral: " + OverrideBrakeDurNeutral + "\n";
140        return ss;
141    }
142
143    @Override
144    public StatusCode sendRequest(String network, int deviceHash, boolean cancelOtherRequests)
145    {
146        var ref = requestReference.getNameValues();
147        ref.put("Output", String.valueOf(this.Output));
148        ref.put("EnableFOC", String.valueOf(this.EnableFOC));
149        ref.put("OverrideBrakeDurNeutral", String.valueOf(this.OverrideBrakeDurNeutral));
150        String ss = "";
151        ss += Voltage.serialize();
152        ControlConfigJNI.JNI_RequestConfigApply(network, deviceHash, configTimeout, ss, applyConfigsOnRequest);
153        applyConfigsOnRequest = false;
154        return StatusCode.valueOf(ControlJNI.JNI_RequestControlVoltageOut(
155                network, deviceHash, UpdateFreqHz, cancelOtherRequests, Output, EnableFOC, OverrideBrakeDurNeutral));
156    }
157    
158    /**
159     * Modifies this Control Request's Output parameter and returns itself for
160     * method-chaining and easier to use request API.
161     *
162     * @param newOutput Parameter to modify
163     * @return Itself
164     */
165    public VoltageOut withOutput(double newOutput)
166    {
167        Output = newOutput;
168        return this;
169    }
170    
171    /**
172     * Modifies this Control Request's EnableFOC parameter and returns itself for
173     * method-chaining and easier to use request API.
174     *
175     * @param newEnableFOC Parameter to modify
176     * @return Itself
177     */
178    public VoltageOut withEnableFOC(boolean newEnableFOC)
179    {
180        EnableFOC = newEnableFOC;
181        return this;
182    }
183    
184    /**
185     * Modifies this Control Request's OverrideBrakeDurNeutral parameter and returns itself for
186     * method-chaining and easier to use request API.
187     *
188     * @param newOverrideBrakeDurNeutral Parameter to modify
189     * @return Itself
190     */
191    public VoltageOut withOverrideBrakeDurNeutral(boolean newOverrideBrakeDurNeutral)
192    {
193        OverrideBrakeDurNeutral = newOverrideBrakeDurNeutral;
194        return this;
195    }
196    /**
197     * Sets the period at which this control will update at.
198     * This is designated in Hertz, with a minimum of 20 Hz
199     * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
200     * <p>
201     * If this field is set to 0 Hz, the control request will
202     * be sent immediately as a one-shot frame. This may be useful
203     * for advanced applications that require outputs to be
204     * synchronized with data acquisition. In this case, we
205     * recommend not exceeding 50 ms between control calls.
206     *
207     * @param newUpdateFreqHz Parameter to modify
208     * @return Itself
209     */
210    public VoltageOut withUpdateFreqHz(double newUpdateFreqHz)
211    {
212        UpdateFreqHz = newUpdateFreqHz;
213        return this;
214    }
215    /**
216     * Forces configs to be applied the next time this is used in a setControl.
217     * <p>
218     * This is not necessary in the majority of cases, because Phoenix will make sure configs are
219     * properly set when they are not already set
220     */
221    public void forceApplyConfigs() { applyConfigsOnRequest = true; }
222}
223