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