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.phoenix6.controls;
008
009import com.ctre.phoenix6.StatusCode;
010import com.ctre.phoenix6.controls.jni.ControlJNI;
011
012import java.util.HashMap;
013import java.util.Map;
014
015/**
016 * Plays a single tone at the user specified frequency.
017 */
018public class MusicTone extends ControlRequest implements Cloneable
019{
020    /**
021     * Sound frequency to play.  A value of zero will silence the device. The
022     * effective frequency range is 10-20000Hz.  Any nonzero frequency less than 10
023     * Hz will be capped to 10Hz.  Any frequency above 20Khz will be capped to
024     * 20KHz.
025     */
026    public double AudioFrequency;
027
028    /**
029     * The period at which this control will update at.
030     * This is designated in Hertz, with a minimum of 20 Hz
031     * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
032     * <p>
033     * If this field is set to 0 Hz, the control request will
034     * be sent immediately as a one-shot frame. This may be useful
035     * for advanced applications that require outputs to be
036     * synchronized with data acquisition. In this case, we
037     * recommend not exceeding 50 ms between control calls.
038     */
039    public double UpdateFreqHz = 100; // Default to 100Hz
040
041    /**
042     * Plays a single tone at the user specified frequency.
043     * 
044     * @param AudioFrequency    Sound frequency to play.  A value of zero will
045     *                          silence the device. The effective frequency range is
046     *                          10-20000Hz.  Any nonzero frequency less than 10 Hz
047     *                          will be capped to 10Hz.  Any frequency above 20Khz
048     *                          will be capped to 20KHz.
049     */
050    public MusicTone(double AudioFrequency)
051    {
052        super("MusicTone");
053        this.AudioFrequency = AudioFrequency;
054    }
055
056    @Override
057    public String toString()
058    {
059        String ss = "class: MusicTone\n";
060        ss += "AudioFrequency: " + AudioFrequency + "\n";
061        return ss;
062    }
063
064    @Override
065    public StatusCode sendRequest(String network, int deviceHash, boolean cancelOtherRequests)
066    {
067        return StatusCode.valueOf(ControlJNI.JNI_RequestControlMusicTone(
068                network, deviceHash, UpdateFreqHz, cancelOtherRequests, AudioFrequency));
069    }
070
071    /**
072     * Gets information about this control request.
073     *
074     * @return Map of control parameter names and corresponding applied values
075     */
076    @Override
077    public Map<String, String> getControlInfo()
078    {
079        var controlInfo = new HashMap<String, String>();
080        controlInfo.put("Name", getName());
081        controlInfo.put("AudioFrequency", String.valueOf(this.AudioFrequency));
082        return controlInfo;
083    }
084    
085    /**
086     * Modifies this Control Request's AudioFrequency parameter and returns itself for
087     * method-chaining and easier to use request API.
088     * <p>
089     * Sound frequency to play.  A value of zero will silence the device. The
090     * effective frequency range is 10-20000Hz.  Any nonzero frequency less than 10
091     * Hz will be capped to 10Hz.  Any frequency above 20Khz will be capped to
092     * 20KHz.
093     *
094     * @param newAudioFrequency Parameter to modify
095     * @return Itself
096     */
097    public MusicTone withAudioFrequency(double newAudioFrequency)
098    {
099        AudioFrequency = newAudioFrequency;
100        return this;
101    }
102    /**
103     * Sets the period at which this control will update at.
104     * This is designated in Hertz, with a minimum of 20 Hz
105     * (every 50 ms) and a maximum of 1000 Hz (every 1 ms).
106     * <p>
107     * If this field is set to 0 Hz, the control request will
108     * be sent immediately as a one-shot frame. This may be useful
109     * for advanced applications that require outputs to be
110     * synchronized with data acquisition. In this case, we
111     * recommend not exceeding 50 ms between control calls.
112     *
113     * @param newUpdateFreqHz Parameter to modify
114     * @return Itself
115     */
116    public MusicTone withUpdateFreqHz(double newUpdateFreqHz)
117    {
118        UpdateFreqHz = newUpdateFreqHz;
119        return this;
120    }
121
122    @Override
123    public MusicTone clone()
124    {
125        try {
126            return (MusicTone)super.clone();
127        } catch (CloneNotSupportedException ex) {
128            /* this should never happen */
129            throw new RuntimeException(ex);
130        }
131    }
132}
133