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 - 2015 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
038 *
039 */
040public interface I2CDevice {
041
042    /**
043     * This method writes one byte directly to i2c device.
044     * 
045     * @param b byte to be written
046     * 
047     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
048     */
049    void write(byte b) throws IOException;
050
051    /**
052     * This method writes several bytes directly to the i2c device from given buffer at given offset.
053     * 
054     * @param buffer buffer of data to be written to the i2c device in one go
055     * @param offset offset in buffer 
056     * @param size number of bytes to be written 
057     * 
058     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
059     */
060    void write(byte[] buffer, int offset, int size) throws IOException;
061    
062    /**
063     * This method writes one byte to i2c device.
064     * 
065     * @param address local address in the i2c device
066     * @param b byte to be written
067     * 
068     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
069     */
070    void write(int address, byte b) throws IOException;
071
072    /**
073     * This method writes several bytes to the i2c device from given buffer at given offset.
074     * 
075     * @param address local address in the i2c device
076     * @param buffer buffer of data to be written to the i2c device in one go
077     * @param offset offset in buffer 
078     * @param size number of bytes to be written 
079     * 
080     * @throws IOException thrown in case byte cannot be written to the i2c device or i2c bus
081     */
082    void write(int address, byte[] buffer, int offset, int size) throws IOException;
083
084    /**
085     * This method reads one byte from the i2c device.
086     * Result is between 0 and 255 if read operation was successful, else a negative number for an error.
087     *
088     * @return byte value read: positive number (or zero) to 255 if read was successful. Negative number if reading failed.
089     *
090     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
091     */
092    int read() throws IOException;
093
094    /**
095     * This method reads bytes directly from the i2c device to given buffer at asked offset. 
096     * 
097     * @param buffer buffer of data to be read from the i2c device in one go
098     * @param offset offset in buffer 
099     * @param size number of bytes to be read 
100     * 
101     * @return number of bytes read
102     * 
103     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
104     */
105    int read(byte[] buffer, int offset, int size) throws IOException;
106
107    /**
108     * This method reads one byte from the i2c device.
109     * Result is between 0 and 255 if read operation was successful, else a negative number for an error.
110     *
111     * @param address local address in the i2c device
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(int address) throws IOException;
117
118    /**
119     * This method reads bytes from the i2c device to given buffer at asked offset. 
120     * 
121     * @param address local address in the i2c device
122     * @param buffer buffer of data to be read from the i2c device in one go
123     * @param offset offset in buffer 
124     * @param size number of bytes to be read 
125     * 
126     * @return number of bytes read
127     * 
128     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
129     */
130    int read(int address, byte[] buffer, int offset, int size) throws IOException;
131
132    /**
133     * This method writes and reads bytes to/from the i2c device in a single method call
134     *
135     * @param writeBuffer buffer of data to be written to the i2c device in one go
136     * @param writeOffset offset in write buffer
137     * @param writeSize number of bytes to be written from buffer
138     * @param readBuffer buffer of data to be read from the i2c device in one go
139     * @param readOffset offset in read buffer
140     * @param readSize number of bytes to be read
141     *
142     * @return number of bytes read
143     *
144     * @throws IOException thrown in case byte cannot be read from the i2c device or i2c bus
145     */
146    int read(byte[] writeBuffer, int writeOffset, int writeSize, byte[] readBuffer, int readOffset, int readSize) throws IOException;
147}