001package com.pi4j.io.spi;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  SpiDevice.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 java.io.*;
034import java.nio.ByteBuffer;
035import java.nio.charset.Charset;
036
037public interface SpiDevice {
038
039    public static final SpiMode DEFAULT_SPI_MODE = SpiMode.MODE_0;
040    public static final int DEFAULT_SPI_SPEED = 1000000; // 1MHz (range is 500kHz - 32MHz)
041    public static final int MAX_SUPPORTED_BYTES = 2048;
042
043    /**
044     * Attempts to read/write data through this SPI device
045     *
046     * @param data
047     *            bytes (encoded in string) to write to the SPI device
048     * @param charset
049     *            character encoding for bytes in string
050     * @return resulting bytes read from the SPI device after the write operation
051     */
052    public String write(String data, Charset charset) throws IOException;
053
054    /**
055     * Attempts to read/write data through this SPI device
056     *
057     * @param data
058     *            bytes (encoded in string) to write to the SPI device
059     * @param charset
060     *            character encoding for bytes in string
061     * @return resulting bytes read from the SPI device after the write operation
062     */
063    public String write(String data, String charset) throws IOException;
064
065    /**
066     * Attempts to read/write data through this SPI device
067     *
068     * @param data
069     *            bytes to write to the SPI device
070     * @return resulting bytes read from the SPI device after the write operation
071     */
072    public ByteBuffer write(ByteBuffer data) throws IOException;
073
074    /**
075     * Attempts to read/write data through this SPI device
076     *
077     * @param input
078     *            input stream to read from to get
079     *            bytes to write to the SPI device
080     * @return resulting bytes read from the SPI device after the write operation
081     */
082    public byte[] write(InputStream input) throws IOException;
083
084    /**
085     * Attempts to read/write data through this SPI device
086     *
087     * @param input
088     *            input stream to read from to get
089     *            bytes to write to the SPI device
090     * @param output
091     *            output stream to write bytes
092     *            read from the SPI device
093     * @return number of resulting bytes read from the SPI device and written to the output stream
094     */
095    public int write(InputStream input, OutputStream output) throws IOException;
096
097    /**
098     * Attempts to read/write data through this SPI device
099     *
100     * @param data
101     *            bytes to write to the SPI device
102     * @param start
103     *            start index position in the data buffer to start writing from
104     * @param length
105     *            length of bytes to write from the data buffer
106     * @return resulting bytes read from the SPI device after the write operation
107     */
108    public byte[] write(byte[] data, int start, int length) throws IOException;
109
110    /**
111     * Attempts to read/write data through this SPI device
112     *
113     * @param data
114     *            bytes to write to the SPI device
115     * @return resulting bytes read from the SPI device after the write operation
116     */
117    public byte[] write(byte ... data) throws IOException;
118
119    /**
120     * Attempts to read/write data through this SPI device
121     *
122     * @param data
123     *            bytes to write to the SPI device
124     * @param start
125     *            start index position in the data buffer to start writing from
126     * @param length
127     *            length of bytes to write from the data buffer
128     * @return resulting bytes read from the SPI device after the write operation
129     */
130    public short[] write(short[] data, int start, int length) throws IOException;
131
132    /**
133     * Attempts to read/write data through this SPI device
134     *
135     * @param data
136     *            bytes to write to the SPI device (Note: short value should not exceed 255.)
137     * @return resulting bytes read from the SPI device after the write operation
138     */
139    public short[] write(short ... data) throws IOException;
140
141}