Wire
名称
Wireライブラリ
ヘッダーファイル #include <Wire.h> | #include <SoftWire.h> | #include <HardWire.h>
/icons/hr.icon
このページでは、I2CプロトコルのWireライブラリについて説明します。Arduino IDEでこのライブラリを使用するには、Sketch> Import Library ...メニューのWire項目を選択します。
Arduino STM32版のWireライブラリの補足説明
Arduino STM32のWireライブラリは、2つの実装方式のクラスライブラリを提供しています。
HardWireクラス ハードウェア実装版 ヘッダーファイル Wire.h Leaf版ではソフトウェアによるエミュレーション（bit-banged (software) protocol）にて実装されていましたが、
Arduino STM32では、ハードウェアにによる実装版が公開されました。
ハードウェア実装版のHardWireは、STM32のI2C通信ポートとI2C通信機能を利用しています。高速かつ安定した通信ができます。I2C用のポートは最大２つ利用可能です。ソフトウェア実装版は、ハードウェアの制約がないため任意のGPIOピンを使った任意のピンでのI2C通信を行うことが可能です。
ハードウェア実装版とソフトウェア実装版の機能はほぼ同じです。
ヘッダーファイルおよび、インスタンス生成のコードを変更することで、簡単に切り替えることができます。
ハードウェア実装版
code:hardWire_def.c
HardWire MyWire(1);
ヘッダーファイル、Wire.hはHardWireクラスの定義を読み込んでいます。
ソフトウェア実装版
code:hardWire_def.c
TwoWire MyWire;
インスタンス名を同じにすれば、ハードウェア版とソフトウェア版の切り替えが可能です。
定義済みWireオブジェクト
Wireライブラリは、定義済のインスタンスとしてWireオブジェクトが用意されています。
WireオブジェクトはSTM32ボードのI2C1ポートを利用したI2C通信を行うことができます。
I2C2ポートを使った、I2C通信を行いたい場合は、HardWireクラスのインスタンスを別途作成して利用する必要があります。
以下にその定義の例を示します。
code:i2c2.c
Hardwire Wire_2(2);
Arduino STM32のバージョンに関する差異について
Arduino STM32の安定板 R20170323では、定義済みWireオブジェクトは、HardWireクラスのインスタンスではなく、TwoWireクラスのインスタンスとなります。
また、ヘッダーファイル Wire.hは、HardWireクラス定義の読み込みではなく、TwoWireクラスを読み込みます。
安定板でハードウェア実装のI2Cを利用する場合は、ヘッダーファイルHardWire.hを読み込む必要があります。
安定板のWireライブラリのヘッダーファイルとWireオブジェクト
Wire.h ：ソフトウェア実装版I2C（TwoWireクラス） 利用のための定義
HardWire.h ：ハードウェア実装版I2C（HardWireクラス）利用のための定義
Wireオブジェクト：TwoWireクラスのインスタンス
最新版のWireライブラリのヘッダーファイル
Wire.h ：ハードウェア実装版I2C（HardWireクラス）利用のための定義
SoftWire.h ：ソフトウェア実装版I2C（TwoWireクラス）利用のための定義
Wireオブジェクト：HardtWireクラスのインスタンス
Wireライブラリを使ったI2C通信の基本
Wireライブラリを使ったI2C通信を行うための、基本仕様について説明します。
通信クロック周波数
通信クロック周波数は、100kHz、400kHzに対応しています。
通信クロック周波数はデフォルトでは100kHzです。setClock()関数を使って変更が可能です。
I2Cアドレス
通信に利用するI2Cのデバイスアドレスは、Ardunoと互換のある7ビット長のアドレスを利用します。
（コンストラクタにより、10ビット指定も可能ですが動作は未確認です）
電気的な仕様
Arduinoと異なりバス信号の電位は3.3Vです。
ただし、I2CポートはI2C1、I2C2とも5VトレラントであるためI2Cバスの電位を5Vで利用することは可能です。
また、Arduino STM32では、ArduinoのWireとは異なりI2C端子内部プルアップしていません。
I2CバスにI2Cデバイスを接続する場合、外部でのプルアップが必要となります。
プルアップしていないと、確実にフリーズします。
プロトコル的な仕様
Arduino STM32のWireライブラリはスレーブモードをサポートしていません。
従って、STM32ボードをI2Cスレーブとして利用することはできません。
通信処理の実装
I2Cスレーブデバイスとの通信を行うには、I2Cデバイスのスレーブアドレスが必要となります。
一般的なデータの送受信は次の手順となります。
通信速度の設定（setClock()）
バスの利用開始（begin()）
データの送信
送信トランザクションの開始（beginTransmission()）
データ送信（send()）
送信トランザクションの終了（endTransmission()）
データの受信
データ要求（requestFrom()）
データの受信チェック
データ受信
バスの利用終了（end())
バスの利用開始、利用終了は、通信の度に行う必要はありません。スケッチの開始と明示的な終了時にのみ行います。
次のスケッチはI2CスレーブデバイスにI2C接続EEPROM利用した例です。
指定したアドレスへのデータ書き込みとデータ読み込みを行っています。
code:sample.ino
#define DEVICE_ADDRESS 0x50 //I2C EEPROM スレーブアドレス // 1バイト書込
uint8_t write(uint16_t address, uint8_t data) {
uint8_t rc;
Wire.beginTransmission(DEVICE_ADDRESS);
Wire.write((byte)(address >> 8)); // アドレス上位
Wire.write((byte)(address & 0xFF)); // アドレス下位
Wire.write(data);
rc = Wire.endTransmission();
delay(6);
return rc;
}
// 1バイト読込
uint8_t read(unsigned long address) {
Wire.beginTransmission(DEVICE_ADDRESS);
Wire.write((byte)(address >> 8)); // アドレス上位
Wire.write((byte)(address & 0xFF)); // アドレス下位
Wire.endTransmission();
Wire.requestFrom(DEVICE_ADDRESS, 1);
return Wire.read();
}
// 書込みテスト
void write_test() {
unsigned long addr =0;
byte data;
Serial.println("Start Writeing test.");
for (int addr = 0; addr < 10; addr++) {
write(addr, (uint8_t)addr);
data = read(addr) ;
Serial.print("data="); Serial.println(data,DEC);
}
}
void setup(){
Serial.begin(19200);
delay(300);
Wire.begin();
write_test();
Wire.end();
}
void loop() { }
ライブラリ リファレンス
/icons/hr.icon
HardWireクラス class HardWire ヘッダーファイル Wire.h ■ コンストラクタ
書式
HardWire(uint8 dev_sel, uint8 flags=0)
引数
dev_sel ：利用するI2Cデバイスの指定 1:I2C1、2:I2C2
flags ：I2C通信に関する設定
説明
HardWireクラスのインスタンスを作成します。
flagsには次の項目をORで指定できます。
I2C_FAST_MODE ：400kHz高速通信（デフォルトは100kHz）
I2C_DUTY_16_9 ：16/9 Tlow/Thigh duty cycle (only applicable for fast mode),
I2C_BUS_RESET ：初期化時にバスをリセットし、ハングしたスレーブをクロックアウトする,
I2C_10BIT_ADDRESSING ：10ビットアドレスを使用する
I2C_REMAP ：I2C1のピンをSCLをPB8 、SDAをPB9に変更（マッピング）する
コンストラクタでは、I2C通信に関するデバイスの初期化等の設定は行いません。
インスタンスの生成と設定値の保持のみ行っています。
■ デイストラクタ
書式
~HardWire()
引数
なし
説明
I2Cデバイスを解放し、インスタンスを破棄します。
■ バスの利用開始
書式
void begin(uint8 self_addr)
引数
self_addr ：マスタ側のI2Cアドレス
戻り値
なし
説明
I2Cバスの利用を有効にします。STM32ボードをバスマスタとして初期化します。
※ 引数self_addrは、ライブラリでは利用していません。任意の値を指定して下さい。
■ バス利用の終了
書式
void end()
引数
なし
戻り値
なし
説明
I2Cバスの利用を終了します。
■ I2Cバスクロック速度設定
書式
void setClock(uint32_t frequencyHz)
引数
frequencyHz ： 通信クロック周波数(Hz)； 100000 または 400000のみ指定可能
戻り値
なし
説明
I2Cデバイスの通信クロック周波数を設定します。
指定できるクロック周波数は100000（100kHz）、400000（400kHz）のみです。
それ以外の値を指定した場合は、100000（100kHz）を設定します。
この設定は、コンストラクタのflagsで指定するI2C_FAST_MODEと等価です。
■ 送信トランザクションの開始
書式
void beginTransmission(uint8 slave_address)
void beginTransmission(int slave_address)
引数
slave_address ：通信相手のスレーブデバイスのアドレス
戻り値
なし
説明
指定された（7ビット）アドレスを持つスレーブデバイスへの送信を設定します。
int型slave_addressは、uint8にキャストして7ビットアドレスとして処理します。
endTransmission()が呼び出されると、送信待ちのバイト数（wrie()を使用）がslave_addressで指定したスレーブに送信されます。
■ 送信トランザクションの終了
書式
uint8 endTransmission(bool stop)
uint8 endTransmission()
引数
stop ：ストップビット送信の指定 ※現時点ではこの指定のための処理は未実装です。
戻り値
実行結果 0 ～ 4 を返します。次の定数が定義されています。
SUCCESS 0 正常終了
EDATA 1 異常終了（送信キューの容量を超えたデータがキューイングされている）
ENACKADDR 2 異常終了（スレーブアドレスの送信時にNACKを受信した）
ENACKTRNS 3 データの送信時にnackを受信した（これが正常である場合もある）
EOTHER 4 その他のエラー
説明
beginTransmission()によって開始される送信を終了し、
実際には呼び出しによって待機しているバイトデータをスレーブデバイスに送信します。
送信キュー32バイトを超えるキューイングを行った場合、キュー内のデータは送信されずに戻り値としてEDATAが返されます。
■ データ要求
書式
uint8 requestFrom(int slave_address, int numBytes)
uint8 requestFrom(uint8 slave_address, int numBytes)
引数
slave_address ：通信相手のスレーブデバイスのアドレス
numBytes ：要求バイト数
戻り値
要求に対して、読み取られた実際のバイト数
説明
addressで指定した7ビットのスレーブアドレスアドレスのデバイスからnum_bytesバイトのデータを要求します。
要求に対して、読み取られた実際のバイト数を返します。
これらのバイトデータは、その後、read()を使用して一度に1つずつ読み込むことができます。
■ データ送信
書式
void write(uint8 value)
void write(uint8* buf, int len)
void write(int* buf, int len)
void write(int value)
void write(char* buf)
引数
value ：符号無し1バイトデータをキューイングします。int型指定時は下位1バイトをキューイングします。
buf, len ：bufで指定したアドレス先頭からlenバイトをキューイングします
char* buf ：文字列（'\0'(nul)文字を終端）をキューイングします
戻り値
なし
説明
指定されたバイトデータ（uint8、int、バイト列、ワード列、文字列）をbeginTransmission()を呼び出して指定したスレーブアドレスにキューイングします。 最大32バイトは単一の送信でキューに入れられます。
write()では、データ送信は行われません。endTransmission()の呼び出しでキュー内データを一括送信します。
キュー内のデータが32バイトを超えた場合、endTransmission()実行時にEDATAを返し、キュー内のデータは送信されずに破棄されます。
■ 受信データ有無チェック
書式
uint8 available()
引数
なし
戻り値
0 ：受信データなし
0以外 ：受信データあり
説明
requestFrom()の最後の呼び出しから読み取ることができるデータがあるかをチェックします。
データはread()で取得できます。
■ データの読み取り
書式
uint8 read()
引数
なし
戻り値
読み取られたバイトデータ
説明
requestFrom()の呼び出しで読み取られたバイトを取得して返します。
available()を使用して、読み込むバイト数を確認できます。
/icons/hr.icon
■ コンストラクタ
書式
TwoWire(uint8 scl=SCL, uint8 sda=SDA, uint8 delay=SOFT_STANDARD)
引数
scl ：SCLのピン番号（デフォルト：SDA=PB7）
sda ：SCLのピン番号（デフォルト：SCL=PB6）
delay ：バスクロック指定
※delayには次の定数の指定が可能です。
SOFT_STANDARD ：バスクロック100kHz相当（デフォルト）
SOFT_FAST ：バスクロック400kHz相当
説明
TwoWireクラスのインスタンスを作成します。
引数は省略可能です。省略時はハードウェア実装時と同じ利用するGPIOピンを利用します。
コンストラクタでは、I2C通信に関するデバイスの初期化等の設定は行いません。
インスタンスの生成と設定値の保持のみ行っています。
■ デイストラクタ
書式
~TwoWire()
引数
なし
説明
インスタンスの廃棄を行います。
■ バスの利用開始
書式
void begin(uint8 self_addr=0x00)
引数
self_addr ：マスタ側のI2Cアドレス
※ 引数self_addrは、ライブラリでは利用していません。任意の値を指定して下さい。
戻り値
なし
説明
2Cバスの利用を有効にします。
■ バス利用の終了
書式
void end()
引数
なし
戻り値
なし
説明
I2Cバスの利用を終了します。
■ 通信条件設定
書式
void setClock(uint32_t frequencyHz)
引数
frequencyHz ： 通信クロック周波数(Hz)； 100000 または 400000のみ指定可能
戻り値
なし
説明
I2Cデバイスの通信クロック周波数を設定します。
通信クロック周波数に指定できるクロック周波数は100000（100kHz）、400000（400kHz）のみです。
それ以外の値を指定した場合は、100000（100kHz）を設定します。
この設定は、コンストラクタのdelayで指定するSOFT_STANDARD、SOFT_FASTと等価です。
■ 送信トランザクションの開始
書式
void beginTransmission(uint8 slave_address)
void beginTransmission(int slave_address)
引数
slave_address ：通信相手のスレーブデバイスのアドレス
戻り値
なし
説明
指定された（7ビット）アドレスを持つスレーブデバイスへの送信を設定します。
int型slave_addressは、uint8にキャストして7ビットアドレスとして処理します。
endTransmission()が呼び出されると、送信待ちのバイト数（wrie()を使用）がslave_addressに送信されます。
■ 送信トランザクションの終了
書式
uint8 endTransmission(bool stop)
uint8 endTransmission()
引数
stop ：ストップビット送信の指定 ※現時点ではこの指定のための処理は未実装です
戻り値
実行結果 0 ～ 4 を返します。次の定数が定義されています。
SUCCESS 0 正常終了
EDATA 1 異常終了（送信キューの容量を超えたデータがキューイングされている）
ENACKADDR 2 異常終了（スレーブアドレスの送信時にNACKを受信した）
ENACKTRNS 3 データの送信時にnackを受信した（これが正常である場合もある）
EOTHER 4 その他のエラー
説明
（beginTransmission()によって開始される）送信を終了し、
実際には呼び出しによって待機しているバイトデータをスレーブデバイスに送信します。
送信キュー32バイトを超えるキューイングを行った場合、キュー内のデータは送信されずに
戻り値としてEDATAが返されます。
■ データ要求
書式
uint8 requestFrom(int slave_address, int numBytes)
uint8 requestFrom(uint8 slave_address, int numBytes)
引数
slave_address ：通信相手のスレーブデバイスのアドレス
numBytes ：要求バイト数
戻り値
要求に対して、読み取られた実際のバイト数
説明
addressで指定した7ビットのスレーブアドレスアドレスのデバイスからnum_bytesバイトのデータを要求します。
要求に対して、読み取られた実際のバイト数を返します。
これらのバイトデータは、その後、read()を使用して一度に1つずつ読み込むことができます。
■ データ送信
書式
void write(uint8 value)
void write(uint8* buf, int len)
void write(int* buf, int len)
void write(int value)
void write(char* buf)
引数
value ：符号無し1バイトデータをキューイングします。int型指定時は下位1バイトをキューイングします。
buf, len ：bufで指定したアドレス先頭からlenバイトをキューイングします
char* buf ：文字列（'\0'(nul)文字を終端）をキューイングします
戻り値
なし
説明
指定されたバイトデータ（uint8、int、バイト列、ワード列、文字列）をbeginTransmission()を呼び出し、
指定したスレーブアドレスにキューイングします。 最大32バイトは単一の送信でキューに入れられます。
write()では、データ送信は行われません。endTransmission()の呼び出しでキュー内データを一括送信します。
キュー内のデータが32バイトを超えた場合、endTransmission()実行時にEDATAを返し、
キュー内のデータは送信されずに破棄されます。
■ 受信データ有無チェック
書式
uint8 available()
引数
なし
戻り値
0 ：データなし
0以外 ：データあり
説明
requestFrom()の最後の呼び出しから読み取ることができる場合は0以外（実際は受信バイト数）、
そうでない場合は0を返します。データはread()で取得できます。
■ データの読み取り
書式
uint8 read()
引数
なし
戻り値
読み取られたバイトデータ
説明
requestFrom()の呼び出しで読み取られたバイトを取得して返します。
available()を使用して、読み込むバイト数を確認できます。
■ プロトコルエミュレーション関数（bit-banged (software) protocol）
■void set_sda(bool)
SDAバスに値をセットします。
■ void set_scl(bool)
SLCバスに値をセットします。
■ void i2c_start()
スタートビットを送信します。
■ void i2c_stop()
ストップビットを送信します。
■ void i2c_repeated_start()
■ bool i2c_get_ack()
ACKを受信します。
■ void i2c_send_ack()
ACKを送信します。
■ void i2c_send_nack()
NAKを送信します。
■ uint8 i2c_shift_in()
ビット列データを受信します。
■ void i2c_shift_out(uint8)
ビットデータ列を送信します。
関連項目
/icons/hr.icon
このドキュメントはArduino.cc が執筆し、たま吉が翻訳・一部加筆修正したものです。