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