setWireTimeout()
Last revision:2026/01/24

名称

Wire.setWireTimeout()

説明

setWireTimeout()は、コントローラーモードで利用するときの、通信タイムアウトを設定する。

パラメータなしで呼び出されたときは、デフォルトのタイムアウトが設定される。これは、典型的な単一コントローラ設定でのロックアップを防ぐには十分な値である。

この関数はWireライブラリの一部である。詳細はWireメインページを参照のこと。

書式

  • Wire.setWireTimeout(timeout, reset_on_timeout)
  • Wire.setWireTimeout()

C言語シグネチャ(avr)

void TwoWire::setWireTimeout(uint32_t timeout, bool reset_with_timeout);

引数

timeoutタイムアウト(ミリ秒単位)。0のときは、タイムアウトは無効。デフォルト値は25000。データ型: uint32_t。
reset_on_timeouttrueの場合、タイムアウト時にWireハードウェアを自動リセットする。データ型: bool。

戻り値

なし。

コード例 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#include <Wire.h>

void setup() {
  Wire.begin(); // join i2c bus (address optional for master)
  #if defined(WIRE_HAS_TIMEOUT)
    Wire.setWireTimeout(3000 /* us */, true /* reset_on_timeout */);
  #endif
}

byte x = 0;

void loop() {
  /* First, send a command to the other device */
  Wire.beginTransmission(8); // transmit to device #8
  Wire.write(123);           // send command
  byte error = Wire.endTransmission(); // run transaction
  if (error) {
    Serial.println("Error occured when writing");
    if (error == 5)
      Serial.println("It was a timeout");
  }

  delay(100);

  /* Then, read the result */
  #if defined(WIRE_HAS_TIMEOUT)
  Wire.clearWireTimeoutFlag();
  #endif
  byte len = Wire.requestFrom(8, 1); // request 1 byte from device #8
  if (len == 0) {
    Serial.println("Error occured when reading");
    #if defined(WIRE_HAS_TIMEOUT)
    if (Wire.getWireTimeoutFlag())
      Serial.println("It was a timeout");
    #endif
  }

  delay(100);
}

注意と警告

タイムアウトの理解: タイムアウトは、デバイスの問題や雑音、不十分な絶縁、他の電気的な問題などがおこっていることを示唆する。タイムアウトはスケッチが停止するのを防ぐが、問題を解決するわけではない。このような場合、タイムアウトによっては検出されないデータ破損が発生している可能性もある。このため、タイムアウトが発生したときは、以前に送受信したデータも破損している可能性がある。このような問題をより確実に検出するための手段(チェックサムや書き込んだ値を読み戻す)が必要になるかもしれない。タイムアウトや追加の手段は最終的な防御策であり、本来は根本的な原因を解決する必要がある。

タイムアウトの動作: 典型的には、トランザクションが完了するのを待っているとき(例えば、バスが再度利用可能になるのを待つ、ACKビットを待つ、全トランザクションが終了するのを待つなど)に、タイムアウト条件が発生する。タイムアウト状態がおこると、トランザクションは中断され、Wire.endTransmission()やWire.requestFrom()が、それぞれ、エラーコードやゼロバイトを返す。

ハードウェアリセット: reset_on_timeoutがtrueに設定され、プラットフォームがこれをサポートしている場合は、I2Cハードウェアがリセットされる。これは、I2Cハードウェアモジュール内の不正な状態を解消するのに役立つ。

タイムアウトフラグ: タイムアウトが起こると、Wire.getWireTimeoutFlag()によって検出できるフラグが設定される。これは、Wire.clearWireTimeoutFlag()を使って手動でクリアする必要がある(Wire.setWireTimeout()を呼び出したときにもクリアされる)。

推奨値: 典型的なタイムアウトは25ms(SMBusプロトコルで許されるクロックストレッチの最大値)だが、(かなり)短い値でも通常は動作する。必要に応じて、クロックストレッチやマルチコントローラ構成に対応できるよう、タイムアウト時間を適切に設定すること。

ポータビリティ: この関数はWireライブラリの基のバージョンでは利用できない。また、全てのプラットフォームで利用できるわけでもない。プラットフォームやバージョン間の互換が必要な場合は、Wire.setWireTimeout()とWire.getWireTimeoutFlag()、Wire.clearWireTimeout()が利用できるときにだけ定義されるWIRE_HAS_TIMEOUTマクロを利用する。

デフォルト値: デフォルトのタイムアウト設定は、WIRE_DEFAULT_TIMEOUTとWIRE_DEFAULT_RESET_WITH_TIMEOUTマクロとして利用できる。タイムアウトを無効にするには、現状はデフォルト値ではあるが、setWireTimeout(0)を利用することが推奨されている。

オリジナルのページ

https://docs.arduino.cc/language-reference/en/functions/communication/wire/setWireTimeout/

最終更新日

August 16, 2026

inserted by FC2 system