001package com.pi4j.wiringpi;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  Gertboard.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 - 2021 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 * The Gertboard has an on-board Digital to Analog (DAC) converter and an Analog to Digital (ADC)
038 * converters. These are connected via the SPI bus back to the Raspberry Pi host.
039 * </p>
040 *
041 * <p>
042 * Each of the DAC and ADC chips has 2 channels.
043 * </p>
044 *
045 * <p>
046 * The DAC has a resolution of 8 bits and produces an output voltage between 0 and 2.047 volts, the
047 * ADC has a resolution of 10 bits and can take an input voltage between 0 and 3.3 volts.
048 * </p>
049 *
050 * <p>
051 * Part of the wiringPi library includes code to setup and drive these chips in an easy to use
052 * manner.
053 * </p>
054 *
055 * <p>
056 * To use in a program, first you need to make sure that the 5 SPI jumpers are present on the
057 * Gertboard (there are 7 in total, 5 for the SPI, 2 to connect the serial to the ATmega), the
058 * photo below shows all 7 jumpers in-place.
059 * </p>
060 *
061 * <p>
062 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
063 * the following system libraries:
064 * <ul>
065 * <li>pi4j</li>
066 * <li>wiringPi</li>
067 * </ul>
068 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
069 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>)
070 * </blockquote>
071 * </p>
072 *
073 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a>
074 * @see <a
075 *      href="http://wiringpi.com/dev-lib/gertboard-analog/">http://wiringpi.com/dev-lib/gertboard-analog/</a>
076 * @author Robert Savage (<a
077 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
078 */
079public class Gertboard {
080
081    public static final int SPI_ADC_SPEED = 1000000;
082    public static final int SPI_DAC_SPEED = 1000000;
083    public static final int SPI_A2D = 0;
084    public static final int SPI_D2A = 1;
085
086    // private constructor
087    private Gertboard() {
088        // forbid object construction
089    }
090
091    static {
092        // Load the platform library
093        NativeLibraryLoader.load("libpi4j.so", "pi4j");
094    }
095
096    /**
097     * <p> This outputs the supplied value (0-255) to the given channel (0 or 1). The output voltage is:
098     *
099     * <pre>
100     * vOut = value / 255 * 2.047
101     * </pre>
102     *
103     * or to find the value for a given voltage:
104     *
105     * <pre>
106     * value = vOut / 2.047 * 255
107     * </pre>
108     * </p>
109     * @see <a
110     *      href="http://wiringpi.com/dev-lib/gertboard-analog/">http://wiringpi.com/dev-lib/gertboard-analog/</a>
111     * @param chan  Analog channel to write to (0 or 1).
112     * @param value The output value (0-255) supplied to the given channel (0 or 1).
113     */
114    public static native void gertboardAnalogWrite(int chan, int value);
115
116    /**
117     * <p> This returns a value from 0 to 1023 representing the value on the supplied channel (0 or 1).
118     * To convert this to a voltage, use the following formula:
119     *
120     * <pre>
121     * vIn = value * 3.3 / 1023
122     * </pre>
123     * </p>
124     *
125     * @see <a
126     *      href="http://wiringpi.com/dev-lib/gertboard-analog/">http://wiringpi.com/dev-lib/gertboard-analog/</a>
127     * @param chan Analog channel to read from (0 or 1).
128     * @return This returns a value from 0 to 1023 representing the value on the supplied channel (0
129     *         or 1).
130     */
131    public static native int gertboardAnalogRead(int chan);
132
133    /**
134     * <p> This must be called to initialize the SPI bus to communicate with the Gertboards ADC and DAC
135     * chips. If the return value is < 0 then an error occurred and errno will be set appropriately.
136     * </p>
137     *
138     * @see <a
139     *      href="http://wiringpi.com/dev-lib/gertboard-analog/">http://wiringpi.com/dev-lib/gertboard-analog/</a>
140     * @return If the return value is < 0 then an error occurred and errno will be set
141     *         appropriately. If the return value is '0' or greater than the call was successful.
142     */
143    public static native int gertboardSPISetup();
144
145
146
147    /**
148     * <p>
149     * This setup routine allocates 2 pins and overlays the analog to digital input pins with the digital to analog
150     * output pins. So reading channel pinBase + 0 reads the first analog input channel (pin DA0 on the Gertboard),
151     * and writing pinBase + 0 outputs to the first analog output channel. (Pin AD0).
152     * </p>
153     *
154     * @see <a
155     *      href="http://wiringpi.com/dev-lib/gertboard-analog/">http://wiringpi.com/dev-lib/gertboard-analog/</a>
156     * @param pinBase pinBase is the base pin that you want the analog ports to appear as
157     * @return If the return value is < 0 then an error occurred and errno will be set
158     *         appropriately. If the return value is '0' or greater than the call was successful.
159     */
160    public static native int gertboardAnalogSetup(int pinBase);
161}