001package com.pi4j.wiringpi;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  SoftTone.java
009 *
010 * This file is part of the Pi4J project. More information about
011 * this project can be found here:  https://www.pi4j.com/
012 * **********************************************************************
013 * %%
014 * Copyright (C) 2012 - 2019 Pi4J
015 * %%
016 * This program is free software: you can redistribute it and/or modify
017 * it under the terms of the GNU Lesser General Public License as
018 * published by the Free Software Foundation, either version 3 of the
019 * License, or (at your option) any later version.
020 *
021 * This program is distributed in the hope that it will be useful,
022 * but WITHOUT ANY WARRANTY; without even the implied warranty of
023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
024 * GNU General Lesser Public License for more details.
025 *
026 * You should have received a copy of the GNU General Lesser Public
027 * License along with this program.  If not, see
028 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
029 * #L%
030 */
031
032
033import com.pi4j.util.NativeLibraryLoader;
034
035/**
036 * <p>
037 * WiringPi includes a software-driven sound handler capable of outputting a simple tone/square wave signal on any of
038 * the Raspberry Pi’s GPIO pins.
039 * </p>
040 *
041 * <p>
042 * There are some limitations… To maintain a low CPU usage, the minimum pulse width is 100μS. That gives a maximum
043 * frequency of  1/0.0002 = 5000Hz.
044 * </p>
045 *
046 * <p>
047 * Also note that while the routines run themselves at a higher and real-time priority, Linux can still affect the
048 * accuracy of the generated tone.
049 * </p>
050 *
051 * <p>
052 * However, within these limitations, simple tones on a high impedance speaker or piezo sounder is possible.
053 * </p>
054 *
055 * <p>
056 * NOTES:  - Each pin activated in softTone mode uses approximately 0.5% of the CPU.
057           - You need to keep your program running to maintain the sound output!
058 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
059 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>)
060 * </blockquote>
061 * </p>
062 *
063 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a>
064 * @see <a
065 *      href="http://wiringpi.com/reference/software-tone-library/">http://wiringpi.com/reference/software-tone-library/</a>
066 * @author Robert Savage (<a
067 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
068 */
069public class SoftTone {
070
071    // private constructor
072    private SoftTone() {
073        // forbid object construction
074    }
075
076    static {
077        // Load the platform library
078        NativeLibraryLoader.load("libpi4j.so");
079    }
080
081    /**
082     * <p>int softToneCreate (int pin)</p>
083     *
084     * <p>
085     * This creates a software controlled tone pin. You can use any GPIO pin and the pin numbering will be that of
086     * the wiringPiSetup() function you used.
087     * </p>
088     *
089     * @see <a
090     *      href="http://wiringpi.com/reference/software-tone-library/">http://wiringpi.com/reference/software-tone-library/</a>
091     *
092     * @param pin The GPIO pin to use as a PWM pin.
093     *            </p>
094     * @return The return value is 0 for success. Anything else and you should check the global
095     *         errno variable to see what went wrong.
096     */
097    public static native int softToneCreate(int pin);
098
099    /**
100     * <p>void softToneWrite (int pin, int frequency);</p>
101     *
102     * <p>
103     * This updates the tone frequency value on the given pin. The tone will be played until you set the frequency to 0.
104     * </p>
105     *
106     * @see <a
107     *      href="http://wiringpi.com/reference/software-tone-library/">http://wiringpi.com/reference/software-tone-library/</a>
108     *
109     * @param pin The GPIO pin to use.
110     * @param frequency The frequency value set on the GPIO pin.  Set of value of '0' to stop the tone.
111     */
112    public static native void softToneWrite(int pin, int frequency);
113
114    /**
115     * <p>void softToneStop (int pin);</p>
116     *
117     * <p>
118     * This stops any tone frequency value on the given pin.
119     * </p>
120     *
121     * @see <a
122     *      href="http://wiringpi.com/reference/software-tone-library/">http://wiringpi.com/reference/software-tone-library/</a>
123     *
124     * @param pin The GPIO pin to use.
125     */
126    public static native void softToneStop(int pin);
127}