I2C-RELAY16 Library Reference

Introduction

The Relay16 library was designed to make the Iowa Scaled Engineering I2C-RELAY16 control board easy to use with the ArduinoTM environment. The board itself needs to be connected to the SCL and SDA lines coming out of the Arduino, as well as ground. Optionally, the /IORST (inverted IO reset) line can be connected to a digital I/O pin or just connected to +3.3V or +5V. If the /IORST is left floating, the board will hold itself in a permanent reset state and do nothing. The 6P6C connectors on the board implement the standard Iowa Scaled Engineering 6P6C I2C connector pinout, making it directly compatible with a wide variety of shields we offer with an I2C port.

Setup

You'll need to copy the Relay16 directory (with the Relay16.cpp and Relay16.h files) into your arduino/libraries directory. This is known as "Manual Installation" of an Arduino library. More details can be found in the Arduino - Libraries documentation.

Once the files are there, start your Arduino IDE and you should be able to pick "Relay16" from "Sketch->Import Library..." to add it to your sketch. You'll also likely need to import the stock "Wire" library to get I2C functionality.

Example Sketch

(AKA... Real developers don't read the documentation first, just shut up and show me some code, sparky!)

A sample Arduino sketch that demonstrates some simple uses of the library is available as part of the source package - it's in the "relay16_example" directory. You still need to install the library itself, as described in Setup. Once the library's in place, you should be able to open up the relay16_example.ino sketch and build/upload it. It will cause the relays to turn on, in order, for a quarter of a second. At the end of the cycle, it'll turn on all the relays, then turn them off, and start over.

Source Releases

The latest source code is always available from our GitHub I2C-RELAY16 repository. Look in the src/Relay16 directory.

License

The Relay16 library is copyright 2013 by Nathan Holmes and Michael Petersen. It is free software, licensed under the GNU General Public License v3.

Classes and Structures

class Relay16
{
public:
Relay16();
void begin(boolean j5, boolean j6, boolean j7, char dioResetPin);
void relayOn(byte relayNum);
void relayOff(byte relayNum);
void allOn();
void allOff();
void refresh();
};

Relay16 Class Public Methods / Functions

Relay16::Relay16()

The Relay16::Relay16() constructor takes no arguments, and will initialize the Relay16 object upon creation.


void Relay16::begin(boolean j5, boolean j6, boolean j7, char dioResetPin)

The Relay16::begin() function should be called within the setup() function of your sketch. Input parameters j5, j6, and j7 should be either HIGH or LOW, depending on whether address jumpers for the board are set from center to the pin near the plus sign (HIGH) or center to the pin opposite the plus sign (LOW). Using various combinations of these pins, up to 8 I2C-RELAY16 boards (and therefore 128 relays) can be controlled on a single I2C bus.

If the /IORST line in the 6p6c connector is attached to a digital I/O pin, specify its number here. If it isn't connected, pass in a -1 for the dioResetPin parameter.


byte Relay16::relayOn(byte relayNum)

The Relay16::relayOn() function will turn on an individual relay (numbered 1 to 16) without affecting the state of the other relays.


byte Relay16::relayOff(byte relayNum)

The Relay16::relayOff() function will turn off an individual relay (numbered 1 to 16) without affecting the state of the other relays.


byte Relay16::allOn()

The Relay16::allOn() function will turn on all 16 relays on an individual board at once.


byte Relay16::allOff()

The Relay16::allOff() function will turn off all 16 relays on an individual board at once.


byte Relay16::refresh()

The Relay16::refresh() function will send the current on/off configuration over the I2C bus to the relay board again. This can be useful if the I2C bus has to be reset for some reason.