001package com.pi4j.io.i2c;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  I2CDevice.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
032import java.io.IOException;
033import java.nio.ByteBuffer;
034import java.nio.IntBuffer;
035
036/**
037 * This is abstraction of an i2c device. It allows data to be read or written to the device.
038 *
039 * @author Daniel Sendula, refactored by <a href="http://raspelikan.blogspot.co.at">RasPelikan</a>
040 *
041 */
042public interface I2CDevice {
043
044    /**
045     * @return The address for which this instance is constructed for.
046     */
047    int getAddress();
048
049    /**
050     * This method writes one byte directly to i2c device.
051     *
052     * @param b byte to be written
053     *
054     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
055     */
056    void write(byte b) throws IOException;
057
058    /**
059     * This method writes several bytes directly to the i2c device from given buffer at given offset.
060     *
061     * @param buffer buffer of data to be written to the i2c device in one go
062     * @param offset offset in buffer
063     * @param size number of bytes to be written
064     *
065     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
066     */
067    void write(byte[] buffer, int offset, int size) throws IOException;
068
069    /**
070     * This method writes all bytes included in the given buffer directly to the i2c device.
071     *
072     * @param buffer buffer of data to be written to the i2c device in one go
073     *
074     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
075     */
076    void write(byte[] buffer) throws IOException;
077
078    /**
079     * This method writes one byte to i2c device.
080     *
081     * @param address local address in the i2c device
082     * @param b byte to be written
083     *
084     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
085     */
086    void write(int address, byte b) throws IOException;
087
088    /**
089     * This method writes several bytes to the i2c device from given buffer at given offset.
090     *
091     * @param address local address in the i2c device
092     * @param buffer buffer of data to be written to the i2c device in one go
093     * @param offset offset in buffer
094     * @param size number of bytes to be written
095     *
096     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
097     */
098    void write(int address, byte[] buffer, int offset, int size) throws IOException;
099
100    /**
101     * This method writes all bytes included in the given buffer directoy to the register address on the i2c device
102     *
103     * @param address local address in the i2c device
104     * @param buffer buffer of data to be written to the i2c device in one go
105     *
106     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
107     */
108    void write(int address, byte[] buffer) throws IOException;
109
110    /**
111     * This method reads one byte from the i2c device.
112     * Result is between 0 and 255 if read operation was successful, else a negative number for an error.
113     *
114     * @return byte value read: positive number (or zero) to 255 if read was successful. Negative number if reading failed.
115     *
116     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
117     */
118    int read() throws IOException;
119
120    /**
121     * This method reads bytes directly from the i2c device to given buffer at asked offset.
122     *
123     * @param buffer buffer of data to be read from the i2c device in one go
124     * @param offset offset in buffer
125     * @param size number of bytes to be read
126     *
127     * @return number of bytes read
128     *
129     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
130     */
131    int read(byte[] buffer, int offset, int size) throws IOException;
132
133    /**
134     * This method reads one byte from the i2c device.
135     * Result is between 0 and 255 if read operation was successful, else a negative number for an error.
136     *
137     * @param address local address in the i2c device
138     * @return byte value read: positive number (or zero) to 255 if read was successful. Negative number if reading failed.
139     *
140     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
141     */
142    int read(int address) throws IOException;
143
144    /**
145     * This method reads bytes from the i2c device to given buffer at asked offset.
146     *
147     * @param address local address in the i2c device
148     * @param buffer buffer of data to be read from the i2c device in one go
149     * @param offset offset in buffer
150     * @param size number of bytes to be read
151     *
152     * @return number of bytes read
153     *
154     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
155     */
156    int read(int address, byte[] buffer, int offset, int size) throws IOException;
157
158    /**
159     * Runs an ioctl on this device.
160     *
161     * @see com.pi4j.io.file.LinuxFile#ioctl(long, int)
162     */
163    void ioctl(long command, int value) throws IOException;
164
165    /**
166     * Runs an ioctl on this device.
167     *
168     * @see com.pi4j.io.file.LinuxFile#ioctl(long, ByteBuffer, IntBuffer)
169     */
170    void ioctl(long command, ByteBuffer data, IntBuffer offsets) throws IOException;
171
172    /**
173     * This method writes and reads bytes to/from the i2c device in a single method call
174     *
175     * @param writeBuffer buffer of data to be written to the i2c device in one go
176     * @param writeOffset offset in write buffer
177     * @param writeSize number of bytes to be written from buffer
178     * @param readBuffer buffer of data to be read from the i2c device in one go
179     * @param readOffset offset in read buffer
180     * @param readSize number of bytes to be read
181     *
182     * @return number of bytes read
183     *
184     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
185     */
186    int read(byte[] writeBuffer, int writeOffset, int writeSize, byte[] readBuffer, int readOffset, int readSize) throws IOException;
187
188}