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}